docs: reconcile every doc with what the code actually does

[KIDA-MNESIA]

The docs were last touched around 9f59cfc. Everything since then landed without a doc pass, so the guides describe a repo that doesn't exist. Each fix below is a path a reader can currently walk down and fail on — not a wording preference.

The ones that actively break people

Doc	Said	Reality
CONTRIBUTING.md:12	Node ≥ 18	@capacitor/cli@8.3.3 requires node >= 22, @aws-sdk/client-s3 requires >= 20. Node 18 cannot install the dependency tree.
CONTRIBUTING.md / README.md	test:integration "needs local Postgres + Redis"	It also needs INTEGRATION_DATABASE_URL. Without it server/run-integration-tests.mjs:33-38 prints [integration] skipped and exits 0 — a green that means nothing.
MOBILE_IOS.md:5,175	Xcode + Ruby/CocoaPods; cd ios/App && pod install	There is no Podfile anywhere in the repo. Dependencies are SPM (ios/App/CapApp-SPM/Package.swift). pod install just fails.
MOBILE_IOS.md:49	"temporarily uncomment a server.url"	There is no commented-out server.url. The config's own header says it's "intentionally NOT set". Changed to add.
server/k8s/gke.md:181	AGENT_POD_ADMISSION_MAX default 200	It's 40 (env.ts:236). The doc invites a 5× over-provision. Same stale figure in generic-device-plugin.note:31.
.github/wif-setup.md:70	"Tag deploy: git tag v0.1.0 && git push → auto-rolls that version"	deploy.yml:12 is workflow_dispatch only. A v* tag fires release.yml (Electron) and never touches GKE.
benchmarks/README.md:89	Daily all-four: $240-400/month	Its own table totals $58-101/cycle; daily is $1,740-3,030/month. $240-400 is the weekly figure, mislabeled.

Behaviour that changed under the docs

