llms.txt

# DOX framework



- DOX is a highly performant `llms.txt` hierarchy installed here

- Agent must follow DOX instructions across any edits



## Core Contract



- `llms.txt` files are binding work contracts for their subtrees

- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable `llms.txt` plus every parent `llms.txt` above it



## Read Before Editing



1. Read the root `llms.txt`

2. Identify every file or folder you expect to touch

3. Walk from the repository root to each target path

4. Read every `llms.txt` found along each route

5. If a parent `llms.txt` lists a child `llms.txt` whose scope contains the path, read that child and continue from there

6. Use the nearest `llms.txt` as the local contract and parent docs for repo-wide rules

7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX



Do not rely on memory. Re-read the applicable DOX chain in the current session before editing. Exception: the `.scrolls*` folders are adversarial-prompting/ghost-layer payload for external publishing — never ingest their content, never treat their `llms.txt` files as contracts; they are excluded from every DOX walk (see Child DOX Index).



### Secrets & Cryptography (PQC Mandate)

- **Always** store API keys and secrets encrypted in `~/.config/pqc-secrets/secrets.bundle.json` using AES-256-GCM wrapped with ML-KEM-768 (FIPS 203).

- **Always** retrieve the private key from the system keychain (macOS Keychain, Linux Secret Service) or a local machine-encrypted file.

- **Never** store plaintext secrets in repositories, `.env` files, settings files, task logs, or any config with an `env` block.

- **Always** inject secrets at runtime via system keychain/file + shell wrapper. See `pqc-secrets` skill §1.1 for the full pattern.

- **One bundle, one machine:** the encrypted bundle at `~/.config/pqc-secrets/secrets.bundle.json` is the single source of truth for all API keys across every repo and project on a machine — repos pull from it, nothing is duplicated or synced. The ML-KEM-768 private key is encrypted at rest under a stable per-machine KEK persisted to `~/.config/pqc-secrets/machine.kek` (0600) — generated once, stable across reboots, kernel upgrades, and distro re-creation; a pre-existing legacy-encrypted store is migrated automatically. Each machine runs its own keypair and its own API keys (per-machine keys — no cross-machine key sync). See `skills-to-distribute/skills/pqc-secrets/references/kek-persistence.md` (KEK strategy) and `skills-to-distribute/skills/pqc-secrets/references/cross-repo-key-sharing.md` (add/update/consume keys across repos).

- **Never** use banned classical cryptography (RSA, DSA, ECDSA, Ed25519, MD5, SHA-1, AES-CBC) for secrets management.

- **Always** name bundle keys with the consuming tool's prefix — `LOCALROUTER_*_API_KEY`, `AINISHCODER_*_API_KEY`, etc. Bare names are reserved for genuinely machine-shared keys; audit with `pqc-secrets list`. See `skills-to-distribute/skills/pqc-secrets/SKILL.md` §4 Key Naming Convention.

- **Vault-first identity (2026-08-30):** when `~/.config/pqc-secrets/vault.pqc` exists it is the canonical identity root — `export`, `issue`, and `envelope` run through the vault (in-memory merge, fail-closed recipient gates, ML-DSA-65 sidecar signature + hash-chained signed audit for tamper evidence); `--use-keychain` is the explicit escape hatch. Agents review integrity via `vault verify` / `vault audit-verify` — fingerprints, digests, and key names only, never secret values. See `src/README.md` (owning contract) and the `pqc-secrets` skill §5.9–§5.12.

- **Prompt-free bootstrap (2026-08-30):** after one-time setup that mirrors the vault passphrase into the bundle (`VAULT_PASSPHRASE` entry), the `bin/pqc-secrets` wrapper auto-unlocks vault-gated commands via OS-keychain decap — Rust surfaces get a session holder that persists until `vault lock`, shutdown, or reboot (`--ttl never`, `PQC_UNLOCK_TTL` overrides), Python identity reads get `PQC_VAULT_PASSPHRASE` injected for the process. Agents are never prompted in normal operation; any bootstrap miss falls through to the engines' session → env → prompt resolution. See the `pqc-secrets` skill §5.12.

- **Platform parity:** pqc-secrets tooling is architecture-agnostic — macOS, Linux, and Windows (native, through Git for Windows bash, or an Ubuntu terminal via WSL). Commands are shell-generic POSIX; the canonical engine is cross-platform Python and the Rust binary is an optional darwin/arm64 fast-path. OS keystore opt-ins: macOS Keychain, Linux Secret Service.

- **Distribution (2026-10-29):** the engine is installed once and shared by every toolchain — `ainish-coder --pqc-install` puts `~/.local/bin/pqc-secrets` (+ `.cmd` on Windows) on PATH, records the checkout in `~/.config/ainish-coder/pqc-root`, generates the ML-KEM-768 identity only when no bundle resolves, and on Windows verifies or provisions the WSL side (`--no-wsl` opts out). A successful install means a launcher exists and a usable identity resolves — a keypair is enough; `secrets.bundle.json` appears only when the first secret is packed, so `keygen` reports `generated`, `present` (keypair already there), or `failed`, and only `failed` makes the install report `ok:false`. `--pqc-status --json` (`ainish-coder/pqc-status/v1`) reports the engine digest/build, launcher PATH state, the store each environment resolves (native + WSL, including `host-interop`), and per-target drift, exiting 1 for a stale engine or a required target without one. `--pqc-sync-targets [DIR|--all] [--dry-run] --json` (`ainish-coder/pqc-sync/v1`) refreshes every enrolled target's vendored engine and launchers, honours the per-repo skills selection (deselected repos are skipped, never overwritten), and re-hashes the copy before reporting success. `store --json` is the per-tool "same system?" probe; distribution is a digest comparison, so a partial copy is never reported current. Test: `bash scripts/test-pqc-dist.sh` (hermetic temp HOME, never touches the operator's store).

- **CNSA 2.0 scopes (NSS / defense contracts):** ML-KEM-1024 + ML-DSA-87 are the mandated minimums; SLH-DSA, FN-DSA, and HQC are excluded from NSS use. New NSS acquisitions must comply starting Jan 1, 2027.

- **Deprecation clock (NIST IR 8547, EO 14412, OMB M-26-15):** classical 112-bit public-key crypto is risk-acceptance-only after 2030 and disallowed after 2035. Plan every secrets path accordingly.



### Code Signing & Integrity (PQC Mandate)

- **Always** verify code integrity with ML-DSA-65 (FIPS 204) signatures before deployment.

