docs: add CLAUDE.md + AGENTS.md doc-map chain

CLAUDE.md (<=200 lines): working agreements (you're-the-dev, verify-then-commit,
design-first), build/run via run-sica-fondt, S1/S2/S3 invariants; links to
ONBOARDING.md and AGENTS.md. AGENTS.md (<=100 pref): signpost to every doc and
which to read for which task. ONBOARDING.md now points at AGENTS.md.

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

AGENTS.md

@@ -0,0 +1,40 @@
+# AGENTS.md
+
+How to use the documents in this repo. This is the map: read it first, then go
+to the right doc for your task. Keep this file under **200 lines** (aim for
+**100**) — it's a signpost, not a manual. The 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 |
+
+## 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
+  (the container is ephemeral).
+- **Keep the docs honest.** If you change behavior, update the doc that
+  describes it — and keep `CLAUDE.md` ≤200 lines and this file ≤200 (≤100 pref).

CLAUDE.md

@@ -0,0 +1,53 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository. Keep this file under
+**200 lines**. For team setup and a newcomer walkthrough, see
+[`ONBOARDING.md`](ONBOARDING.md); for how the docs fit together and which to
+read when, see [`AGENTS.md`](AGENTS.md).
+
+## What this is
+
+sica-fondt is a **design-first, polyglot architecture**: an Ichor perfusion bus
+(Pony) feeds an Ada/SPARK border (D1), which fronts the inner brain, with a
+COBOL invariant-law vault as the constitution. The design docs are the source of
+truth; the code follows them.
+
+## Working agreements
+
+- **You're the dev.** When details are missing or a decision is open, make the
+  reasonable call and fill in concrete details — don't leave placeholders or
+  stall to ask, unless something is genuinely ambiguous.
+- **Verify, then commit.** After generating or editing, confirm it works (build
+  / run / `run-sica-fondt` smoke), then commit with a descriptive message.
+  Commit and push before ending a session — the container is ephemeral.
+- **Design before code.** If something feels ambiguous, the answer is usually
+  already written in `docs/`. Sync the design first.
+
+## Build & run
+
+Use the `run-sica-fondt` skill (`.claude/skills/run-sica-fondt/`) — its
+`smoke.sh` builds and runs every executable unit and asserts output:
+
+```bash
+.claude/skills/run-sica-fondt/smoke.sh   # want: smoke: ALL GREEN
+```
+
+Per-unit commands and gotchas live in that skill's `SKILL.md`. Toolchains
+(ponyc/Alire/GnuCOBOL) are reinstalled each session by the SessionStart hook
+`.claude/hooks/install-toolchains.sh`; if `ponyc` isn't found,
+`export PATH=/root/.local/share/ponyup/bin:$PATH`.
+
+## Invariants — do not violate
+
+- **S1:** all external traffic crosses the Ada border (D1) first; never route
+  around it.
+- **S2:** never reclassify a message's provenance.
+- **S3 / vault:** the COBOL invariant-law vault (Invariant 0, the culpability
+  anchor; 01, minimize harm) is immutable at runtime — don't edit it casually.
+
+## Docs map
+
+- `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.

ONBOARDING.md

@@ -61,7 +61,9 @@ Top MCP Servers:
 
 ## Get Started
 
-Your first task: get the project running end-to-end and read the map.
+Your first task: get the project running end-to-end and read the map. Not sure
+which doc to read for what? Start with [`AGENTS.md`](AGENTS.md) — it's the
+signpost to every other document here.
 
 1. Open the repo and let the SessionStart hook finish installing toolchains.
 2. Run the smoke driver to confirm everything builds and runs: