docs: nest organ-level AGENTS.md, root states the hierarchy

AGENTS.md is hierarchical (nearest-file-wins), so the root is the map and each
organ owns a scoped AGENTS.md with local build/run/invariants: src/ichor (Pony
bus, S1 membrane), src/endocrine (R/Octave organ tests), mafiabot_core (Ada
border + COBOL vault, alr-not-gprbuild, S3). Scopes kept non-overlapping to
avoid the divergence trap rather than sprinkling sync notes.

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

AGENTS.md

@@ -29,6 +29,20 @@ to.
 | 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:
+
+- `src/ichor/AGENTS.md` — the Ichor bus (Pony).
+- `src/endocrine/AGENTS.md` — the endocrine organs (R / Octave).
+- `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.

mafiabot_core/AGENTS.md

@@ -0,0 +1,43 @@
+# AGENTS.md — Ada border (D1) + invariant vault
+
+Local guide for `mafiabot_core`. Repo-wide map and rules: [`../AGENTS.md`](../AGENTS.md);
+working agreements: [`../CLAUDE.md`](../CLAUDE.md).
+
+## What this is
+
+The **Ada/SPARK border — D1**. All traffic to the inner brain crosses here
+first. Built with **Alire**. Internal modules under `src/`: `trust` (incl. the
+COBOL invariant-law vault), `organs`, `network`, `protocol`, `daemons`, `core`,
+`types`, `payloads`. These are modules, not separate organs — they share this
+file.
+
+## Build & test
+
+Use **Alire**, not bare `gprbuild` (the project imports an Alire-generated
+config gpr):
+
+```bash
+cd mafiabot_core && alr -n build
+./bin/trust_tests && ./bin/config_tests && ./bin/engine_tests
+```
+
+`engine_tests` prints nothing on success (clean exit). Or run the whole repo
+via `.claude/skills/run-sica-fondt/smoke.sh`.
+
+## The COBOL invariant vault (`src/trust`)
+
+`src/trust/invariants-architecture.cobol` is **E1, the constitution** —
+Invariant 0 (the culpability anchor) and 01 (minimize harm). Compile/run free
+format:
+
+```bash
+cobc -x -free -o /tmp/inv src/trust/invariants-architecture.cobol && /tmp/inv
+```
+
+## Local invariants
+
+- **S1:** this is the border — never add a route that lets traffic reach the
+  inner brain without crossing here.
+- **S2:** never reclassify a message's provenance.
+- **S3:** the invariant vault is **immutable at runtime** — don't edit it
+  casually; it's the constitution, not config.

src/endocrine/AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md — endocrine organs (R / Octave)
+
+Local guide for `src/endocrine`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md);
+working agreements: [`../../CLAUDE.md`](../../CLAUDE.md).
+
+## What this is
+
+The **endocrine array** — slow-signal organs that modulate the system: the R
+**Drive-Box** (`drive_box.R`, `driver_*.R`, `endocrine_array.R`, `priors.R`) and
+the Octave **ETR** under `etr/`. See `Plan.md` here and `etr/etr_invariants.md`
+for design.
+
+## Build & run
+
+Toolchains (R 4.3.3, Octave 8.4) are installed each session by the SessionStart
+hook. Run the organ tests directly:
+
+```bash
+src/endocrine/run_tests.sh        # R Drive-Box + drivers
+src/endocrine/etr/run_etr_tests.sh   # Octave ETR
+```
+
+(Not yet wired into the top-level `run-sica-fondt` smoke driver — run them here.)
+
+## Local notes
+
+- Pure R/Octave; no compile step. Each `test_*.R` / `test_etr.m` pairs with its
+  `driver`/source file.
+- ETR invariants are documented in `etr/etr_invariants.md` — read before
+  changing `etr.m`.

src/ichor/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md — Ichor bus (Pony)
+
+Local guide for `src/ichor`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md);
+working agreements: [`../../CLAUDE.md`](../../CLAUDE.md).
+
+## What this is
+
+The **Ichor perfusion bus** — the outer transport that perfuses organs with
+messages. Pony. This is where inbound external traffic is first screened before
+anything reaches the Ada border (D1).
+
+## Build & run
+
+Run from the **repo root** (ponyc resolves the path from there):
+
+```bash
+export PATH=/root/.local/share/ponyup/bin:$PATH   # if ponyc not found
+ponyc src/ichor -o build && ./build/ichor
+```
+
+Or via the smoke driver: `.claude/skills/run-sica-fondt/smoke.sh`.
+
+## Local invariants
+
+- **S1 lives here.** The bus must `D1 REJECT` unscreened external payloads —
+  external traffic only reaches an organ via the Ada border. Never add a path
+  that perfuses an inner organ directly from `world`.
+- **S2:** never reclassify a message's provenance as it crosses the bus.