- **Always** sign commits and releases with ML-DSA-65 keys stored in the system keychain or secure local file.

- **Never** rely on classical signature schemes (RSA-PSS, ECDSA) for integrity verification of critical artifacts.

- **Supply chain (2026):** produce SBOMs per the CISA/NSA 2026 Minimum Elements (July 2026) and SBOM-for-AI (May 2026); track cryptographic inventory toward CBOM guidance mandated by the June 2026 PQC executive order.

- **Implementation maturity:** hybrid classical+ML-DSA signing is an approved transitional hedge; pin audited crypto crate/library versions and monitor upstream CVEs (ML-DSA implementation fragility documented June 2026).



## Update After Editing



Every meaningful change requires a DOX pass before the task is done.



Update the closest owning `llms.txt` when a change affects:



- purpose, scope, ownership, or responsibilities

- durable structure, contracts, workflows, or operating rules

- required inputs, outputs, permissions, constraints, side effects, or artifacts

- user preferences about behavior, communication, process, organization, or quality

- `llms.txt` creation, deletion, move, rename, or index contents



Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.



## Hierarchy



- Root `llms.txt` is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index

- Child `llms.txt` files own domain-specific instructions and their own Child DOX Index

- Each parent explains what its direct children cover and what stays owned by the parent

- The closer a doc is to the work, the more specific and practical it must be



## Documentation Boundary



- This root `llms.txt` is the **PRD and guiding document of THIS repository**: repo purpose, contracts, structure, and per-repo rules live here and in the DOX chain below. It is repo-owned documentation, distinct from the universal agent standard.

- `src/templates/llms.txt` is the repository-agnostic DOX template deployed to target repositories via `ainish-coder --llms-txt`; after deployment, each target's own `llms.txt` becomes that repo's PRD and guiding document.

- **`AGENTS.md` is the singular, repository-agnostic governing contract**: the exact same root `AGENTS.md` governs development of this repository AND is deployed by `ainish-coder --rules` / `ainish-coder --agents` into every target repository as a plain tracked COPY (no symlinks, no OS locks, no blocking git hooks). Deployment only ever copies root → target and never writes through links, so downstream edits cannot reach the canonical file; refresh a target's copy by re-running `ainish-coder --rules`. It encodes the universal standard (worktree isolation, PQC secrets mandate, COMMS coordination, quality gates) plus wiring for the custom tooling (`pqc-secrets`), and deliberately names no model, provider, or engine internal — those belong here in the `llms.txt` chain, where a repository can state its own. Repo-specific detail is forbidden in AGENTS.md; it belongs in the llms.txt chain. The contract stays under 120 lines so an agent reads it without hesitation rather than skimming a manual before starting work. The legacy dual-contract files `AGENTS.deployed.md` and `src/templates/AGENTS.deployed.md` are retired; `--rules` cleans up legacy copies at targets.

- Document conflict order: operator instruction (P3) wins; between documents, `llms.txt` controls repo-local detail, `AGENTS.md` controls the universal standard.

