[jayleaton]

Problem

JJ: "The README is very technical. It should be simpler and talk about the performance gains, cost improvements and architecture choices for AI agents." It was 377 lines of deploy, secrets, backup and security detail.

Fix

README.md   377 lines ──▶ 118 lines: what it is · how it fits together · performance · cost · built for AI agents · quick start · learn more
docs/       + development.md  deploy.md  secrets.md  backups.md  security.md  admin.md   (the old sections, verbatim)

1. Pure move (abb604c): every technical section moves verbatim into a topic file. Headings drop one level; nothing is reworded.

   File	From README
   docs/development.md	Try the API, Commands, Look and feel, Stack, Working on it
   docs/deploy.md	Deploy to Railway, Profiles, Cost, Preview environments, Under the hood
   docs/secrets.md	Secrets, Secrets and Doppler, Where secrets live
   docs/backups.md	Backups and restore (fix(docs): Railway volume snapshot schedules are settable through its API, not dashboard-only #99's sentence is unchanged, as on main; fix(docs): Railway volume snapshot schedules are settable through its API, not dashboard-only #99 is still open)
   docs/security.md	Security
   docs/admin.md	Admin dashboard

2. Links (b044327): relative links in the moved sections, and every README "…" pointer in AGENTS.md, .env.example, deploy/ (comments, platform.yaml, one railway-setup hint string) and docs/, now name the docs/ file. AGENTS.md's facts are unchanged; only its links and the "Docs" pointer (README.md or its topic file in docs/) changed.

3. Rewrite (README commit): plain language, and every number has a source:

   Claim	Source
   16.5 MB static binary	go build -trimpath -ldflags='-s -w' ./apps/web/cmd/server → 16,453,794 bytes (Go 1.26.8)
   34 KB client JS (13 KB gzipped)	apps/web/ui/static/datastar-1.0.4.js: 33,553 B; gzip -9: 13,386 B. It's the only script.
   83 MB RSS at start, 93 MB after 200 page loads	that binary on a throwaway Postgres: VmRSS 82544 kB, then 92860 kB
   home page 17 KB, ~0.4 ms	curl size 17,470 B; server log ms=0.423
   ~75 MB on Railway; ≈ $1.55 / $3.10 / $6.00 per month; image ~5 MB	the old README's Cost and Stack sections (now docs/deploy.md, docs/development.md)
   CI 14 s docs-only, 65 → 33 s one package, 54 s all packages	perf(ci): parallel checks in one job, test only tested packages #86
   29 s median race suite; 60 s / 10 s budgets	perf(devloop): parallel tests, test-time budgets, 1s probes and a dev-loop bench #74, AGENTS.md "Budgets"
   9 → 1 billed minutes per docs PR; ~84,000 → ~18,500–22,100 minutes per 30 days	perf(ci): ~43% fewer billed Actions minutes per PR at the same wall time #54, perf(ci): one CI job by default; ci-ok as a commit status; timeouts at ~2x averages #67
   check-fast under 1 s docs, under 10 s full warm	AGENTS.md "Verifying"

   Next.js comparison: left out. The old template documents no size or memory figures, and building it here would break the compute rule. Route access (feat/route-access) and the naming lint (chore/naming-lint) are listed under Coming soon, not as shipped.

Parallel branches: add your doc sections to the matching docs/*.md file, not to README.md.

Not changed: the Makefile comment # Backups (README "Backups and restore"). The Makefile is on scripts/affected.sh's full-run list, so a one-word comment fix would force a full CI run. It can ride along with the next real Makefile change.

Verified

• No line lost: a script checked that every non-empty line of the old README appears in README.md or a docs/ file: missing: [].
• Links: every ](…), src= and href= target and every #anchor in tracked markdown: 53 relative links checked in 19 markdown files, 0 broken. The same script on main: 24 … 0 broken.
• make check-fast: ok in 1.1s.
• GitHub rendering: gh api markdown (gfm) renders 7 sections and 4 tables.

Merge risk

Docs and comments only, plus one hint string in deploy/cmd/railway-setup. Branches that edit README sections will conflict; move those edits into the matching docs/ file.

🤖 Generated with Claude Code