Keru/knowledge-genome-orchestrator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: improve readability and consistency across other documentation

Browse source
This commit is contained in:
Matteo Cherubini 2026-06-03 12:28:19 +02:00
parent 2e06d8f4e8
commit 33697e9b82
5 changed files with 154 additions and 111 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

201
README.md
View file

@ -49,6 +49,7 @@ evolving synthesis. Knowledge is compiled once and kept current.
Contradictions have been flagged. The synthesis already reflects everything ingested. Contradictions have been flagged. The synthesis already reflects everything ingested.
This means: This means:
- No vector database. - No vector database.
- No embedding pipeline. - No embedding pipeline.
- No external retrieval infrastructure. - No external retrieval infrastructure.
@ -103,11 +104,11 @@ genome-{name}/
### Three layers ### Three layers
| Layer | Path | Owner | Rule | | Layer | Path | Owner | Rule |
|-------|------|-------|------| | ----------- | ----------- | ----------- | ----------------------------------------------------- |
| Raw sources | `raw/` | Human | Immutable. LLM reads only. Never modified. | | Raw sources | `raw/` | Human | Immutable. LLM reads only. Never modified. |
| Wiki | `wiki/` | LLM | Agent creates, updates, cross-links, maintains. | | Wiki | `wiki/` | LLM | Agent creates, updates, cross-links, maintains. |
| Schema | `AGENTS.md` | Human + LLM | Co-evolved contract defining structure and workflows. | | Schema | `AGENTS.md` | Human + LLM | Co-evolved contract defining structure and workflows. |
### Framework structure ### Framework structure
@ -154,6 +155,7 @@ All tools (git-crypt, bw, qmd) have native Linux binaries.
### macOS — full support ### macOS — full support
All scripts are compatible with macOS. Requirements: All scripts are compatible with macOS. Requirements:
- bash 3.2+ (macOS default) — fully supported. All `bash 4+` constructs removed. - bash 3.2+ (macOS default) — fully supported. All `bash 4+` constructs removed.
- GNU coreutils not required — BSD variants of `date`, `grep`, `sed` all handled. - GNU coreutils not required — BSD variants of `date`, `grep`, `sed` all handled.
- `git-crypt`: install via Homebrew — `brew install git-crypt` - `git-crypt`: install via Homebrew — `brew install git-crypt`
@ -166,6 +168,7 @@ If you use Homebrew bash (`brew install bash`), the scripts work identically to
**Git Bash and native Windows are not supported.** **Git Bash and native Windows are not supported.**
Reasons: Reasons:
- `git-crypt` has no native Windows binary. - `git-crypt` has no native Windows binary.
- Process substitution `<(...)` used for runtime key injection is not available - Process substitution `<(...)` used for runtime key injection is not available
in Git Bash or PowerShell. in Git Bash or PowerShell.
@ -179,13 +182,13 @@ All setup and runtime operations work identically to native Linux inside WSL2.
The system is designed for a homelab architecture: The system is designed for a homelab architecture:
| Component | Recommended | Role | | Component | Recommended | Role |
|-----------|-------------|------| | --------------- | ------------------------- | --------------------------------------------------------------- |
| Storage node | Any Linux server with NFS | Hosts Forgejo, stores genome repos | | Storage node | Any Linux server with NFS | Hosts Forgejo, stores genome repos |
| AI compute node | GPU server (16GB+ VRAM) | Runs local LLM agent sessions | | AI compute node | GPU server (16GB+ VRAM) | Runs local LLM agent sessions |
| VRAM | 16GB minimum | 14B model at Q5_K_M ≈ 10GB weights; ~6GB for KV cache | | VRAM | 16GB minimum | 14B model at Q5_K_M ≈ 10GB weights; ~6GB for KV cache |
| Local LLM | 14B–32B quantised | Active wiki maintenance sessions | | Local LLM | 14B–32B quantised | Active wiki maintenance sessions |
| Large LLM | 70B (async) | Deep reflection, complex synthesis (scheduled, not interactive) | | Large LLM | 70B (async) | Deep reflection, complex synthesis (scheduled, not interactive) |
> **On VRAM constraints:** with a 16GB card and a 14B model, the KV cache budget > **On VRAM constraints:** with a 16GB card and a 14B model, the KV cache budget
> is ~6GB — approximately 32k tokens of effective context. Every token in `AGENTS.md`, > is ~6GB — approximately 32k tokens of effective context. Every token in `AGENTS.md`,
@ -198,18 +201,18 @@ The system is designed for a homelab architecture:
### Required ### Required
| Tool | Purpose | | Tool | Purpose |
|------|---------| | ----------- | -------------------------------- |
| `git` | Version control | | `git` | Version control |
| `git-crypt` | Transparent file encryption | | `git-crypt` | Transparent file encryption |
| `curl` | REST API calls to Forgejo/GitHub | | `curl` | REST API calls to Forgejo/GitHub |
| `jq` | JSON parsing | | `jq` | JSON parsing |
### Optional ### Optional
| Tool | Purpose | | Tool | Purpose |
|------|---------| | ----- | ----------------------------------------------------------------------- |
| `bw` | Bitwarden CLI — runtime key injection from Vaultwarden (no key on disk) | | `bw` | Bitwarden CLI — runtime key injection from Vaultwarden (no key on disk) |
| `qmd` | Local BM25 + vector search for Markdown files with MCP server interface | | `qmd` | Local BM25 + vector search for Markdown files with MCP server interface |
> **`bw` vs `bws`:** Use `bw` (standard Bitwarden CLI). `bws` is the Bitwarden > **`bw` vs `bws`:** Use `bw` (standard Bitwarden CLI). `bws` is the Bitwarden
@ -347,6 +350,7 @@ make setup
- Commits submodule pointer in master repo - Commits submodule pointer in master repo
After setup completes: After setup completes:
- Upload all files in `keys/` to Vaultwarden (see Key Management) - Upload all files in `keys/` to Vaultwarden (see Key Management)
- Delete key files from disk: `rm keys/*.key` - Delete key files from disk: `rm keys/*.key`
@ -354,16 +358,16 @@ After setup completes:
## Makefile Reference ## Makefile Reference
| Target | Description | | Target | Description |
|--------|-------------| | --------------------------------- | ------------------------------------------------------------------------------ |
| `make setup` | Full system initialisation — master repo + all genomes in `registry.sh` | | `make setup` | Full system initialisation — master repo + all genomes in `registry.sh` |
| `make add-genome NAME=x DESC="y"` | Scaffold and register a single new genome | | `make add-genome NAME=x DESC="y"` | Scaffold and register a single new genome |
| `make lint` | Run quality checks across all genomes (schema, privacy, decay, page size) | | `make lint` | Run quality checks across all genomes (schema, privacy, decay, page size) |
| `make status` | Show submodule status and first 10 git-crypt encryption states | | `make status` | Show submodule status and first 10 git-crypt encryption states |
| `make lock` | Lock all encrypted repos (master + all genome submodules) | | `make lock` | Lock all encrypted repos (master + all genome submodules) |
| `make doctor` | Verify required tools: git, git-crypt, curl, jq; warn if bw missing | | `make doctor` | Verify required tools: git, git-crypt, curl, jq; warn if bw missing |
| `make sync` | `git submodule update --init --recursive` + report unpushed commits per genome | | `make sync` | `git submodule update --init --recursive` + report unpushed commits per genome |
| `make help` | Print all available targets | | `make help` | Print all available targets |
### Examples ### Examples
@ -407,6 +411,7 @@ After adding: upload the new key to Vaultwarden and delete the key file.
### Removing a genome ### Removing a genome
Manual process: Manual process:
```bash ```bash
# In master repo # In master repo
git submodule deinit genome-name git submodule deinit genome-name
@ -421,16 +426,16 @@ git push
When a genome is scaffolded, `render_template` replaces these placeholders in all When a genome is scaffolded, `render_template` replaces these placeholders in all
template files: template files:
| Placeholder | Source | Example | | Placeholder | Source | Example |
|-------------|--------|---------| | ----------------------- | ----------- | ------------------------------ |
| `{{GENOME_NAME}}` | registry.sh | `genome-dev` | | `{{GENOME_NAME}}` | registry.sh | `genome-dev` |
| `{{GENOME_NAME_UPPER}}` | derived | `GENOME-DEV` | | `{{GENOME_NAME_UPPER}}` | derived | `GENOME-DEV` |
| `{{GENOME_DESC}}` | registry.sh | `Web development...` | | `{{GENOME_DESC}}` | registry.sh | `Web development...` |
| `{{FORGEJO_URL}}` | globals.env | `https://git.yourserver.com` | | `{{FORGEJO_URL}}` | globals.env | `https://git.yourserver.com` |
| `{{FORGEJO_USER}}` | globals.env | `yourusername` | | `{{FORGEJO_USER}}` | globals.env | `yourusername` |
| `{{VAULTWARDEN_URL}}` | globals.env | `https://vault.yourserver.com` | | `{{VAULTWARDEN_URL}}` | globals.env | `https://vault.yourserver.com` |
| `{{MASTER_REPO}}` | globals.env | `master-knowledge-genome` | | `{{MASTER_REPO}}` | globals.env | `master-knowledge-genome` |
| `{{DATE}}` | runtime | `2026-05-11` | | `{{DATE}}` | runtime | `2026-05-11` |
--- ---
@ -441,9 +446,9 @@ template files:
Each genome uses a unique symmetric AES-256-CTR key managed by git-crypt. Each genome uses a unique symmetric AES-256-CTR key managed by git-crypt.
Two directories in every genome are always encrypted: Two directories in every genome are always encrypted:
| Directory | Contents | On remote | | Directory | Contents | On remote |
|-----------|----------|-----------| | --------------- | --------------------------- | ------------------ |
| `raw/private/` | Sensitive source material | Opaque binary blob | | `raw/private/` | Sensitive source material | Opaque binary blob |
| `wiki/private/` | Private synthesis and notes | Opaque binary blob | | `wiki/private/` | Private synthesis and notes | Opaque binary blob |
All other directories (`raw/articles/`, `wiki/sources/`, etc.) are plaintext. All other directories (`raw/articles/`, `wiki/sources/`, etc.) are plaintext.
@ -502,6 +507,7 @@ PRIVATE_CONTEXT: enabled ← Agent may read/write private/. Requires git-cryp
``` ```
Rules: Rules:
- Never inferred. Never carried over from a previous session. - Never inferred. Never carried over from a previous session.
- `enabled` requires the operator to confirm that `git-crypt unlock` has run on the host. - `enabled` requires the operator to confirm that `git-crypt unlock` has run on the host.
- Per-genome, per-session: enabling for `genome-finance` does NOT enable for `genome-dev`. - Per-genome, per-session: enabling for `genome-finance` does NOT enable for `genome-dev`.
@ -530,6 +536,7 @@ The key flows: Vaultwarden → `bw get notes` → `base64 -d` → kernel pipe
At no point is the key written to any file on disk. At no point is the key written to any file on disk.
Lock a genome when the session ends: Lock a genome when the session ends:
```bash ```bash
git-crypt lock git-crypt lock
``` ```
@ -544,11 +551,11 @@ git-crypt lock
Each genome key is stored as a base64-encoded Secure Note in Vaultwarden: Each genome key is stored as a base64-encoded Secure Note in Vaultwarden:
| Genome | Vaultwarden Note Name | | Genome | Vaultwarden Note Name |
|--------|----------------------| | ---------------- | --------------------- |
| `genome-dev` | `genome-dev key` | | `genome-dev` | `genome-dev key` |
| `genome-finance` | `genome-finance key` | | `genome-finance` | `genome-finance key` |
| `genome-homelab` | `genome-homelab key` | | `genome-homelab` | `genome-homelab key` |
After `make setup` or `make add-genome`, key files are exported to `keys/`. After `make setup` or `make add-genome`, key files are exported to `keys/`.
Upload procedure: Upload procedure:
@ -593,6 +600,7 @@ gcrypt_rotate_key "genome-dev"
``` ```
`gcrypt_rotate_key` performs: `gcrypt_rotate_key` performs:
1. Unlocks repo with existing key 1. Unlocks repo with existing key
2. Removes old key material 2. Removes old key material
3. Generates new symmetric key via `git-crypt init` 3. Generates new symmetric key via `git-crypt init`
@ -603,13 +611,16 @@ gcrypt_rotate_key "genome-dev"
> **Limitation:** git history still contains blobs encrypted with the old key. > **Limitation:** git history still contains blobs encrypted with the old key.
> Anyone with the old key and git history access can decrypt them. To purge old > Anyone with the old key and git history access can decrypt them. To purge old
> encrypted blobs from history: > encrypted blobs from history:
>
> ```bash > ```bash
> git filter-repo --invert-paths --path raw/private --path wiki/private > git filter-repo --invert-paths --path raw/private --path wiki/private
> git push --force origin main > git push --force origin main
> ``` > ```
>
> This rewrites all commit hashes — coordinate with any collaborators first. > This rewrites all commit hashes — coordinate with any collaborators first.
After rotation: After rotation:
- Upload new key to Vaultwarden (replace existing note) - Upload new key to Vaultwarden (replace existing note)
- Delete both `keys/genome-dev.key` and `keys/genome-dev-rotated-*.key` from disk - Delete both `keys/genome-dev.key` and `keys/genome-dev-rotated-*.key` from disk
- Revoke access from previous key holders - Revoke access from previous key holders
@ -621,6 +632,7 @@ After rotation:
### Prerequisites for every session ### Prerequisites for every session
Before starting an LLM agent session on a genome: Before starting an LLM agent session on a genome:
1. The host (AI server) runs `git-crypt unlock` for the required genomes 1. The host (AI server) runs `git-crypt unlock` for the required genomes
2. The orchestrator prepares context: `tail -n 20 wiki/log.md` 2. The orchestrator prepares context: `tail -n 20 wiki/log.md`
3. Declare `PRIVATE_CONTEXT` state explicitly in the opening prompt 3. Declare `PRIVATE_CONTEXT` state explicitly in the opening prompt
@ -651,6 +663,7 @@ sequentially — not one session with 5 files.
### n8n automation ### n8n automation
For Forgejo webhook → automated ingest: For Forgejo webhook → automated ingest:
1. Forgejo sends webhook on push to `raw/` 1. Forgejo sends webhook on push to `raw/`
2. n8n receives webhook, identifies new files 2. n8n receives webhook, identifies new files
3. n8n starts one agent session per new file (sequential, not parallel) 3. n8n starts one agent session per new file (sequential, not parallel)
@ -677,6 +690,7 @@ Triggered by a new file in `raw/` (manual or via webhook).
9. Commit on `feat/ai-ingest-<slug>`; open PR using `templates/pr-description.md` 9. Commit on `feat/ai-ingest-<slug>`; open PR using `templates/pr-description.md`
For private sources (`PRIVATE_CONTEXT: enabled` required): For private sources (`PRIVATE_CONTEXT: enabled` required):
- All output goes to `wiki/private/<slug>.md` only - All output goes to `wiki/private/<slug>.md` only
- PR title: `[PRIVATE] ingest: <slug>` - PR title: `[PRIVATE] ingest: <slug>`
@ -697,11 +711,13 @@ For general orientation without a specific query: read `wiki/index.md` directly.
The lint workflow is split between deterministic bash checks and semantic LLM judgment. The lint workflow is split between deterministic bash checks and semantic LLM judgment.
**Step 1 — operator runs bash linter:** **Step 1 — operator runs bash linter:**
```bash ```bash
make lint make lint
``` ```
The bash linter checks automatically: The bash linter checks automatically:
- YAML frontmatter validity (all mandatory fields present) - YAML frontmatter validity (all mandatory fields present)
- Domain consistency (domain field matches genome name) - Domain consistency (domain field matches genome name)
- Type validity (value from allowed list) - Type validity (value from allowed list)
@ -713,6 +729,7 @@ The bash linter checks automatically:
**Step 2 — operator provides bash output to LLM agent:** **Step 2 — operator provides bash output to LLM agent:**
The agent applies semantic judgment to findings the bash linter cannot make: The agent applies semantic judgment to findings the bash linter cannot make:
- **Orphan pages** (from bash list): for each orphan, identify 1-3 existing pages - **Orphan pages** (from bash list): for each orphan, identify 1-3 existing pages
that should link to it; propose specific additions that should link to it; propose specific additions
- **Implicit concepts** (from bash term frequency list): determine if a candidate - **Implicit concepts** (from bash term frequency list): determine if a candidate
@ -735,22 +752,28 @@ The PR description uses `templates/pr-description.md`:
```markdown ```markdown
## Summary ## Summary
One sentence: goal of this session and source processed. One sentence: goal of this session and source processed.
## Pages Created ## Pages Created
| Path | Type | Maturity | | Path | Type | Maturity |
## Pages Modified ## Pages Modified
| Path | Change | | Path | Change |
## Contradictions Found ## Contradictions Found
[ ] None / [ ] n conflict file(s) created
[ ] None / [ ] n conflict file(s) created
## Private Data Accessed ## Private Data Accessed
[ ] No (PRIVATE_CONTEXT: disabled) / [ ] Yes
[ ] No (PRIVATE_CONTEXT: disabled) / [ ] Yes
## Scoped Lint (post-ingest) ## Scoped Lint (post-ingest)
[ ] Frontmatter valid [ ] No broken links [ ] No issues found
[ ] Frontmatter valid [ ] No broken links [ ] No issues found
``` ```
This makes human review fast and structured: read the table, scan the diff, This makes human review fast and structured: read the table, scan the diff,
@ -776,10 +799,10 @@ The operator resolves the conflict, updates relevant pages, closes the PR.
Pages have a `last_updated` field in frontmatter. During lint passes: Pages have a `last_updated` field in frontmatter. During lint passes:
| Maturity | Threshold | Action | | Maturity | Threshold | Action |
|----------|-----------|--------| | -------- | --------- | -------------------------------------- |
| `stable` | 180 days | Flag as stale — add `⚠️ STALE` callout | | `stable` | 180 days | Flag as stale — add `⚠️ STALE` callout |
| `draft` | 90 days | Flag as stale — add `⚠️ STALE` callout | | `draft` | 90 days | Flag as stale — add `⚠️ STALE` callout |
The agent proposes re-validation but does not change `maturity` without new source evidence. The agent proposes re-validation but does not change `maturity` without new source evidence.
@ -816,47 +839,47 @@ private: true | false
--- ---
``` ```
| Field | Rules | | Field | Rules |
|-------|-------| | ---------------------- | ------------------------------------------------------------------------ |
| `type` | Must be one of: `source entity concept query conflict private index log` | | `type` | Must be one of: `source entity concept query conflict private index log` |
| `maturity: draft` | Single source or unvalidated | | `maturity: draft` | Single source or unvalidated |
| `maturity: stable` | Confirmed by 2+ independent sources | | `maturity: stable` | Confirmed by 2+ independent sources |
| `maturity: deprecated` | Superseded — add `> **DEPRECATED:** <reason>` callout at top | | `maturity: deprecated` | Superseded — add `> **DEPRECATED:** <reason>` callout at top |
| `private: true` | Required on all pages in `wiki/private/` and `raw/private/` | | `private: true` | Required on all pages in `wiki/private/` and `raw/private/` |
Do not use semantic versioning for content. Git history tracks every change. Do not use semantic versioning for content. Git history tracks every change.
`maturity` captures epistemic state; `last_updated` tracks recency. `maturity` captures epistemic state; `last_updated` tracks recency.
### Page types and directories ### Page types and directories
| Type | Directory | Description | | Type | Directory | Description |
|------|-----------|-------------| | ---------- | ---------------------------- | -------------------------------------------- |
| `source` | `wiki/sources/` | One page per processed raw source | | `source` | `wiki/sources/` | One page per processed raw source |
| `entity` | `wiki/entities/` | People, tools, organisations, projects | | `entity` | `wiki/entities/` | People, tools, organisations, projects |
| `concept` | `wiki/concepts/` | Patterns, theories, architectural decisions | | `concept` | `wiki/concepts/` | Patterns, theories, architectural decisions |
| `query` | `wiki/queries/` | Preserved answers and analyses | | `query` | `wiki/queries/` | Preserved answers and analyses |
| `conflict` | `wiki/queries/conflict-*.md` | Unresolved contradictions | | `conflict` | `wiki/queries/conflict-*.md` | Unresolved contradictions |
| `private` | `wiki/private/` | Private synthesis (PRIVATE_CONTEXT: enabled) | | `private` | `wiki/private/` | Private synthesis (PRIVATE_CONTEXT: enabled) |
| `index` | `wiki/index.md` | Primary navigation catalog (singleton) | | `index` | `wiki/index.md` | Primary navigation catalog (singleton) |
| `log` | `wiki/log.md` | Operations ledger (singleton) | | `log` | `wiki/log.md` | Operations ledger (singleton) |
### Page size limits ### Page size limits
| Limit | Lines | Action | | Limit | Lines | Action |
|-------|-------|--------| | -------- | ----- | ----------------------------------- |
| Soft cap | 400 | Bash linter warns | | Soft cap | 400 | Bash linter warns |
| Hard cap | 800 | Bash linter errors — split the page | | Hard cap | 800 | Bash linter errors — split the page |
These limits ensure pages fit within the LLM context window without attention degradation These limits ensure pages fit within the LLM context window without attention degradation
and keep the wiki atomically navigable. and keep the wiki atomically navigable.
### Linking conventions ### Linking conventions
| Type | Format | | Type | Format |
|------|--------| | ---------------------- | ------------------------------------------- |
| Internal (same genome) | `[[folder/slug]]` — Obsidian wikilinks only | | Internal (same genome) | `[[folder/slug]]` — Obsidian wikilinks only |
| Cross-genome | `[[../genome-target/wiki/folder/slug]]` | | Cross-genome | `[[../genome-target/wiki/folder/slug]]` |
| External | `[text](https://url)` — standard Markdown | | External | `[text](https://url)` — standard Markdown |
Never use `[text](relative/path)` for internal references. Obsidian wikilinks are Never use `[text](relative/path)` for internal references. Obsidian wikilinks are
bidirectional and appear in the graph view. bidirectional and appear in the graph view.
@ -878,6 +901,7 @@ Every operation appends one entry to `wiki/log.md`:
Valid TYPEs: `INGEST` `LINT` `QUERY` `CONFLICT` `CONFIG` `SECURITY` Valid TYPEs: `INGEST` `LINT` `QUERY` `CONFLICT` `CONFIG` `SECURITY`
Parse examples: Parse examples:
```bash ```bash
grep "^## \[" wiki/log.md | tail -5 # Last 5 entries grep "^## \[" wiki/log.md | tail -5 # Last 5 entries
grep "^## \[" wiki/log.md | grep "CONFLICT" # All conflicts grep "^## \[" wiki/log.md | grep "CONFLICT" # All conflicts
@ -891,12 +915,12 @@ The LLM never loads the full log.
## Collaboration Model ## Collaboration Model
| Role | Key access | Permitted operations | | Role | Key access | Permitted operations |
|------|-----------|----------------------| | -------------- | ----------------- | ----------------------------------------------------------------------------- |
| Owner | Full — key holder | Read/write everywhere | | Owner | Full — key holder | Read/write everywhere |
| Collaborator | None | Push to `raw/articles/`, `raw/transcripts/`, `raw/code-packs/`, `raw/assets/` | | Collaborator | None | Push to `raw/articles/`, `raw/transcripts/`, `raw/code-packs/`, `raw/assets/` |
| Local AI agent | Conditional | `private/` only when `PRIVATE_CONTEXT: enabled` | | Local AI agent | Conditional | `private/` only when `PRIVATE_CONTEXT: enabled` |
| Cloud AI model | Never | `PRIVATE_CONTEXT` must be `disabled`; private data stays on local network | | Cloud AI model | Never | `PRIVATE_CONTEXT` must be `disabled`; private data stays on local network |
Grant collaborator access: add as Forgejo contributor with Write role. Grant collaborator access: add as Forgejo contributor with Write role.
Never share the git-crypt key — collaborators operate exclusively in public directories. Never share the git-crypt key — collaborators operate exclusively in public directories.
@ -930,6 +954,7 @@ qmd serve --port 3333
Obsidian is the recommended wiki browser. Open any genome directory as an Obsidian vault. Obsidian is the recommended wiki browser. Open any genome directory as an Obsidian vault.
Recommended setup: Recommended setup:
- **Graph view** — visualise page connections; spot orphans and hubs instantly - **Graph view** — visualise page connections; spot orphans and hubs instantly
- **Obsidian Web Clipper** — browser extension to clip articles directly to `raw/articles/` - **Obsidian Web Clipper** — browser extension to clip articles directly to `raw/articles/`
as Markdown as Markdown
@ -991,6 +1016,7 @@ sudo apt install git git-crypt curl jq
The staged file is in a path matching `**/private/**` but is not encrypted. The staged file is in a path matching `**/private/**` but is not encrypted.
Fix options: Fix options:
1. Verify `.gitattributes` contains `**/private/** filter=git-crypt diff=git-crypt -text` 1. Verify `.gitattributes` contains `**/private/** filter=git-crypt diff=git-crypt -text`
2. Run `git-crypt init` if git-crypt is not initialised in this repo 2. Run `git-crypt init` if git-crypt is not initialised in this repo
3. Run `git-crypt status` to check the encryption state of all files 3. Run `git-crypt status` to check the encryption state of all files
@ -1011,6 +1037,7 @@ git commit -m "fix: re-stage private files for encryption"
### Agent returns stale or missing cross-references ### Agent returns stale or missing cross-references
Likely causes: Likely causes:
1. Session was too long — KV cache degraded. Use one source per session. 1. Session was too long — KV cache degraded. Use one source per session.
2. `wiki/index.md` was not read at session start — agent lacked the page catalog. 2. `wiki/index.md` was not read at session start — agent lacked the page catalog.
3. qmd index is stale — re-index: `qmd index <genome>/wiki/` 3. qmd index is stale — re-index: `qmd index <genome>/wiki/`