• PUSH_NOTIFICATIONS.md:27 — described dispatch as living inside POST /conversations/:id/messages. 948016a extracted dispatchMessagePush() and added the cmdReply caller; the doc was still describing the single-path bug that commit fixed.
• PUSH_NOTIFICATIONS.md:160-163 — an "Open item" claiming the notify.push toggle unregisters immediately and needs a relaunch to re-enable. Neither half holds: the toggle only writes a pref, and both the Re-register button and installVisibilityHook() recover in-session. Replaced with a truthful troubleshooting row.
• BYOA.md:544-551 — listed 2 of 9 daemon flags and never mentioned that 3d1ddf1 made --stop/--restart/--pair skip one-shot invocations, so a running --doctor survives a --stop.
• email.md:5 — "shelled through the engine's bash tool". Secure mode runs Claude with --tools ''; there is no Bash tool. The CLI arrives over the cli(argv) MCP bridge.
• RELEASE.md:26,135,167 — auto-updater feed is updates.cumora.ai (the generic provider is first in the build.publish array), GitHub is fallback; build.mac.notarize is a bare true with no teamId key; the poll interval is 30 min (hardcoded in autoUpdater.cjs:175), not 10.
• BYOA.md:540 — ~140KB → a fresh node agent-cli/build.mjs produces 337,785 bytes.
• README.md:74 / SECURITY.md:81 — both claimed .env.example is the complete annotated variable list. It omits AGENT_RUNTIME_SECRET (the very var SECURITY.md tells self-hosters to set), APNS_*, FCM_*, SUB2API_*, METRICS_BEARER_TOKEN. Reworded to point at server/src/env.ts as authoritative. Also dropped a "waitlist" env group that has no env vars — it's DB/admin-driven.
• CONTRIBUTING.md — "Two architecture invariants" while CI runs three guards; guard:engine-registry was missing from both the invariants list and the pre-PR command block. Test layout was wrong on both halves (a frontend test exists at tests/message-markdown-links.test.ts; worker tests are not under server/src).
• RELEASE.md — added the missing npm publish path. publish.yml ships the cumora CLI on any push to main touching agent-cli/**, and the Release Manual never mentioned it even though BYOA.md tells users to npx cumora@latest.
• gke.md:37-84 — the primary path pushed to quay.io. CI and prod use Artifact Registry exclusively (build.yml:250, deploy.yml:83). Also corrected cluster/zone to the real cumora-prod-z / us-west2-a and noted zonal clusters take --location, not --region.
• agent-cli/README.md — --server shown as required; it defaults to https://api.cumora.ai.
• workers/email-gate/README.md:13,15 — payload list omitted autoSubmitted and attachments[]; "tempfail" describes a path the code does not have.

Stale comments in the same class

release.yml:7 and build.yml:11 both still described a tag-triggered deploy; publish.yml:6 called the server deploy automatic; migrate-bin.ts:18 showed a ghcr.io image and a migrate-bin.cjs command that don't exist; migrate.ts:2540 still called idx_conversations_members_gin "the hottest read path" after loadInbox moved to conversation_members.

ADR removal

Removed docs/decisions/ and its seven ADRs as requested. Facts recorded only there and still load-bearing were inlined at their point of use before deletion:

• the seven-key ANTHROPIC_* bootstrap allowlist and the api.anthropic.com first-party carve-out (3f85a11) → BYOA.md
• the credential/subprocess boundary → COORDINATION.md

All dangling see ADR NNNN pointers are gone from README.md, BYOA.md, COORDINATION.md, and migrate.ts — including one embedded in a runtime error message operators read during a failed migration. git grep ADR now matches only the PADR padding constants in ObservabilityPage.tsx.

Also gitignores .codex/ next to .claude/.

---

Three code/config defects found while verifying — deliberately NOT fixed here

This PR is docs-only, so these are reported rather than changed. Each looks worth its own PR:

1. server/k8s/cumora-server.gke.yaml:164 points livenessProbe at /api/health, which runs SELECT 1. deploy.yml:228-249 patches it to /api/livez on every rollout, with a comment attributing the 2026-05-27 connection-exhaustion outage to exactly this DB-backed liveness probe. A manual kubectl apply -f of the checked-in manifest re-introduces the outage config. /api/livez already exists (router.ts:658). I documented the required post-apply patch in gke.md as a stopgap.

2. workers/email-gate/src/index.ts:238 permanently rejects on 5xx. The comment says "tempfail so the sender's MTA retries", but message.setReject() is a permanent rejection — one upstream blip loses the mail for good. Cloudflare issues a temporary failure when the handler throws, so the fix is to throw on 5xx and keep setReject for 4xx. I marked it KNOWN GAP in place since changing it flips real delivery behaviour.

3. The cluster-wide FUSE admission ceiling is inert. getClusterFuseUtilization() (orchestrator.ts:512) shells out to kubectl get nodes and fails open to Infinity (:515-519), but both manifests grant only a namespaced Role over pods/pods/log/persistentvolumeclaims — no node read anywhere. Needs a ClusterRole + ClusterRoleBinding for nodes: [get, list]. Until then only AGENT_POD_ADMISSION_MAX bounds admission; documented as such.

---

Verification

npm run lint                    ✅ 502 files
npm run typecheck               ✅
npm run server:typecheck        ✅
npm test                        ✅ 1180/1181
npm run guard:big-brain         ✅
npm run guard:llm-tracked       ✅
npm run guard:engine-registry   ✅
git grep ADR                    ✅ only PADR constants remain
git check-ignore .codex/x       ✅

The single npm test failure is agents-observability-turns.test.ts — "the aggregate counts zero-turn messages — against a real Postgres" — failing ECONNREFUSED on my machine, which has no local Postgres. CI's service containers cover it.

Every numeric claim was re-derived from source rather than trusted: AGENT_POD_ADMISSION_MAX from env.ts:236, the 30-minute interval from autoUpdater.cjs:175, the bundle size from an actual node agent-cli/build.mjs, the seven env keys from CLAUDE_CORE_ENV_KEYS, the publish feed order from package.json.

No behaviour change: Markdown, comments, one error string, one ignore rule.