SYSTEM DIRECTIVE: Global Schema `{{MASTER_REPO}}`

[ROLE] You are the Orchestrator AI for the Knowledge Genome network. This file defines global architecture, cross-genome boundary rules, and security protocols. Read it before any cross-genome session.

1. Architecture & Boundaries

{{MASTER_REPO}}/
├── core-karpathy/      ← Reference pattern — read-only, never modify
├── genome-dev/         ← Submodule: web development, Angular, TUI
├── genome-finance/     ← Submodule: personal finance (git-crypt on private/)
├── genome-homelab/     ← Submodule: Keru infrastructure and network
└── AGENTS.md           ← This file

Each genome submodule has its own AGENTS.md with domain-specific rules.

Critical boundary rules:

Single-domain focus: Operate within ONE genome at a time. Do not attempt atomic commits across multiple genomes in the same operation.
Cross-genome references: Use relative bi-directional wikilinks only:
```
[[../genome-target/wiki/folder/target-page]]
```
Read-only cores: Any repository prefixed core-* is a reference architecture. Never commit to it. To update core-karpathy to the latest gist commit:
```
git submodule update --remote core-karpathy
git add core-karpathy
git commit -m "chore: update core-karpathy to latest gist"
```

2. Global Security Protocol

Zero-Disk Key Policy

Never write, suggest, or generate scripts that save .key files to disk.

Symmetric keys are injected at runtime via Vaultwarden (bw CLI) through memory pipelines using process substitution:

bw config server {{VAULTWARDEN_URL}}
export BW_SESSION=$(bw unlock --passwordenv BW_MASTER_PASSWORD --raw)
git-crypt unlock <(bw get notes "genome-dev key" --session "$BW_SESSION" | base64 -d)

Use bw, not bws. bws is the Bitwarden Secrets Manager CLI — a separate commercial product that Vaultwarden does NOT implement.

Log Sanitisation

Never print decrypted secrets, BW_SESSION tokens, or git-crypt key contents to stdout or log files.
If an operation requires a key, document only the run_id and the genome name, not the key value or session token.

PRIVATE_CONTEXT scope

The PRIVATE_CONTEXT toggle is per-genome and per-session. Enabling it for genome-finance does NOT enable it for genome-dev.
Cloud LLM models must never be used when PRIVATE_CONTEXT is enabled for any genome. Private data must not leave the local network.

3. Cross-Genome Lint (Monthly)

The goal is to detect concept duplication and semantic overlap across genomes. This is a manual, monthly operation — not an automated CI/CD step — because it requires judgement and has a cost in tokens.

Procedure:

Collect the wiki/index.md from every active genome.

Pass the aggregated index to the agent with this prompt:

Compare these indices and identify:
a) Concepts defined in two or more genomes with potentially conflicting definitions.
b) Entities (tools, people, organisations) referenced across genomes without
   a canonical cross-genome wikilink.
c) Concepts in genome-X that should link to genome-Y but don't.
Report findings. Do not modify any files.

For each finding, create a cross-genome conflict note in the genome where the resolution should live, following the conflict format in that genome's AGENTS.md.
Log the lint pass in the master AGENTS.md update history (below).

4. Submodule Operations

# Update all genomes to their latest main commit
git submodule update --remote

# Initialise all submodules after a fresh clone
git submodule update --init --recursive

# Record updated submodule pointers
git add .
git commit -m "chore: update submodule pointers"
git push

5. Adding a New Genome

# 1. Scaffold and push the genome repo
make add-genome NAME=genome-newname DESC="Domain description"

# 2. Register it as a submodule in the master
git submodule add {{FORGEJO_URL}}/{{FORGEJO_USER}}/genome-newname.git genome-newname
git add .gitmodules genome-newname
git commit -m "feat: add genome-newname submodule"
git push

# 3. Update this file's architecture diagram in Section 1

6. Cloning

# Full clone with all submodules
git clone --recurse-submodules \
  {{FORGEJO_URL}}/{{FORGEJO_USER}}/{{MASTER_REPO}}.git

# Unlock a genome after cloning (manual key file)
cd {{MASTER_REPO}}/genome-dev
git-crypt unlock /path/to/genome-dev.key

# Unlock on AI server without writing key to disk
bw config server {{VAULTWARDEN_URL}}
export BW_SESSION=$(bw unlock --passwordenv BW_MASTER_PASSWORD --raw)
git-crypt unlock <(bw get notes "genome-dev key" --session "$BW_SESSION" | base64 -d)

# Sparse clone — collaborator who needs only one genome
git clone {{FORGEJO_URL}}/{{FORGEJO_USER}}/genome-dev.git

7. Key Rotation (Emergency Procedure)

If a git-crypt key is lost or compromised, run the rotation function:

# From the project root (knowledge-genome-setup/)
source lib/git-crypt.sh
cd ~/knowledge-genome-setup/genome-dev
gcrypt_rotate_key "genome-dev"

gcrypt_rotate_key performs: decrypt all private files → generate new key → re-encrypt → export new key → print Vaultwarden update instructions.

After rotation, update the Secure Note in Vaultwarden with the new base64-encoded key and revoke access from any previous key holders.

8. Key Management Reference

Genome	Vaultwarden Secure Note	Key file (temporary)
genome-dev	`genome-dev key`	`keys/genome-dev.key`
genome-finance	`genome-finance key`	`keys/genome-finance.key`
genome-homelab	`genome-homelab key`	`keys/genome-homelab.key`

Key files in keys/ are temporary exports only. Delete them after uploading to Vaultwarden.

5.8 KiB Raw Blame History

SYSTEM DIRECTIVE: Global Schema {{MASTER_REPO}}