knowledge-genome-orchestrator/templates/agents-master.md

# 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

```text
{{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:
  ```text
  [[../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:
  ```bash
  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:
  ```bash
  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:**
1. Collect the `wiki/index.md` from every active genome.
2. Pass the aggregated index to the agent with this prompt:
   ```text
   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.
   ```
3. 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`.
4. Log the lint pass in the master `AGENTS.md` update history (below).

---

## 4. Submodule Operations

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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.