16
templates/agents-master.md
View file

@ -2,10 +2,10 @@
## Identity ## Identity
| Field | Value | | Field | Value |
|--------|-------| | ------ | -------------------------------------------------- |
| Repo | `{{MASTER_REPO}}` | | Repo | `{{MASTER_REPO}}` |
| Owner | `{{FORGEJO_USER}}` | | Owner | `{{FORGEJO_USER}}` |
| Remote | `{{FORGEJO_URL}}/{{FORGEJO_USER}}/{{MASTER_REPO}}` | | Remote | `{{FORGEJO_URL}}/{{FORGEJO_USER}}/{{MASTER_REPO}}` |
**Role:** Cross-genome coordinator for the Knowledge Genome network. **Role:** Cross-genome coordinator for the Knowledge Genome network.
@ -32,14 +32,17 @@ Genome-level operations are governed by the genome's `AGENTS.md`, not this file.
## Global Security Rules ## Global Security Rules
### PRIVATE_CONTEXT scope ### PRIVATE_CONTEXT scope
- Toggle is **per-genome and per-session**. Enabling for `genome-finance` does NOT enable for `genome-dev`. - Toggle is **per-genome and per-session**. Enabling for `genome-finance` does NOT enable for `genome-dev`.
- Cloud LLM models: `PRIVATE_CONTEXT` must be `disabled` for all genomes. Private data never leaves the local network. - Cloud LLM models: `PRIVATE_CONTEXT` must be `disabled` for all genomes. Private data never leaves the local network.
### Log sanitization ### Log sanitization
- Never print decrypted secrets, session tokens, or key contents to stdout or log files. - Never print decrypted secrets, session tokens, or key contents to stdout or log files.
- Document only `run_id` and genome name — never the key value. - Document only `run_id` and genome name — never the key value.
### Key management ### Key management
- Key injection is the host's responsibility — executed before this session starts. - Key injection is the host's responsibility — executed before this session starts.
- Never write, suggest, or generate scripts that save `.key` files to disk. - Never write, suggest, or generate scripts that save `.key` files to disk.
@ -54,12 +57,14 @@ Genome-level operations are governed by the genome's `AGENTS.md`, not this file.
5. Per-genome `AGENTS.md` governs all wiki operations within that genome. This file governs boundaries only. 5. Per-genome `AGENTS.md` governs all wiki operations within that genome. This file governs boundaries only.
### NEVER ### NEVER
- Load multiple `wiki/index.md` files simultaneously for cross-genome comparison — use qmd. - Load multiple `wiki/index.md` files simultaneously for cross-genome comparison — use qmd.
- Run `git-crypt`, `bw`, or Vaultwarden commands — host responsibility. - Run `git-crypt`, `bw`, or Vaultwarden commands — host responsibility.
- Modify files in more than one genome in the same operation. - Modify files in more than one genome in the same operation.
- Modify `core-karpathy` in any way. - Modify `core-karpathy` in any way.
### ASK FIRST ### ASK FIRST
- Any operation that touches two or more genomes. - Any operation that touches two or more genomes.
- Updating submodule pointers in master. - Updating submodule pointers in master.
- Any key rotation procedure. - Any key rotation procedure.
@ -77,7 +82,8 @@ Genome-level operations are governed by the genome's `AGENTS.md`, not this file.
--- ---
## Cross-Genome Lint ## Cross-Genome Lint
*Manual, monthly — requires operator initiation. Not automated.*
_Manual, monthly — requires operator initiation. Not automated._
1. Use `qmd search "<concept>"` to find pages covering the same concept across genomes. 1. Use `qmd search "<concept>"` to find pages covering the same concept across genomes.
2. Identify: 2. Identify:

