docs: make AGENTS.md canonical and correct its drifted claims

[KenTaniguchi-R]

The repo only had CLAUDE.md, so Codex, Cursor and anything else that reads AGENTS.md got nothing at all. There was no AGENTS.md to update — none in the tree, none anywhere in git history.

Next.js' own generator (node_modules/next/dist/server/lib/generate-agent-files.js) treats AGENTS.md as the real instructions file and CLAUDE.md as a one-line @AGENTS.md import. Its managed rules block goes to whichever file already hosts it, so moving the block into AGENTS.md is also what stops next dev from writing into CLAUDE.md on every run. The block is byte-identical — verified by calling the generator's own hasCurrentAgentRules(), which returns true.

Claims that had drifted

Each checked against the code rather than carried across:

• The two docs it called "the authoritative reference" do not exist. docs/superpowers/specs/2026-05-09-ledgr-design.md and -testing-architecture-design.md are both missing — dead links at the top of the file agents are told to read first. Replaced with a pointer to docs/superpowers/ and a note that the code wins when a doc disagrees.
• SimpleFIN was invisible. src/lib/simplefin/ is a complete sync path (client, schemas, sync, queries, recurring), but the stack table said Plaid-only and the conventions said "Plaid is the primary feature."
• Three subsystems were absent entirely: the MCP server (src/lib/mcp/ — tools, OAuth, widget apps), the cron scheduler (src/lib/scheduler/), and the .well-known OAuth metadata routes.
• Encryption keys are versioned (ENCRYPTION_KEY, then ENCRYPTION_KEY_V2…), not a single key.
• 30 tables, not 29. categorization/ has no orchestrator.ts.
• Commands were missing test:changed, test:mutate:diff, build:mcp-widgets, reset-password, and two backfills.

Added

Things that cost real time to discover in the session that produced #162:

• The UI primitives are Base UI, not Radix — ToggleGroup takes value: string[], PopoverTrigger takes render, and so on.
• shadcn add emits import { cn } from "cn" and tries to install a package by that name, and rewrites package.json versions it should leave alone (it downgraded recharts on every run).
• components/ui/chart.tsx carries two deliberate local edits a regenerate would clobber.
• Charts must go through ChartContainer; Recharts' bare <Tooltip> is a hardcoded white box that is unreadable in dark mode.
• Vitest is environment: "node" matching *.test.ts only, so React component tests are not currently possible without a config change — worth knowing before someone tries to write one.
• Migration hazards: generated NOT NULL adds ship without a backfill, and hand-editing a journal when timestamp makes older Docker images replay and crash-loop.
• CI reds on the self-hosted runners are often contention rather than the diff.
• Transfers are excluded from spend, and investment activity is tagged as a transfer at sync time — the mechanism behind feat(transactions): exclude investment-account activity from spending/income #157/fix(dashboard): stop Account Balances and Investments from clipping their own numbers #159, which was nowhere in the docs.

One judgment call to check

AGENTS.md states that docs/superpowers/specs/2026-07-07-ledgr-hosted-beta-design.md describes a direction that was abandoned, and that self-hosting is the only deployment model. That comes from a maintainer decision, not from anything in the repo — the README backs the self-hosted framing throughout, but the abandoned-spec claim is worth a second look before merge.

Testing

pnpm lint and pnpm typecheck pass. No code changes.

🤖 Generated with Claude Code