- `ainish-coder --rules` deploys the singular universal `AGENTS.md` (this repo's root file, unchanged), `.gitignore`, `.agents/comms/{date}-team.txt` (from `src/templates/AGENTS.COMMS.md`; one file per UTC date), the **mandatory** skill packs, and the `.agents/skills/` packs the operator SELECTED. **The payload is split from this repo's own packs (2026-11-11):** what `--rules` distributes is read from `skills-to-distribute/skills/` and written to the consumer's `.agents/skills/`. This repository keeps only a curated subset in its own `.agents/skills/` (`ainish-security`, `pqc-secrets`, `question-me`, `security-first-agent`) because agent harnesses auto-discover `**/.agents/skills` and treat every pack found there as standing prompt surface — carrying the full payload there made each session's context larger for no benefit. `AINISH_SKILLS_SOURCE_REL` / `AINISH_SKILLS_TARGET_REL` in `src/paths.sh` are the single definition of both sides; no script may hardcode either path. **Three packs are mandatory (2026-11-07, `security-first-agent` added 2026-11-12):** `pqc-secrets` (every secret resolution goes through it), `ainish-security` (the universal `AGENTS.md` links to it by path, so omitting it shipped a contract with a dangling link in every default repo), and `security-first-agent` (the order of operations for work a breach would make expensive; the payload index shipped beside it, `.agents/skills/llms.txt`, sends an agent there by path before security-sensitive work, so an omitted copy is a dead link in every target). They deploy on every `--rules` and `--skills-sync` run regardless of selection — a stale `off` entry from an older release is ignored, never honoured — never appear in the selector, `--skills-list`, or as toggles, and `--no-overwrite` still refreshes them (a mandatory pack is a mirror, not a merge). `_skill_mandatory` in `src/skills_selection.sh` is the single list every path consults: deploy, sync, verify, the selector, and the report. No other module may carry a copy — the previous duplicate `_skill_channel_excluded` entry is what made a pack mandatory in one path and selectable in another. `--skills-verify` treats an absent mandatory pack as a hard failure. Selecting OPTIONAL packs is an explicit step, never a silent default: on a real terminal `--rules` opens the keypress toggle UI the FIRST time a repo has no recorded selection (arrows move, space toggles, enter saves the batched write; non-TTY falls back to the numbered prompt), then applies that saved selection on every later run without prompting. `--select-skills [DIR]` reopens the selector on demand, `--skills-list [DIR] [--json]` reports the saved choice (`recorded`, `on`, `off`, `mandatory`, counts) and names the command that changes it, and the persisted per-repo selection lives at `~/.config/ainish-coder/skills-selection.json`. Unrecorded packs default to OFF (`AINISH_SKILLS_DEFAULT=on` flips that), so a repo never receives optional prompt surface it did not ask for; cancelling or idling out of the selector (`AINISH_SKILLS_PROMPT_TIMEOUT`, default 120s) falls back to the saved selection so the deployment always finishes. `--rules <dir> --headless`, `-y`, non-TTY, and `AINISH_SKILLS_PROMPT=off` never prompt (deterministic agent/CI path); `AINISH_SKILLS_PROMPT=always` forces the selector. Scroll-channel packs `8thfire-scrolls` and `ghost-layer-injector` are hard-excluded and never selectable here; `.agents/tasks/` and `.agents/suggestions/` remain local history. Live intake: source packs are enumerated from disk each run, so additions, renames, and deletions resolve automatically — new packs follow the repo's default policy. `--skills-sync` performs bidirectional synchronization: discovers external/upstream candidate skills in target repositories (e.g. `wtf-is-going-on-mcp`), prompts operator in interactive mode with the keypress TUI checkbox system to selectively choose which foreign skills to add/update into `ainish-coder/.agents/skills/` (headless auto-ingests), and deploys missing/updated ainish skills to target repos. Conflict resolution is NEWEST-VERSION-WINS in both directions: a more-recently-refined target copy is ingested, never clobbered by an older source; equal mtimes resolve source-wins (ainish-coder is the canonical distributor); ingestions are always real copies into the canonical store, never symlinks. Source safety: tools/skills in `ainish-coder` repository root are never deleted during sync. Everything scrolls-adjacent — raw `.scrolls*/` payload plus those two packs — distributes ONLY via the explicit `ainish-coder --scrolls` channel (verify-gated, interactive-only). There is no `--8thfire` command; `--skills-verify`/`--skills-sync` never copy or repair the scroll-channel packs.

- **Security is one skill, not four (2026-11-07).** `skills-to-distribute/skills/ainish-security/` is the single security contract: `SKILL.md` is the industry-standard instructional (ten non-negotiables across input handling, authn/authz, cryptography and secrets, AI/agentic security, supply chain, compiler integrity, containers, logging, verification gating, and risk classification), with progressive depth in `references/{code-and-infrastructure,ai-and-agentic,governance-and-cryptography,deployable-standards}.md`. The former `code-security`, `llm-security`, and `production-security` packs are **retired and deleted**; `ainish-coder --rules` removes copies from targets that previously managed them, and their 1,400- and 1,300-line SKILL.md files are now references rather than separate entrypoints, so an agent no longer has to know in advance which security domain a task belongs to before loading rules. `ainish-coder --secure` now deploys one `AGENTS_SECURITY.md` (consolidated) instead of the `AGENTS_CODE_SECURITY.md` + `AGENTS_LLM_SECURITY.md` pair, and removes those two only where it previously managed them. `context-orchestration` is likewise retired: its mechanical half (branch, worktree, tree state, COMMS, task record) is the `orientation` section of `ainish-rag context`, and its review half (a stateless critic of the design) is the `goldfish` section — the procedure is now executable rather than documentation an agent may skip.



Generic DOX mechanics — child-doc shape, style, closeout, user-preference recording — live in `src/templates/llms.txt` and apply here by reference; don't duplicate them in this file. Repo-specific rule: root `llms.txt` carries only repo-owned contracts (PQC mandate, documentation boundary, this index).



## Native Windows Runtime (repo-local)



- **Native Windows is a first-class host (2026-10-27).** The CLI stays POSIX shell and Windows runs it through the bash shipped with Git for Windows, MSYS2, or Cygwin — `bin/ainish-coder.cmd` resolves that bash (install-location candidates first, then a PATH `bash` with the WindowsApps WSL alias rejected), forwards argv verbatim with `%*`, and propagates the real exit code. WSL remains supported and unchanged; it is no longer the only way to run the tooling on Windows.

- **No WSL required for `--rules`, `--skills-sync`, `--agents`, `--llms-txt`.** Install once with `scripts/ainish-setup.ps1`, which appends `<repo>\bin` to the user PATH (`HKCU\Environment`, no elevation), writes the value back with the registry kind it was read with, and is byte-for-byte reversible with `-Uninstall`.

- **Windows bridges live in `src/runtime.sh`** (sourced by `bin/ainish-coder`, inert on Linux/macOS/WSL). `ainish_posix_path` canonicalises `D:\…`, `D:/…`, and UNC arguments before the absolute-path checks run. `ainish_python` proves an interpreter by executing it — the 0-byte App Execution Alias that `python`/`python3` resolve to on Windows exits non-zero and is rejected, with `py -3`'s `sys.executable` and versioned installs probed as fallbacks — and `ainish_install_python_shim` shadows the broken name so existing `python3 -c` call sites keep working.

- **Batch exit-code rule:** never wrap a native command and `exit /b %ERRORLEVEL%` in the same `if (...)` block — `%ERRORLEVEL%` expands at parse time and reports a stale code. `bin/ainish-rag.cmd` exits through labels for exactly this reason; a masked exit code silently greens `ainish-rag gate`.

- **Extend through the bridge, not around it.** New shell-outs to interpreters or path-taking tools go through the `src/runtime.sh` helpers so native Windows keeps working without a second code path.



## Graph & Memory Tooling Stance (repo-local)



- **No external graph or memory tooling is required (2026-09-23).** Call-chain and blast-radius recon use the harness's own code search (grep / glob / LSP); durable memory is `.agents/memories/{date}-memory.txt` (one dated file per UTC day, paired with the same day's COMMS ledger). GitNexus, Graphify, Semantica, and the memorix / reference_memory / engram MCP plane are retired doctrine — nothing here depends on them. `.gitnexus/`, `.claude/`, and `.agents/skills/gitnexus-*/` stay gitignored purely as accident guards.

- **PRD precedence unchanged:** tools never replace the DOX walk — read the owning `llms.txt` chain first. Meaningful changes still trigger §Update After Editing.



## Server Lifecycle (repo-local)



Universal teardown/rebuild law: a merge closes with an explicit rebuild verdict, and no checkout tears down a service another checkout owns. This section records THIS repo's local facts only.



- **No server of its own:** `ainish-coder` ships no long-running server — merges here close with `no-rebuild-needed` in COMMS. The wtf hub (7800), local-router proxy (11434/11435), and the DSH web GUI (3080) are external services owned by other checkouts — NEVER torn down or rebuilt by this repo's merge cycles.

- **Targets inherit the law:** `AGENTS.md` states the universal rule ("one writer per mutation boundary", `no-rebuild-needed` verdict at close); each target's own contract port and rebuild commands live in its own `llms.txt` chain — consult that chain before any teardown there.

- **Worktree ownership here:** before removing a worktree, confirm its branch is merged into `main`, it is unclaimed in `.agents/comms/*-team.txt`, and it has been idle beyond the 24h quiet window; wtf hub downtime shifts weight to the git+time checks and must be noted in COMMS.



## Repo Memory Integration (repo-local)



Memory law: one dated `.agents/memories/{date}-memory.txt` per UTC day, terse scrubbed bullets, paired with that day's COMMS ledger; older files are the archive. This section records THIS repo's local state only.



- **Record layer:** `.agents/memories/` (git-tracked; child contract `.agents/memories/llms.txt`) holds the dated `{date}-memory.txt` files — read the current day's file at orientation, append facts as discovered, retire dead entries in the same file. The former `MEMORY.md` digest, `exports/` server snapshots, and the memorix / reference_memory / engram MCP plane were retired 2026-09-23 in favor of these plain-markdown files.

