Seed an AI-legible project memory map that stays small

One file (AGENTS.md) that bootstraps the rest: rules, the file map to create,
what belongs in each file, the first-session interview order, and the list of
anti-patterns that killed the previous map (1,308-line guide, 63 task files,
narrative history inline, sessions skimming 56k tokens of context).

Separates four kinds of content by read frequency:
  rules/invariants  -> AGENTS.md          (every session)
  subsystem truth   -> docs/ai/<topic>.md (only the matching one)
  lookups           -> environment.md     (grepped, never read)
  retired decisions -> decisions.md       (only when re-opening one)

Caps are enforced, not promised: scripts/verify.sh checks doc budgets before
the build, so a commit that pads a capped file fails. Proven both ways — it
passes clean and exits 1 on an over-cap file.

scripts/scope-check.sh blocks edits outside the declared file list.
templates/ holds fill-in skeletons for the seven files a project must create.

CC0: copy it, rename it, sell it, no attribution needed.

templates/ai.md

@@ -0,0 +1,30 @@
+# <Product> (repo `<name>`) — AI guide & router
+
+> Read [`AGENTS.md`](AGENTS.md) first: the rules and the invariants. This file is the **map** —
+> what the product is, how it is built, and where the truth lives. No narrative, no status.
+
+## What it is
+
+<Five lines max: what it does, for whom, the platform, the one thing that makes it different.>
+
+## Build, run, test
+
+<The commands actually used. Link to docs/ai/environment.md for the full runbook.>
+
+## Architecture
+
+| Path | Role |
+|---|---|
+| `<dir>/` | <one line> |
+
+## Where the truth lives
+
+| Subsystem | File | Read when |
+|---|---|---|
+| <subsystem> | [`docs/ai/<topic>.md`](docs/ai/<topic>.md) | <the trigger> |
+
+Lookup, not reading: [`MyMistakes.md`](MyMistakes.md) · [`TASKS.md`](TASKS.md) · `<dir>/index.md`.
+
+## Current state
+
+[`HANDOFF.md`](HANDOFF.md) — do not restate it here.

templates/decisions.md

@@ -0,0 +1,12 @@
+# Decisions log — retired paths, kept so they are not re-litigated
+
+One dated line per decision that **no longer governs**, with the reason it died. Read only when
+about to re-open one.
+
+## <Domain>
+
+- **<YYYY-MM-DD>** <decision> — superseded by <what>, because <why>.
+
+## Out of scope — permanently
+
+- <thing> — <the reason it will not be built, not "later">.

templates/docs-ai-index.md

@@ -0,0 +1,10 @@
+# docs/ai — index
+
+Subsystem truth, split out so a session pays only for what its task touches. `ai.md` routes here;
+`AGENTS.md` carries the invariants that hold across every subsystem.
+
+| File | Covers | Read when |
+|---|---|---|
+| [`environment.md`](environment.md) | Hosts, ports, paths, build/run/test commands, test map | building, running, adding a test |
+| [`decisions.md`](decisions.md) | Retired paths with cause of death; the permanent out-of-scope list | about to re-open a settled decision |
+| <topic>.md | <subsystem> | <trigger> |

templates/environment.md

@@ -0,0 +1,34 @@
+# Environment — lookups
+
+Facts you grep for, never read start to finish. Add a line the first time one costs a hunt.
+
+## Hosts & access
+
+| Host | Address | Role |
+|---|---|---|
+| <host> | <ip> | <role> |
+
+SSH / credentials: <where they live, never in this repo>.
+
+## Build, run, test
+
+```bash
+<clean command>
+<build command>
+<run command>
+<test command>
+```
+
+<The traps: which toolchain, which host, why not the other one. Notes on warnings, restores, caches.>
+
+## Paths
+
+- App data / config: `<path>`
+- Logs: `<path>` (rotation: <rule>)
+- Build output / artifacts: `<path>`
+
+## Test map
+
+| Area | Test file | Notes |
+|---|---|---|
+| <area> | `<file>` | <known flaky? slow? needs env?> |

templates/handoff.md

