docs: sharpen AGENTS.md to instructions-only, map stays in docmap.yaml

Clean role split: AGENTS.md = instructions (nesting rule + behavioral rules),
docmap.yaml = map (locations). Dropped the inline organ-structure description;
it now points at docmap.yaml -> organs instead of restating the map in prose.

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

AGENTS.md

@@ -1,28 +1,21 @@
 # AGENTS.md
 
-How to use the documents in this repo — the prose signpost. The full
+**Instructions** for agents (any tool) working in this repo. The **map** — where
-directory/document index lives in [`docmap.yaml`](docmap.yaml) (machine-readable;
+everything lives: read-order, doc routing, the organ list, build commands — is
-start there to find which file covers what, the newcomer read-order, and the
+[`docmap.yaml`](docmap.yaml). Claude-specific guidance: [`CLAUDE.md`](CLAUDE.md).
-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.
 
-## Scope & nesting
+## How these files work
-
+- AGENTS.md files are **instructions, and they nest**: an agent reads the
-`AGENTS.md` is **hierarchical** — an agent reads the *nearest* one walking up
+  *nearest* one walking up from the file it's editing. Each organ has its own
-from the file it's editing. So this root file is the **map**; each organ owns a
+  (listed in `docmap.yaml` → `organs`).
-scoped `AGENTS.md` with its *local* build/run/invariants (see `docmap.yaml` →
+- Keep each file to **instructions for its scope**, non-overlapping. Locations
-`organs` for the list and paths).
+  belong in `docmap.yaml`, not in prose here — don't duplicate the map.
-
-Keep scopes **non-overlapping**: the root signposts, 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
 
+## Rules
 - **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
+- **Honor the invariants** (S1/S2/S3 — text in `CLAUDE.md`): the Ada border and
-  COBOL vault are not optional.
+  the COBOL vault are not optional.
-- **Verify, then commit.** Run the smoke driver (`docmap.yaml` → `smoke`); commit
+- **Verify, then commit.** Run the smoke driver; commit + push before leaving
-  + push before leaving (the container is ephemeral).
+  (the container is ephemeral).
-- **Keep the docs honest.** If you change behavior, update the doc — and the
+- **Keep the map honest.** Add an organ or move a doc → update `docmap.yaml`.
-  `docmap.yaml` entry — that describes it. Keep `CLAUDE.md` ≤200 lines and this
+  Keep `CLAUDE.md` ≤200 lines and this file ≤100.
-  file ≤100.