docs: make AGENTS.md the only agent guide, restructured into five sections

AGENTS.md now holds the instructions and CLAUDE.md and GEMINI.md are
pointers to it. Three files of instructions become three files that
disagree; one file every agent reads cannot.

The content is reorganised rather than rewritten, into: the invariants,
the guards that fail the build, the validation this codebase deliberately
does not perform, the environment, and where to read next. Every guard
now names the test that catches it, and the two rules with no test behind
them are called out as such, because "only review catches this" is
information the reader needs.

Restructuring surfaced one rule that was missing here entirely — sw.js
must stay unhashed and be served no-cache — which had only ever been
written down in ARCHITECTURE.md.

Dropped: the `bun init` boilerplate code samples. Every rule they carried
is still stated; the hello-world test and the three frontend snippets are
not.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/TODO.md

@@ -59,7 +59,7 @@ The reasoning below is kept because it is the reasoning, not a plan.
   converting money at a number the user never chose.
 - Domain purity forces the shape: `createSeedDataset` takes the rates as an
   **argument**; the env read lives in a new `src/store/bakedRates.ts`, in the
-  store layer, using the `try/catch` accessor pattern (see CLAUDE.md gotchas).
+  store layer, using the `try/catch` accessor pattern (see AGENTS.md gotchas).
 
 ## 3. Visual redesign — sub-projects 1 and 2 of 4 DONE
 

docs/plans/2026-09-01-budget-app.md

@@ -72,7 +72,7 @@ Tests are co-located: `src/domain/money.test.ts` beside `src/domain/money.ts`.
 
 **Files:**
 - Create: `package.json`, `tsconfig.json`, `bunfig.toml`, `build.ts`, `src/index.ts`, `src/index.html`, `src/frontend.tsx`, `src/index.css` (all via `bun init`)
-- Modify: `CLAUDE.md` (append project invariants), `.gitignore`
+- Modify: `AGENTS.md` (append project invariants), `.gitignore`
 - Delete: `src/APITester.tsx`, `src/logo.svg`, `src/react.svg`
 - Test: `src/domain/smoke.test.ts`
 
@@ -158,9 +158,9 @@ Expected: PASS, 1 test.
 Run: `bun --hot src/index.ts`
 Expected: server starts, and the printed URL shows "Budget 2.0". Stop it with Ctrl-C.
 
-- [ ] **Step 7: Append project invariants to CLAUDE.md**
+- [ ] **Step 7: Append project invariants to AGENTS.md**
 
-The scaffolded `CLAUDE.md` documents Bun idioms. Append the rules specific to this project:
+The scaffolded `AGENTS.md` documents Bun idioms. Append the rules specific to this project:
 
 ```markdown
 ## Project invariants (Budget 2.0)
@@ -196,7 +196,7 @@ git add -A
 git commit -m "chore: scaffold Bun + React + shadcn project
 
 bun init --react=shadcn, with the demo API routes removed since this app
-has no backend. Adds project invariants to CLAUDE.md and a smoke test
+has no backend. Adds project invariants to AGENTS.md and a smoke test
 proving the domain layer imports with no DOM."
 ```
 
@@ -253,7 +253,7 @@ export const CURRENCY_DIGITS: Record<Currency, number> = {
   EUR: 2,
 };
 
-/** A float amount paired with its currency. See CLAUDE.md for rounding rules. */
+/** A float amount paired with its currency. See AGENTS.md for rounding rules. */
 export interface Money {
   amount: number;
   currency: Currency;

docs/specs/2026-09-01-budget-app-design.md

@@ -310,7 +310,7 @@ migrations are mandatory rather than optional.
 
 ## Agent support files
 
-- `CLAUDE.md` — the `bun init` scaffold provides Bun idioms ("use `bun test`",
+- `AGENTS.md` — the `bun init` scaffold provides Bun idioms ("use `bun test`",
   "don't use vite", HTML imports). This project extends it with its own
   invariants: the domain layer stays free of React and IndexedDB, money
   rounds at every boundary, the last distributed part is computed by

docs/specs/2026-09-02-design-foundation-design.md

@@ -48,7 +48,7 @@ colours app components may name.
 
 ### The brand teal is `--primary`, never `--accent`
 
-CLAUDE.md's hardest-won rule is "never define a bare `--accent`", paid for with
+AGENTS.md's hardest-won rule is "never define a bare `--accent`", paid for with
 an app-wide contrast bug. The mechanism matters: shadcn uses `--accent` as a
 hover **background** with `--accent-foreground` as the text on it. Setting one
 without the other repaints the background and leaves the text behind.

docs/specs/2026-09-02-month-view-design.md

@@ -52,7 +52,7 @@ below the unchanged month `<header>`.
 
 ### The allocation meter scales to `max(income, allocated)`
 
-Not to income. Over-budget is always allowed (CLAUDE.md), and allocating past
+Not to income. Over-budget is always allowed (AGENTS.md), and allocating past
 income is the ordinary way that shows up here, so the meter has to render it
 rather than cap at a full bar: the overflow past the income mark paints
 `--overspend`, and the label reads past 100%. Capping would make