@@ -0,0 +1,18 @@
+# HANDOFF — <YYYY-MM-DD> (<one-line state>)
+
+## State
+
+- Branch `<branch>`, worktree <clean / N files dirty>, **<pushed|unpushed>** (`<last sha>`).
+- In flight: <the unit that is partially done, if any — file names and what is left>.
+
+## Next action
+
+<The single next unit, one sentence on why it is next. Nothing else.>
+
+## Landmines (live, not historical)
+
+- <path / port / flaky test / do-not-touch rule — one line each, only what would bite today.>
+
+## Pending the user
+
+- <decision, hands-on check, or measurement that is blocked on them>

templates/index.md

@@ -0,0 +1,9 @@
+# <dir> — index
+
+One line on what this directory owns, then every file with its purpose. Details live in the files.
+
+| File | Purpose |
+|---|---|
+| `<File>` | <what it does, one line> |
+
+Related: [`../other/index.md`](../other/index.md)

templates/mymistakes.md

@@ -0,0 +1,23 @@
+# MyMistakes — failure log + recipes
+
+## Recipes (grep here FIRST)
+
+<How-tos and workarounds, with verbatim commands. A solution recorded once ends the loop;
+an un-recorded one guarantees the same wall twice.>
+
+### <Recipe name>
+
+```bash
+<exact commands>
+```
+
+Traps: <the two or three things that actually go wrong>.
+
+## Failure log (newest first)
+
+### <YYYY-MM-DD> — <symptom in six words>
+
+- **Symptom:** <what was observed>
+- **Wrong guess:** <what was tried, and why it looked right>
+- **Actual cause:** <the mechanism>
+- **Rule now:** <what prevents the repeat — and where it is written down>

templates/schema.md

@@ -0,0 +1,35 @@
+# Memory map — conventions
+
+## Why files, not a database
+
+Grep-able, diffable, human-editable, portable; git gives versioning and history for free. Files
+form a graph: each file is a node, each relative link an edge.
+
+## Inventory
+
+| File | Role | Entry point? |
+|---|---|---|
+| `AGENTS.md` | Rules + invariants | **always read** |
+| `ai.md` | Router: product, build, architecture, where truth lives | yes |
+| `HANDOFF.md` | Current state (≤40 lines, overwritten) | yes |
+| `TASKS.md` | Active queue | when asking "what's next" |
+| `docs/ai/*.md` | Subsystem truth, one file each | when the task touches it |
+| `MyMistakes.md` | Failure log + recipes | grep first |
+
+## Rules
+
+1. **Semantic filenames.** No codes, no abbreviations.
+2. **One `index.md` per code directory**, listing every file with a one-line purpose.
+3. **Links over hierarchy.** Anything unreachable from `ai.md` may as well not exist.
+4. **Stale facts get fixed, not appended.**
+5. **Progressive disclosure.** Detail lives one level down, never crammed into the router.
+
+## Reading order
+
+1. `AGENTS.md` → 2. `HANDOFF.md` → 3. `ai.md` → 4. the one `docs/ai/<topic>.md` → 5. `<dir>/index.md`
+→ 6. the source (always the authority over any memory file).
+
+## Integration rule
+
+Every change ships with the facts it **falsifies** corrected, in the same commit. Broader
+restatement may be batched at a milestone.

templates/tasks.md

@@ -0,0 +1,22 @@
+# TASKS — the active queue
+
+> One line per live item; detail lives elsewhere. Done work goes to [`TASKS/archive.md`](TASKS/archive.md).
+> Markers: ☐ queued · 🔶 in progress · ⏳ blocked · ⏸ deferred · ❌ retired.
+
+## Next up
+
+**<Task>** — <five lines: what exists today, what is missing, the one unit, its test.>
+
+## Queue
+
+| Task | Status | Scope | Detail |
+|---|---|---|---|
+| <id> | ☐ | <one line> | <link> |
+
+## Pending the user (not programming)
+
+- <hands-on check / decision / take>
+
+## Release gates (before the first shipped build)
+
+- <gate — one line each>