16
templates/pr-description.md
View file

@ -1,25 +1,31 @@
## Summary ## Summary
<!-- One sentence: goal of this session and source processed. --> <!-- One sentence: goal of this session and source processed. -->
## Pages Created ## Pages Created
| Path | Type | Maturity |
|------|------|----------| | Path | Type | Maturity |
| `[[folder/slug]]` | entity / concept / source / query | draft | | ----------------- | --------------------------------- | -------- |
| `[[folder/slug]]` | entity / concept / source / query | draft |
## Pages Modified ## Pages Modified
| Path | Change |
|------|--------| | Path | Change |
| ----------------- | ----------------------------------------- |
| `[[folder/slug]]` | Added cross-reference to `[[other/page]]` | | `[[folder/slug]]` | Added cross-reference to `[[other/page]]` |
## Contradictions Found ## Contradictions Found
- [ ] None - [ ] None
- [ ] `n` conflict file(s) created — listed below - [ ] `n` conflict file(s) created — listed below
## Private Data Accessed ## Private Data Accessed
- [ ] No — `PRIVATE_CONTEXT: disabled` - [ ] No — `PRIVATE_CONTEXT: disabled`
- [ ] Yes — `PRIVATE_CONTEXT: enabled` · outputs in `wiki/private/` only - [ ] Yes — `PRIVATE_CONTEXT: enabled` · outputs in `wiki/private/` only
## Scoped Lint (post-ingest) ## Scoped Lint (post-ingest)
- [ ] Frontmatter valid on all touched pages - [ ] Frontmatter valid on all touched pages
- [ ] No broken wikilinks on touched pages - [ ] No broken wikilinks on touched pages
- [ ] No issues found - [ ] No issues found