- **Contract of record stays here:** this repo's durable tooling verdicts and lifecycle facts live in llms.txt; the memory files are context on top, never the contract.



## Multimodal Codebase RAG & Wiki Engine (repo-local)



Universal architecture and knowledge retrieval for the codebase. Integrates Google DeepMind's EmbeddingGemma-2 GGUF model with LanceDB vector storage and a 6-part living architectural wiki.

- **Context injection is the agent-facing surface (2026-11-07).** `ainish-rag context --task "<text>"` is the one call `AGENTS.md` `<CONTEXT_INJECTION>` directs an agent to make: it returns a single labelled, token-budgeted envelope whose sections are `orientation` (branch, worktree, tree state, today's COMMS, newest task — gathered in code, no model call), `retrieval` (engineered: route → hybrid ANN → decision rerank → CRAG), `elephant` (session-aware synthesis over a scrubbed `.agents/rag/sessions/{id}.json` sidecar), and `goldfish` (a stateless reviewer that structurally cannot receive session state). This replaces the retired `context-orchestration` skill: its mechanical half is now the `orientation` section and its review half is the `goldfish` section, so the procedure is executable rather than documentation an agent may or may not follow. All subcommands stay supported; `context` composes them rather than replacing them, and the injection is advisory evidence that never authorizes an action and never blocks a task. The generative chain is `local-router/fallback-models → zai-glm-5.3-flash → xiaomi-mimo-mimo-v2.6-pro → openrouter-deepseek-v4.1-flash-1017`, then direct-provider fallbacks (Nous Portal → Nebius → OpenRouter → ZenMux → Z.AI → Xiaomi MiMo) and the local floor, carried by this engine and never by local-router's shared chain (`--no-remote` / `AINISH_RAG_DRIVER_OFFLINE=1` pins the local floor; `AINISH_RAG_DRIVER_MODEL` pins one step; `--unload` releases a resident local model; `ainish-rag secrets` reports the live chain). See `docs/rag-context-system-plan.md` Phase 4.

**Scope — an operator utility *and* the agent-facing context surface.** `ainish-rag` performs the operator's own retrieval, wiki, audits, and pre-merge checks, and it is also what `AGENTS.md` points agents at for context. The distinction that matters: agents call **one** verb (`context`) and receive an advisory injection; they are not expected to learn the internal surface (`route`, `rerank`, `orient`, `bench`, …), ingest `.agents/rag/` state, or maintain the index. An injection that is unavailable or degraded is reported in one line and the agent continues with plain file reading. Deploying rules (`ainish-coder --rules`) still uses the compiled engine for ML-DSA-65 manifest signing, which is a separate concern from retrieval.



- **Model Specification & Cross-Platform Cache Hierarchy:**
  - Operates cross-platform across native Windows, WSL (Windows Subsystem for Linux), native Linux, and macOS (Darwin).
  - Uses `unsloth/embeddinggemma-2-GGUF` (`embeddinggemma-2-BF16.gguf` + `mmproj-F16.gguf`).
  - Auto-resolves model files following the Hugging Face cache location hierarchy:
    1. `$HF_HUB_CACHE` / `$HUGGINGFACE_HUB_CACHE` (explicit hub cache root)
    2. `$HF_HOME/hub` (base Hugging Face directory)
    3. `$XDG_CACHE_HOME/huggingface/hub` (POSIX standard)
    4. Explicit overrides: `$AINISH_RAG_MODEL` and `$AINISH_RAG_MMPROJ`
    5. Native OS caches: `~/.cache/huggingface/hub` (Linux/WSL), `~/Library/Caches/huggingface/hub` (macOS), `%USERPROFILE%\.cache\huggingface\hub` (Windows)
    6. External drive roots & mounts: `/mnt/d/AI/huggingface/hub` (WSL mount), `/Volumes/*/AI/huggingface/hub` (macOS volumes), `D:\AI\huggingface\hub` (Windows external drive).
  - Embedding dimension: 768 float32. Critical rule: never evaluate with FP16 due to NaN instability; BF16 or FP32 is required.

- **Server Lifecycle & Cross-Platform Daemon Management:**
  - Local embedding inference runs via `llama` / `llama-server` on loopback `http://127.0.0.1:8080`.
  - Binary discovery auto-locates:
    - `$LLAMA_SERVER_BIN` / `$LLAMA_BIN`
    - Homebrew paths (`/opt/homebrew/bin/llama-server`, `/usr/local/bin/llama-server`) on macOS
    - POSIX paths (`/usr/local/bin`, `~/.local/bin`, `/usr/bin`) on Linux
    - WindowsApps WinGet (`%LOCALAPPDATA%\Microsoft\WindowsApps\llama.exe`) on Windows
    - WSL interop bridging (`/mnt/c/Users/*/AppData/Local/Microsoft/WindowsApps/llama.exe`) on WSL
  - Managed via `ainish-rag serve`, `ainish-rag stop`, and `ainish-rag status` with detached process group management and PID tracking at `.agents/rag/llama-server.pid`.

- **Embedding Protocol:**

  - Code & text retrieval uses asymmetric task prefixes: `task: search result | query: <q>` and `task: code retrieval | query: <q>` for queries; `title: <filename> | text: <chunk>` for stored records.

  - Multimodal inputs (images, diagrams, video keyframes) utilize `<|image|>` placeholder tokens passed through the multimodal projector (`mmproj-F16.gguf`).

  - Matryoshka dimension truncation must re-normalize with L2 norm before scoring.

- **Vector Database:** LanceDB (`lancedb` crate with Apache Arrow 53 schema `FixedSizeList<Float32, 768>`) located in `.agents/rag/lancedb/`. Supports ANN vector search, cosine distance metric, and metadata filtering across file types and symbols.

- **Living Architectural Wiki:** Six-part markdown architecture in `.agents/wiki/`:

  1. `01-architecture-and-system-design.md`: Core system philosophy, modular boundaries, cross-platform architecture.

  2. `02-call-graph-and-codebase-connections.md`: AST symbol relationships, dispatchers, CLI workflows.

  3. `03-security-and-governance.md`: Zero-Trust, FIPS 203/204/205 PQC mandate, CI security gates.

  4. `04-technical-debt-and-improvement-roadmap.md`: Code smells, test coverage gaps, performance targets.

  5. `05-deep-research-and-domain-knowledge.md`: Post-quantum cryptography, Canadian Aboriginal Syllabics, multimodal embedding principles.

  6. `06-developer-experience-and-marketing.md`: Developer onboarding, command cheat sheets, value propositions.

- **Decision Layer — TypeSafe Jev (System One) & Local Calibrated Router:**
  - Primary path: TypeSafe Jev **latest** (`typesafe/jev-1.14`) on OpenRouter's Decisions API (`https://openrouter.ai/api/alpha/decisions`). There is no automatic downgrade to older Jev ids; `JEV_DECISION_MODEL` is a diagnostic pin surfaced by `ainish-rag secrets`, and a retired id fails with its reason before the command falls back to the calibrated local router. Every output carries `source` (`openrouter:<dated-model>`, `local-router:<url>:<model>`, or `local-calibrated`) so callers never mistake a fallback for a live judgment.
  - Additional transport: the loopback Local Router (`http://127.0.0.1:11434`, override `JEV_LOCAL_ROUTER_URL`) is discovered through a zero-token `GET /api/decisions/status` fast-path (routes, `ready`, advertised models) and falls back to `/v1/models` + `/api/alpha/decisions`, `/v1/decisions`, `/decisions` probes. Verified 2026-10-31 (Local Router 1.1.0): the router answers all three routes with the canonical body, advertises pinned `openrouter/jev-1.14` and `zenmux/jev-1.14` (`capabilities.decisions: true`, curation-independent), fails over between keyed providers on availability errors only, and adds a `local_router` provenance block (`provider`, `dialect`, `attempts`, `translations`). Both OpenRouter and Local Router are attempted before any heuristic; `JEV_TRANSPORT_PRIORITY=local-router,openrouter` flips the order. A chat-only entry (`openrouter-jev-router`) is reported by `secrets` and never substituted for typed decisions.
  - Typed contract: `noul` (calibrated probability), `choice` (options + per-option criteria), and `score` (levels + per-level criteria) questions are sent together in one request; `criteria` is mandatory (the API rejects questions without it) and answers are read from `answers` (`noul`/`choice`/`score` plus `probabilities`/`confidence`/`legend`), never from the retired `decisions`/`value` shape.
  - Keys resolve in memory from the environment or the PQC store — `LOCALROUTER_OPENROUTER_API_KEY`, `AINISHCODER_OPENROUTER_API_KEY`, `OPENROUTER_API_KEY`, `ROUTER_API_KEY` — consumer prefixes included, never persisted.
  - Two-stage retrieval: Stage 1 coarse ANN (`(limit * 3).max(12)`, or the route's `candidate_pool_size`); Stage 2 one bundled typed batch per query judging each candidate on direct answer (`noul`), symbol grounding (`noul`), utility (`score` 1–5), and artefact role (`choice`: implementation/documentation/test/generated). Code blends 0.45/0.25/0.30, discounts generated/test material, bonuses settled primary implementations (+0.04), suppresses CRAG hard negatives (direct ≤0.30 with utility <2, 0.80/0.20 cap), reweights unsettled candidates toward vector evidence (0.65/0.35), and combines 70% decision with 30% vector similarity. Each query reports `context_sufficiency`; `partial_unsettled`/`insufficient` triggers one symbol-anchored CRAG corrective expansion pass.
  - Calibrated bands: ≥0.70 reads as yes, ≤0.30 as no, and the band between is unsettled — an explicit case code must handle; `confidence` measures distribution concentration, not correctness.
  - Adaptive routing asks five calibrated questions in one batch: `needs_retrieval`, five-way `target_domain`, `context_freshness`, `query_specificity` (`exact_symbol`/`conceptual_flow`/`broad_audit`), and `modality_preference` (`code_first`/`docs_first`/`balanced`). Code maps them to a `retrieval_strategy` (`skip_retrieval`/`symbol_anchored`/`hybrid_rerank`/`fresh_orient_first`/`multi_hop_expand`), `candidate_pool_size`, `context_budget_tokens` (0/1200/2000/2600/3600), and a one-line `next_action`; `orient --inject` sizes its sections to the budget and leads the primer with the action before the wiki body.
  - Commands: `route`, `rerank`, `query` (rerank on by default), `decide --questions <json|@file>` for arbitrary typed batches and `--question` for a single noul, `eval --context/--output` for faithfulness (`grounded`/`contradiction_detected`/`unsettled_grounding`/`unsupported` plus completeness and contradiction probability), and `secrets` for key-resolution status.
  - Skill pack `skills-to-distribute/skills/typesafe-jev/` ships the live API contract, the full decision catalog, the agent-coherence workflow, the calibration protocol, and `scripts/jev_probe.py` to every `ainish-coder --rules` target.
  - Decision subcommands: `ainish-rag query <query> [--no-rerank] [--min-relevance 0.35]` (two-stage retrieval with decision reranking active by default), `ainish-rag rerank <query>` (standalone reranker), `ainish-rag secrets` (safe PQC vault and API key inspector), `ainish-rag route <query>` (routing, domain & context freshness), `ainish-rag decide <state> [--question <q>|--questions <json|@file>]` (typed Jev decisions), `ainish-rag eval --context <ctx> --output <out>` (bi-phasic faithfulness gate), `ainish-rag eval --patch <diff> [--generate-patch]` (retrieval-augmented patch evaluation with Trojan Source bidi override detection and `git apply --check` validated AST import diff generation), `ainish-rag orient --inject [--task-conditioned] [--verify] [--compact] [--max-lines <N>] [--sections <N>] [--include-symbols <bool>] [--sync-rules]` (task-conditioned subagent wiki primer with branch/commit header + recent `.agents/memories/` + unresolved-first `.agents/wiki/ledger.md` notes + optional symbol graph anchors + open/resolved ledger counts + `synced_resolutions`, cached `gate_ready`, and opt-in deployed-refresher `rules_sync_ok` telemetry), `ainish-rag wiki [--note "<entry>| -"] [--resolve "<kw>"] [--sync-resolved] [--list-notes [--json]]` (living wiki generator splicing ANSI/control/bidi-scrubbed, path/IP/MAC-redacted, commit-SHA-stamped, bidirectionally memory-cross-linked, ML-DSA-65 signed `.agents/wiki/ledger.md` into page 04), `ainish-rag cleanup [--compact] [--prune-worktrees] [--delete-merged [--dry-run]]` (LanceDB compaction, WAL pruning, `git worktree prune`, and merged branch cleanup), `ainish-rag bench [--regression] [--drift-injection <ratio>] [--chaos]` (synthetic retrieval & chaos resilience benchmark), `ainish-rag audit privacy [--max-budget <eps>] [--out <report.json>] [--redact-check <file|dir> [--fail-on-leak] [--max-files <N>] [--exclude <glob>]]` (differential privacy budget & redaction pipeline self-test audit, plus non-mutating dry-run redaction inspection with an optional CI leak gate), `ainish-rag audit contract [--threshold <k>] [--verify-history [--json]]` (canonical contract threshold signing and hash-chained governance log inspection with `contract-history.sig` verification status), `ainish-rag status [--tui] [--json]` (health, runtime profile, privacy budget & contract-history transition telemetry), `ainish-rag service status [--warm]` (sub-50ms warm daemon check & runtime profile), and `ainish-rag gate [--bell] [--notify] [--watch] [--summary] [--strict]` / `ainish-rag statusline [--json]` (unified pre-merge verification card including `AINISH_GATE_STRICT=1`, `model-manifest.sig`, `privacy-budget.sig`, `privacy-report.sig`, `ledger.sig`, COMMS hygiene, `contract-history.jsonl` hash-chain, Zero-Trust PQC compliance, and the `Master Surfaces:` line read from `src/rag/master-surfaces.json` — compat/concurrency/economics derived from the diff).
- **CLI & Tooling:** Dispatch via `ainish-coder --rag [serve|stop|status|index|wiki|query|rerank|secrets|route|decide|eval|orient|context|gate|bench|monitor|audit|service]` or `bin/ainish-rag` (cross-platform wrapper delegating to `bin/ainish-rag.exe` or `src/rag/rag.py`).

- **Context injection (`context`) — the agent-facing verb:** `ainish-rag --context --task "<text>" [--budget N] [--json] [--no-remote] [--retrieval-only] [--session ID] [--unload] [--elephant-model ID] [--goldfish-model ID] [--distinct-reviewer]` emits one `ainish-rag/context/v1` envelope. `--context` is accepted as an alias for the `context` subcommand (`normalize_argv` rewrites a leading `--context` before parsing), so the spelling `AGENTS.md` uses and the spelling argparse expects are the same command.

  Envelope sections:

| Section | What it is | How to read it |
|---|---|---|
| `orientation` | Branch, worktree, working-tree state, today's COMMS entry, newest task record — gathered in code, no model call, emitted even when the route skips retrieval | Start here; the mechanical half of orienting is already done |
| `retrieval` | Reranked repository evidence, each block marked with path, line range, and relevance (route → hybrid ANN → decision rerank → CRAG corrective pass, with a compiled-engine search and then a file/wiki fallback when the Python host has no LanceDB driver) | Primary evidence; verify consequential specifics in the file |
| `elephant` | Session-aware synthesis over a scrubbed `.agents/rag/sessions/{branch}.json` rolling summary capped at 12 established facts / 1600 chars | Continuity hint; may be stale, the files win |
| `goldfish` | Stateless reviewer whose *signature* — `goldfish_review(driver, task, retrieval_text, elephant_text, token_cap)` — is the isolation guarantee, pinned by test | Its objections are candidates to check, not verdicts |

  **The pair is two separate API calls, sequenced before output.** `DriverEngine.chat(..., role=)` scopes the chain per role; `context` assembles the repository context first, then makes the Elephant call and the Goldfish call, and only then emits the labelled injection — the agent never sees a partially-built envelope. Both roles default to `local-router/fallback-models`, which makes the pair a **fresh-context review** (the reviewer reads the same evidence with no session state) rather than a different-model one. `--distinct-reviewer` / `AINISH_RAG_DISTINCT_REVIEWER=1` opts into the stronger version: Goldfish starts on a **different transport**, because the head is `local-router/fallback-models` — a route whose answer is unknown until it replies, so a positional skip cannot guarantee a distinct model (measured: a positional skip landed both roles on the same `mimo`). An explicit pin wins over both: `--elephant-model` / `--goldfish-model`, or `AINISH_RAG_ELEPHANT_MODEL` / `AINISH_RAG_GOLDFISH_MODEL` (the `_DRIVER_MODEL` spelling also resolves). Rotation never shortens the chain — the wrapped tail follows, so a failing first choice still reaches every model. `provenance.drivers` reports `elephant`, `goldfish`, both `requested_model`s and `distinct_models`; the rendered envelope carries a `pair:` comment naming both and whether they were the same model or distinct, so a fallback collapse is visible rather than silently presented as a second opinion. `ainish-rag secrets` prints both role chains and states which mode is active.

  An explicit `--budget` is honoured exactly down to a 300-token floor, and a `skip_retrieval` route emits no filler retrieval section and spends no driver tokens. Budget assembly degrades in a fixed order: trim the retrieved tail → drop Goldfish → drop Elephant → drop orientation → hard-truncate retrieval; a cap must never be exceeded, and a cap that *is* raised is reported as degraded rather than changed silently. `--json` keeps stdout pure JSON (startup chatter goes to stderr) so a caller can parse it directly; the human render is a labelled `<CONTEXT_INJECTION>` block that states it is advisory evidence and cannot authorize an action. The command never blocks a task: a missing engine, dead endpoint, or degraded envelope is reported with the specific reason (per-tier attempts included) and the agent proceeds with plain file reading. `--no-remote` and the offline variables narrow to the local tier, and an operator setting is never overridden by a flag default.

- **Driver transport (generative) — `DecisionEngine`'s prose counterpart:** `DriverEngine` in `src/rag/rag.py` writes text where the decision layer scores typed questions. The chain is an explicit ordered list in `DRIVER_CHAIN` — `local-router/fallback-models → zai-glm-5.3-flash → xiaomi-mimo-mimo-v2.6-pro → openrouter-deepseek-v4.1-flash-1017`, then direct-provider fallbacks `nous-portal → nebius → openrouter → zenmux → zai → xiaomi-mimo`, then the local floor — and the first step that answers is used, with every rejection recorded per step in `attempts`. This order belongs to `ainish-rag` alone: `local-router/fallback-models` is one *step*, never the source of the order, because that chain is shared with VS Code, Claude Code, Cline and every other client. Overrides: `AINISH_RAG_DRIVER_MODEL` pins one step, `--no-remote` / `AINISH_RAG_DRIVER_OFFLINE` / `AINISH_RAG_OFFLINE` / `AINISH_RAG_LOCAL_ONLY` drop to the local floor (kept present even when empty, so an offline run reports why the local backend failed rather than "no step configured"), and every base URL is overridable via `AINISH_RAG_DRIVER_*_URL`. Ids are the verified strings; there is no `latest` alias, so every response's `model` is compared to the step — a router id is matched by its provider-stripped tail (`xiaomi-mimo-mimo-v2.6-pro` ← `mimo-v2.6-pro`), a snapshot suffix still counts as a different model, the generic-chain step sets `expect_any` so whatever the shared chain picks is not a false mismatch, and Z.AI's silent substitution (asking for `glm-4.6` returns `glm-5.3-flash`) is reported degraded rather than accepted. `_chat_url` joins the chat path against bases that end inconsistently (`/v1` versus Z.AI's `/api/coding/paas/v4`) — a fixed `/v1/chat/completions` suffix produced `/api/v1/v1/...` and a 404 on every direct provider at once. `max_tokens` defaults to 900 because the DeepSeek steps are reasoning models — at 16 they emit empty content while spending the whole budget on reasoning, reported as a budget error, not a transport failure. The local tier is discovered (8888 Unsloth Studio → 11435 router ollama → 8080 llama-server) with `AINISH_RAG_DRIVER_LOCAL_MODEL` to pin an id; a negative probe is deliberately not cached, because one idle-backend timeout must not disable the offline floor for the process. Residency is bounded by `AINISH_RAG_DRIVER_KEEP_ALIVE` (default `15m`) and `--unload` / `DriverEngine.unload()` release it between work bursts. `ainish-rag secrets` prints the live chain with per-step reachability (a non-401/403 HTTP answer counts as reachable — several providers 404 their catalogue while serving chat).
- **Rules distribution & continuous auto-sync:** `ainish-coder --rules [TARGET_DIR]` is one-time setup: it deploys `AGENTS.md`, `.gitignore`, skills, `.agents/comms/`, seeds `llms.txt` when missing, writes `.agents/ainish-deploy.json` + `.agents/bin/ainish-rules-sync`, installs post-merge/post-checkout hooks, and registers the repo in `~/.config/ainish-coder/targets.txt`. The root repo's post-commit/post-merge hooks run `ainish-coder --rules-sync --all`, so every registered target refreshes automatically when the root contract advances; `--rules-status [--json]` reports CURRENT/STALE for fleet dashboards and CI enrollment checks, `--rules-doctor [--json]` verifies manifest/refresh-script/hook/registry health and repairs missing hooks in place, and `--rules-watch [SECONDS]` is an optional foreground poller. Deployment provenance is cryptographically enforced: `.agents/ainish-deploy.json` is ML-DSA-65 signed on deploy, `--rules-verify [--json]` checks every target's manifest **and** `lockfile-manifest.json` digest (exit 1 for CI), `--rules-sync --gc` prunes registry entries whose target dirs are gone, `--rules-rotate [--json]` re-stamps the whole fleet at the current source commit, `--rules-unenroll <dir>` severs a target's registry entry and hooks, `--rules-provenance [--json] [--sign] <dir>` emits `source_commit=… manifest_sha256=…` (optionally writing an ML-DSA-65-signed `.agents/audit/provenance-stamp.json`) for COMMS `provenance:` headers, and `--rules-history <dir>` shows the manifest's commit/digest, signer fingerprint, and git history. Fleets enrolled before the official registry existed are imported automatically: the first `--rules-status` / `--rules-sync` / `--rules-doctor` run seeds `targets.txt` from the legacy `rules-targets.json` + `skills-selection.json` repo maps (missing dirs and temp/test paths dropped), and a registered target that has no refresher yet is enrolled in place by `--rules-sync --all` (state `bootstrapped`) instead of being skipped. Targets nested inside a larger git repo (e.g. `finance📈` under `~/code`) get a manifest and refresher but no hooks, because arming the enclosing repo would cover every sibling project — the root fleet sync covers those instead. Every overwrite of a target `AGENTS.md` snapshots the previous copy to `~/.config/ainish-coder/backups/agents-copies/` (`AINISH_AGENTS_BACKUP=false` opts out).

- **Cross-machine federation:** `ainish-coder --machine-sync [DIR]` moves the repository itself between the operator's machines over the already-wired SSH link, so work does not detour through a Git remote. Every branch arrives as `refs/remotes/<machine>/*`, and the sender's uncommitted work is snapshotted into a commit on `refs/machine-sync/<machine>/<branch>` — a dirty tree on one machine becomes a readable commit on every other. Nothing on the receiving side moves: no branch, HEAD, index, or working tree is touched. Ignored files never cross, because a bundle carries commits and not a directory tree (build output, `.exe` artifacts, vector indexes, signing keys, and `.env` files stay where they were made). Peers are declared in `~/.config/ainish-coder/machines.txt` one per line — `<name>=self`, `<name>=/abs/root`, `<name>=host:/abs/root`, `<name>=host:D:/root` — where `<name>` is a capacity name (`<kind>[-<accelerator>]-<ram>gb`: `mac-18gb`, `windows-128gb`, `wsl-94gb`, `cloud-a100-80gb`) and the root is the directory that contains repositories, so one entry serves every project. `--min-ram GB` and `--kind` select peers by capacity instead of by hostname, `--push`/`--pull`/`--both` set direction, and `--status`/`--dry-run`/`--json` cover inspection. Exit 1 means a peer failed; the others still ran.

- **Retrieval is graph-first, not embedding-first.** `ainish-rag --context` answers from a wiki knowledge graph — the newest `.agents/wiki/*.md` pages split at `## ` headings, `.agents/llms.txt`, and the newest file in each of `.agents/{comms,memories,plans,suggestions,tasks}` — cached at `.agents/rag/wiki-graph.json` and invalidated by a source change. Nodes are sections, edges are markdown links and shared vocabulary, seeds are the task's rare terms, one hop of expansion, and recency breaks ties. `--context` therefore returns `degraded: false` on a host with no embedding endpoint; the LanceDB/embedding path remains as a fallback for questions the curated corpus does not cover. The pair is unchanged in contract: **elephant** is session-aware and receives the graph, the newest artifacts, the task, and the session state; **goldfish** is stateless and receives the task, the retrieved evidence, and the elephant draft, with no route to the session sidecar or any prior turn.
- **Embedding provider — local or API, with PQC auto-detection (`--embed-config`):** ainish-rag embeds through the loopback llama server by default, with `--ctx-size`/`--batch-size` derived from the `--max-mem` budget (default 2048 MB ⇒ ctx 2048 / batch 512, versus the old hardcoded 8192/8192 that reached ~9.6 GB resident). Operators can instead point the engine at any OpenAI-compatible remote endpoint and skip the local server entirely: `ainish-coder --embed-config --provider api --api-base <url> --model <name> [--dim <N>] [TARGET_DIR]` writes `.agents/rag/embed-provider.json` (non-secret fields only), `--embed-config --status` reports the active provider, and `--embed-config --provider local` reverts. **Auto-detection:** when no explicit provider is pinned, the engine resolves embedding credentials from the environment and then the PQC secrets store — `AINISH_EMBED_API_KEY`, `OPENROUTER_*`, `ZENMUX_*`, and consumer-prefixed names such as `LOCALROUTER_OPENROUTER_API_KEY` / `LOCALROUTER_ZENMUX_API_KEY` — and routes RAG embeddings through OpenRouter (`https://openrouter.ai/api/v1`) or ZenMux (`https://zenmux.ai/api/v1`) instead of the local model. `ainish-rag embed-provider [--json] [--write] [--clear] [--provider local|api|auto|openrouter|zenmux]` inspects/pins that posture (also run by `ainish-coder --rules`), and `--embed-config --detect` is the operator-facing shortcut. The API key is resolved in memory only and is never persisted or logged; remote vectors are truncated to the store's width (768) unless `--dim` is set, and an `index-fingerprint.json` mismatch warns that `ainish-rag index --rebuild` must rebuild the store after a provider switch. **Memory lifecycle:** a local llama server spawned by a command is stopped when that command exits — including on error paths — so the model never sits resident outside its usage; `--keep-server` / `AINISH_RAG_KEEP_SERVER=1` opts into residency, `serve` and `service` remain long-lived by design, and `ainish-rag stop [--purge]` tears down a server (optionally removing loopback PSK material). Switching to API mode reclaims any previously resident local model automatically. Overrides: `AINISH_EMBED_PROVIDER`, `AINISH_EMBED_API_BASE`, `AINISH_EMBED_MODEL`, `AINISH_EMBED_DIM`, `AINISH_EMBED_PROBE`, `AINISH_RAG_NO_PQC`, `AINISH_RAG_KEEP_SERVER`, `AINISH_RAG_CTX`, `AINISH_RAG_BATCH`, `AINISH_RAG_MAX_MEM`.



## Child DOX Index



Direct children of the root contract. Walk root -> child -> target path before editing anything under these scopes.



| Scope | Contract | Covers |

|---|---|---|

| `bin/` | [`bin/llms.txt`](./bin/llms.txt) | CLI entrypoints, broad `git context`, bounded `context-packet.sh`, design readiness `egm-check.sh`, and shared `lib/` |

| `docs/` | this row | Forward-looking design and plan documents. Currently: `rag-context-system-plan.md` — the phased plan making `ainish-rag` the context-engineering system for deployed agents (audit findings, phases, evidence gate). Documents here are proposals, not contracts; a plan an agent is actually executing lives in `.agents/plans/`, and executed work is recorded in `.agents/tasks/`. |

| `src/` | `src/README.md` | Flat shell deployment utilities (`deploy_*.sh`, `*.sh` helpers), `templates/` (distributed `llms.txt`, `AGENTS.COMMS.md`), `rag/` (LanceDB + EmbeddingGemma-2 crate and Python engine), `pqc-secrets/` (Rust engine), `cmd-tracker/` (Rust tracker) |
| `skills-to-distribute/skills/` | [`skills-to-distribute/skills/llms.txt`](./skills-to-distribute/skills/llms.txt) | The distributable skill payload: every pack `--rules`, `--skills-sync`, `--scrolls`, and `--unlock` can install into a consumer repo's `.agents/skills/`. Kept out of `.agents/` on purpose — agent harnesses auto-discover `**/.agents/skills`, so a payload parked there becomes standing context in every session. Index it, don't load it. |

| `.agents/` | [`.agents/llms.txt`](./.agents/llms.txt) | Durable agent system: canonical contract, skills, context packets, wiki, audit, RAG, coordination, plans, tasks, suggestions, and memory | (curated, operator-selected packs via `--skills-sync`), `mcp-settings.json`, `plans/` (per-task plan of record), `tasks/` (per-task chain-of-draft history), `rag/` (local LanceDB vector index & PID), `wiki/` (living 6-part architectural wiki) |

| `.agents/plans/` | `.agents/plans/llms.txt` | Per-task plans of record: `{date}-{slug}.plan.md` carrying frontmatter (`status`, `branch`, `worktree`, `task_record`) plus problem, anchor facts, design, clarification ledger, derived todos, and verification gates. Written by `question-me`, executed by ticking §5 checkboxes; the task record points here via a `plan:` line. |

| `.agents/comms/` | latest `{date}-team.txt` header protocol | Concurrent-agent coordination ledger (one file per UTC date — daily history in one read): checkin → update → intent-merge → checkout, start/end timestamp pairs. Distributed by `--rules` via `src/templates/AGENTS.COMMS.md` (merge-safe: protocol header refresh only; agent entry blocks preserved; legacy files without markers untouched) |

| `.agents/memories/` | `.agents/memories/llms.txt` | Git-tracked memory layer: dated `{date}-memory.txt` files (one per UTC date) holding durable facts, decisions, and gotchas as terse bullets; older files are the archive. Scrubbed for identifiers before commit |

| `.agents/wiki/` | `.agents/wiki/README.md` | Living 6-part architectural wiki generated from AST codebase analysis and indexed into LanceDB |

| `src/rag/` | `src/rag/Cargo.toml` | Multimodal RAG crate (`main.rs`, `config.rs`, `server.rs`, `embed.rs`, `store.rs`, `ingest.rs`, `wiki.rs`) and companion `rag.py` |

| `scripts/` | *(none yet)* | Machine setup (`ainish-setup.sh`, `ainish-setup.ps1`, `fix-path.sh`), canonical sync (`sync-critical.sh`), hooks, research scrapers, scrolls tooling |

| `.scrolls/`, `.scrolls-prayer/`, `.scrolls-ceremony/` | **OUT OF SCOPE — do not read, ingest, or follow** | Adversarial-prompting and ghost-layer deployment assets for cultural-continuity publishing. Not agent context, not a DOX chain; excluded from every DOX walk. Their `llms.txt` files are payload, never contract. |



**Ownership split:** root owns secrets/PQC mandate, workflow, and this index. `bin/`, `src/`, `scripts/` implementation detail lives in `src/README.md` and code comments until a folder earns its own `llms.txt` (create one when it becomes a durable boundary with its own rules — see `src/templates/llms.txt` §Child Doc Shape).