diff --git a/CLAUDE.md b/CLAUDE.md
index 3559068..ef4e496 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,6 +11,22 @@
 
 - Organise yourself. Design your own agents when needed. Use git. Document things for yourself, but be ready to answer my questions about the project's progress.
 
+## Code layout
+
+| Path | Role |
+|---|---|
+| `crates/ail/` | CLI entry point — subcommands include `check`, `build`, `run`, `emit-ir`, `prose`, `merge-prose`, `workspace`, `diff`, `manifest`, `render`, `describe`, `deps`, `parse`, `builtins` |
+| `crates/ailang-core/` | AST, canonicalisation, desugaring, workspace types, hash, pretty |
+| `crates/ailang-surface/` | Surface syntax — lex, parse, print |
+| `crates/ailang-check/` | Type and uniqueness/mode analysis, lints, diagnostics |
+| `crates/ailang-codegen/` | LLVM-IR codegen — RC, drop, lambda lowering, match lowering, escape, synth, subst |
+| `crates/ailang-prose/` | Form-A ↔ Form-B prose projection |
+| `runtime/` | C glue around the RC runtime |
+| `bench/` | Regression harnesses (`check.py`, `compile_check.py`, `cross_lang.py`) and the throughput-and-latency runner (`run.sh`); `bench/reference/` holds the hand-C corpus for cross-language ratios |
+| `examples/` | AILang fixtures used by tests and benches |
+| `docs/` | Canonical specs and decisions log — `docs/DESIGN.md`, `docs/JOURNAL.md`, `PROSE_ROUNDTRIP.md` |
+| `agents/` | Subagent definitions (toolchain, versioned); `agents/README.md` is the roster |
+
 ## My role: orchestrator
 
 I am the **orchestrator** of this project, not the implementer. The
@@ -26,7 +42,7 @@ See @agents/README.md
 ### What this means in practice
 
 - **Plan, design, decide** — myself. Architectural choices, scope,
-  invariants, and the contents of `JOURNAL.md` and `DESIGN.md` are
+  invariants, and the contents of `docs/JOURNAL.md` and `docs/DESIGN.md` are
   my work product.
 - **Implement, refactor, write tests, diagnose bugs** — by default,
   delegated. `ailang-implementer` for code changes that follow a
@@ -96,7 +112,7 @@ When deciding whether a proposed feature ships, the test is
 whether an LLM author naturally produces code that uses it AND
 whether the feature measurably improves correctness or removes
 redundancy. Aesthetic appeal does not count; neither does human
-ergonomics. The full criterion lives in DESIGN.md
+ergonomics. The full criterion lives in docs/DESIGN.md
 ("Feature-acceptance criterion").
 
 This is the positive complement to the rule above. Together they
@@ -185,8 +201,8 @@ model).
 After every named iter family closes, the next iter is a
 **tidy-iter**: run `ailang-architect` over the whole surface, read
 its drift report, and resolve every item by either (a) fixing the
-drift, (b) updating DESIGN.md to ratify what shipped, or (c)
-recording in JOURNAL.md that the drift is acceptable and why.
+drift, (b) updating docs/DESIGN.md to ratify what shipped, or (c)
+recording in docs/JOURNAL.md that the drift is acceptable and why.
 
 The tidy-iter is non-optional. Without a scheduled cleanup,
 codebases grow by accretion — every iter adds, none tears out,
@@ -212,7 +228,13 @@ report:
   "LLVM-linkable, performance is extremely important" — guards
   against AILang/C ratios drifting upward over time.
 
-Run all three at every family close. The exit code is the gate:
+Run all three at every family close. The canonical sequence is:
+
+```bash
+bench/check.py && bench/compile_check.py && bench/cross_lang.py
+```
+
+The exit code is the gate:
 
 - **Exit 0 (green).** All metrics within their per-metric
   tolerance vs. `bench/baseline.json`. Tidy-iter can close.
@@ -243,28 +265,28 @@ tidy-iter onward.
 Two non-goals to keep clear: (1) per-metric tolerances are tuned
 for run-to-run noise on a quiet developer machine, NOT the
 language's correctness bar — Decision-10 thresholds (rc/bump ≤
-1.3× / p99/median ≤ 5×) live in DESIGN.md and are evaluated
+1.3× / p99/median ≤ 5×) live in docs/DESIGN.md and are evaluated
 against absolute numbers, separate from the regression check.
 (2) Improvements (metric beat its baseline by more than tolerance)
 do NOT auto-update the baseline; they are surfaced in the report
 so the orchestrator can ratify them via `--update-baseline` with
 a paired JOURNAL entry.
 
-### Roles of JOURNAL.md and DESIGN.md
+### Roles of docs/JOURNAL.md and docs/DESIGN.md
 
-- **DESIGN.md** is the canonical specification. It describes what
+- **docs/DESIGN.md** is the canonical specification. It describes what
   AILang *is*: schema, semantics, invariants, runtime contracts.
-  Every new feature must justify itself against DESIGN.md before
-  it can ship; if the feature requires changes to DESIGN.md,
-  those changes are part of the same iter. DESIGN.md is also the
+  Every new feature must justify itself against docs/DESIGN.md before
+  it can ship; if the feature requires changes to docs/DESIGN.md,
+  those changes are part of the same iter. docs/DESIGN.md is also the
   artefact `ailang-architect` checks the code against during
   drift review.
 
-- **JOURNAL.md** is the decisions log. It records *why* the
+- **docs/JOURNAL.md** is the decisions log. It records *why* the
   project moved the way it did — alternatives considered and
   rejected, lessons from past iters, queued options for future
   work, and the rationale behind choices that does not belong in
-  DESIGN.md (rationale is about the choice, not about the
+  docs/DESIGN.md (rationale is about the choice, not about the
   language).
 
 Together they answer two questions: "what is the language right