23
templates/wiki-index.md
View file

@ -1,9 +1,9 @@
--- ---
title: "Index — {{GENOME_NAME}}" title: "Index — {{GENOME_NAME}}"
type: index type: index
domain: {{GENOME_NAME}} domain: { { GENOME_NAME } }
maturity: stable maturity: stable
last_updated: {{DATE}} last_updated: { { DATE } }
private: false private: false
--- ---
@ -19,27 +19,28 @@ Entry format: `- [[folder/slug]] — One-line summary. \`maturity: <value>\``
--- ---
## Sources (`wiki/sources/`) ## Sources (`wiki/sources/`)
*Ingested raw materials. One entry per processed source.*
_Ingested raw materials. One entry per processed source._
## Entities (`wiki/entities/`) ## Entities (`wiki/entities/`)
*People, organisations, tools, projects.*
_People, organisations, tools, projects._
## Concepts (`wiki/concepts/`) ## Concepts (`wiki/concepts/`)
*Theories, methodologies, patterns, architectural decisions.*
_Theories, methodologies, patterns, architectural decisions._
## Queries (`wiki/queries/`) ## Queries (`wiki/queries/`)
*Synthesised answers worth preserving. Archived explorations and analyses.*
_Synthesised answers worth preserving. Archived explorations and analyses._
## Conflicts Pending Review (`wiki/queries/conflict-*.md`) ## Conflicts Pending Review (`wiki/queries/conflict-*.md`)
*Created automatically when the agent detects contradictions between sources.*
*Do not summarise entries here — list slugs only to avoid surfacing unresolved claims.*
*Remove entry once the operator has resolved and closed the corresponding PR.*
_Created automatically when the agent detects contradictions between sources._
_Do not summarise entries here — list slugs only to avoid surfacing unresolved claims._
_Remove entry once the operator has resolved and closed the corresponding PR._
## Private Synthesis (`wiki/private/`) ## Private Synthesis (`wiki/private/`)
*Restricted access. Requires `PRIVATE_CONTEXT: enabled` and unlocked repo.*
*List slug names ONLY. Do not append summaries — prevents metadata leakage.* _Restricted access. Requires `PRIVATE_CONTEXT: enabled` and unlocked repo._
_List slug names ONLY. Do not append summaries — prevents metadata leakage._

