docs: extract directory/doc index into docmap.yaml

AGENTS.md was carrying the read-order + routing table inline; moved that to an
independent machine-readable docmap.yaml (read_order, routing, design_docs,
organs with build cmds, invariants, smoke). AGENTS.md slims to a prose signpost
(54->28 lines) pointing at it; CLAUDE.md docs-map lists it. YAML validated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015hmgREHNsxYCuim33yUF2c

AGENTS.md

@@ -1,54 +1,28 @@
 # AGENTS.md
 
-How to use the documents in this repo. This is the map: read it first, then go
+How to use the documents in this repo — the prose signpost. The full
-to the right doc for your task. Keep this file under **200 lines** (aim for
+directory/document index lives in [`docmap.yaml`](docmap.yaml) (machine-readable;
-**100**) — it's a signpost, not a manual. The depth lives in the docs it points
+start there to find which file covers what, the newcomer read-order, and the
-to.
+organ list). Working agreements and invariant text: [`CLAUDE.md`](CLAUDE.md).
-
+Keep this file lean (≤100 lines) — depth lives in the docs it points to.
-## Read in this order
-
-1. **`README.md`** — what sica-fondt is.
-2. **`SOUL.md`** — intent and principles; the "why."
-3. **`docs/`** — the architecture in detail:
-   - `bus-topology.md` — the Ichor bus and organ wiring.
-   - `gen03_state_of_architecture.md` — current architectural state.
-   - `gen03_body.md`, `gen03_self.md` — body/self model.
-   - `plans/` — forward-looking plans.
-4. **`CLAUDE.md`** — working agreements, build/run, invariants. Read before
-   making changes.
-5. **`ONBOARDING.md`** — setup checklist and first-task walkthrough (for people).
-
-## Which doc for which task
-
-| If you want to… | Go to |
-|---|---|
-| Understand the system at a high level | `README.md`, `SOUL.md` |
-| Understand the architecture / organ model | `docs/` (start: `bus-topology.md`) |
-| Build, run, or smoke-test | `run-sica-fondt` skill → `smoke.sh` |
-| Know the rules before editing | `CLAUDE.md` (working agreements + invariants) |
-| Onboard a new teammate | `ONBOARDING.md` |
-| Find which doc covers a topic | this file |
 
 ## Scope & nesting
 
 `AGENTS.md` is **hierarchical** — an agent reads the *nearest* one walking up
 from the file it's editing. So this root file is the **map**; each organ owns a
-scoped `AGENTS.md` with its *local* build/run/invariants:
+scoped `AGENTS.md` with its *local* build/run/invariants (see `docmap.yaml` →
+`organs` for the list and paths).
 
-- `src/ichor/AGENTS.md` — the Ichor bus (Pony).
+Keep scopes **non-overlapping**: the root signposts, the organs detail. Don't
-- `src/endocrine/AGENTS.md` — the endocrine organs (R / Octave).
+restate the root in an organ file (that's how the two drift) — link up instead.
-- `mafiabot_core/AGENTS.md` — the Ada border (D1) + the COBOL vault under
-  `src/trust`.
-
-Keep scopes **non-overlapping**: the root maps, the organs detail. Don't restate
-the root in an organ file (that's how the two drift) — link up instead.
 
 ## Rules of the road
 
 - **Design before code.** The design docs are the source of truth; code follows.
 - **Honor the invariants** (S1/S2/S3 in `CLAUDE.md`) — the Ada border and the
   COBOL vault are not optional.
-- **Verify, then commit.** Run the smoke driver; commit + push before leaving
+- **Verify, then commit.** Run the smoke driver (`docmap.yaml` → `smoke`); commit
-  (the container is ephemeral).
+  + push before leaving (the container is ephemeral).
-- **Keep the docs honest.** If you change behavior, update the doc that
+- **Keep the docs honest.** If you change behavior, update the doc — and the
-  describes it — and keep `CLAUDE.md` ≤200 lines and this file ≤200 (≤100 pref).
+  `docmap.yaml` entry — that describes it. Keep `CLAUDE.md` ≤200 lines and this
+  file ≤100.

CLAUDE.md

@@ -50,4 +50,5 @@ Per-unit commands and gotchas live in that skill's `SKILL.md`. Toolchains
 - `README.md`, `SOUL.md` — the project and its intent.
 - `docs/` — architecture (`bus-topology.md`, `gen03_state_of_architecture.md`, …).
 - `ONBOARDING.md` — new-teammate setup and walkthrough.
-- `AGENTS.md` — which document to read for what.
+- `AGENTS.md` — prose signpost for how the docs fit together.
+- `docmap.yaml` — machine-readable index: read-order, doc routing, organ list.

docmap.yaml

@@ -0,0 +1,56 @@
+# docmap.yaml — directory & document index for sica-fondt.
+#
+# The independent, machine-readable map referenced by AGENTS.md. AGENTS.md stays
+# prose (scope + rules); this stays data (where things are). Keep in sync with
+# the tree. Invariant text is authoritative in CLAUDE.md — mirrored here as a
+# pointer only.
+
+docs:
+  read_order:                       # newcomer reading path
+    - README.md                     # what sica-fondt is
+    - SOUL.md                       # intent and principles — the "why"
+    - docs/                         # architecture in detail
+    - CLAUDE.md                     # working agreements, build/run, invariants
+    - ONBOARDING.md                 # newcomer setup + first task
+
+  routing:                          # which doc for which task
+    high_level_overview: [README.md, SOUL.md]
+    architecture: [docs/bus-topology.md, docs/gen03_state_of_architecture.md]
+    build_run_test: .claude/skills/run-sica-fondt/   # smoke.sh
+    rules_before_editing: CLAUDE.md
+    onboard_teammate: ONBOARDING.md
+    find_which_doc: AGENTS.md       # the prose signpost; this file is its index
+
+  design_docs:
+    docs/bus-topology.md: Ichor bus and organ wiring
+    docs/gen03_state_of_architecture.md: current architectural state
+    docs/gen03_body.md: body model
+    docs/gen03_self.md: self model
+    docs/plans/: forward-looking plans
+
+# Organs — deployable units, each with its own scoped AGENTS.md (nearest-wins).
+organs:
+  - path: src/ichor
+    agents_md: src/ichor/AGENTS.md
+    lang: pony
+    role: Ichor perfusion bus (outer transport); S1 membrane screens external traffic
+    build: "ponyc src/ichor -o build && ./build/ichor"   # from repo root
+  - path: src/endocrine
+    agents_md: src/endocrine/AGENTS.md
+    lang: [r, octave]
+    role: endocrine array — R Drive-Box + Octave ETR
+    build: "src/endocrine/run_tests.sh ; src/endocrine/etr/run_etr_tests.sh"
+  - path: mafiabot_core
+    agents_md: mafiabot_core/AGENTS.md
+    lang: [ada, cobol]
+    role: Ada border (D1) — all traffic crosses here first; COBOL invariant vault in src/trust
+    build: "cd mafiabot_core && alr -n build"            # not bare gprbuild
+
+# Repo-wide invariants — authoritative text in CLAUDE.md.
+invariants:
+  S1: all external traffic crosses the Ada border (D1) first
+  S2: never reclassify a message's provenance
+  S3: the COBOL invariant-law vault is immutable at runtime
+
+# One harness builds and runs every executable unit; want "smoke: ALL GREEN".
+smoke: .claude/skills/run-sica-fondt/smoke.sh