docs: rewrite AGENTS.md against the current service

[layertwo]

AGENTS.md had drifted ~6 months. I verified every claim in it against the code: 139 were still accurate, 34 were wrong, and 54 load-bearing facts were missing. That ~80% accuracy rate is what made it risky rather than merely dated — it reads as authoritative, and the wrong fifth was concentrated in the parts that changed most recently.

Structural drift the old file missed entirely

• A fifth Lambda (channel_api — WebSocket device pairing), a fifth API Gateway (API Gateway v2 WebSocket at wss://channel.…), and a fifth DynamoDB table (ffsync-channel-<stage>)
• The entire Smithy → pydantic codegen pipeline, undocumented
• Models moved from dataclasses-json — no longer a dependency at all — to generated pydantic v2
• Device endpoints are implemented, not stubs
• react-router v8 (doc said v7), tools/ is uv-managed (requirements.txt is gone), cdk.json sets no profile, monitoring is dashboard-only with no alarms

Added — each mechanism verified, not asserted

• src/shared/generated/ is git-ignored and required. A fresh clone cannot import, test, or type-check until ./scripts/codegen.sh runs. Promoted to a Critical Rule, because the failure (ModuleNotFoundError) looks like a broken repo rather than a missing build step.
• A stale generated/ is invisible to every gate. It imports, type-checks, lints and passes all 958 tests. There is no pre-commit hook, no checksum, no CI step diffing regenerated output, and no committed copy to diff against. CI regenerates from clean checkouts, so it is correct-by-construction and structurally blind to local drift — the one environment that can be wrong is the only one nobody checks.
• TTL is not an access check. DynamoDB deletion lags up to 48 h, so 6 sites re-check expiry in code. Trusting TTL alone leaves expired sessions valid for two days, and no test would catch it.
• The 100% coverage gate fires on subset runs, so pytest -k <pattern> exits 1 even when every selected test passes.
• Decorated handlers must be -> Response[Any]. A bare -> Response passes decoration, mypy and import, then raises PydanticSchemaGenerationError on the first real request.
• except A, B: is valid PEP 758 on 3.14 — do not "fix" it by adding parentheses; Black targets py314 and strips them back off.
• Every push to mainline deploys to production.
• Root npm test deletes frontend/dist/; ...DEFAULT_TABLE_PROPS is spread last so per-table overrides are silently discarded; REST APIs set disableExecuteApiEndpoint so only custom domains work.

Method

Six parallel verifiers each owned specific sections and were required to cite file:line; a separate auditor then fact-checked the rewrite and found 11 errors in it, which are fixed here. Commands were confirmed by execution rather than inference — uv run mypy, uv run pytest, and the Gradle + SMITHY_BUILD_DIR codegen path were all actually run.

Code issues found while verifying — documented, not fixed here

Worth separate follow-ups:

1. DeviceManager.get_devices does an unpaginated full-table scan of the auth table, so device lists truncate past 1 MB. (The scan itself is justified — UserCollectionsIndex is the only GSI in the stack — but the missing pagination is not.)
2. The Profile Lambda's auth-table grant is read-only (grantReadData), so any write added to a Profile route fails only at runtime with AccessDeniedException; stubbed DynamoDB means tests cannot catch it.
3. smithy/models/storage/bso.smithy:27 documents BSO modified as "milliseconds since epoch" where the code uses seconds; the wrong description propagates into the generated model.

Docs-only change — no code, no CI impact.