9
templates/wiki-log.md
View file

@ -1,9 +1,9 @@
--- ---
title: "Operations Log — {{GENOME_NAME}}" title: "Operations Log — {{GENOME_NAME}}"
type: log type: log
domain: {{GENOME_NAME}} domain: { { GENOME_NAME } }
maturity: stable maturity: stable
last_updated: {{DATE}} last_updated: { { DATE } }
private: false private: false
--- ---
@ -22,11 +22,13 @@ Append new entries at the bottom using the format defined below.
## Entry Format ## Entry Format
### Required header (enables shell parsing): ### Required header (enables shell parsing):
```text ```text
## [YYYY-MM-DD] TYPE | Subject or title ## [YYYY-MM-DD] TYPE | Subject or title
``` ```
### Required metadata block for all agent-generated entries: ### Required metadata block for all agent-generated entries:
```markdown ```markdown
- run_id: `<short-uuid or session-identifier>` - run_id: `<short-uuid or session-identifier>`
- model: `<model-name-and-version>` - model: `<model-name-and-version>`
@ -38,6 +40,7 @@ Append new entries at the bottom using the format defined below.
**Valid TYPEs:** `INGEST` | `LINT` | `QUERY` | `CONFLICT` | `CONFIG` | `SECURITY` **Valid TYPEs:** `INGEST` | `LINT` | `QUERY` | `CONFLICT` | `CONFIG` | `SECURITY`
**Parse examples:** **Parse examples:**
```bash ```bash
# Last 5 entries # Last 5 entries
grep "^## \[" wiki/log.md | tail -5 grep "^## \[" wiki/log.md | tail -5
@ -55,6 +58,6 @@ grep "^## \[2026-05" wiki/log.md
- run_id: `system-init` - run_id: `system-init`
- model: `setup-knowledge-genome.sh` - model: `setup-knowledge-genome.sh`
- context_read: *(none — initial scaffold)* - context_read: _(none — initial scaffold)_
- output_written: `[[wiki/index.md]]`, `[[wiki/log.md]]`, `[[AGENTS.md]]` - output_written: `[[wiki/index.md]]`, `[[wiki/log.md]]`, `[[AGENTS.md]]`
- reasoning: Initial directory structure and encryption layer initialized by setup script. - reasoning: Initial directory structure and encryption layer initialized by setup script.