docs: write down what may change on the wire, and gate it

[puritysb]

Why

Three things this week broke, or nearly broke, rules that existed only in reviewers' heads:

• feat(codex): surface persistent goals as read-only tiles #163 appended a new kind of row to sessions_list. It followed every written rule — optional fields only, generated mirrors regenerated, the Swift fold guard mirrored, appstore-feature-matrix.md updated in the same commit — and would still have consumed physical Stream Deck keys and produced untappable rows on iOS 1.0.4, plugin 1.0.2 and every flashed board. Nothing said that a new row kind is not an additive change, and pnpm verify-version calls all 1.0.x mutually compatible regardless.
• fix(plugin): reject expired Claude usage windows #161 added a fourth freshness rule at a fourth layer with a 5-minute grace, next to the 1-hour grace that adjustUsagePercent and formatResetTime already share.
• Closing Security feedback #145 needed a probe from a second host. Nothing recorded that, and the first attempt at it misread a correct result as a live vulnerability.

An external contributor followed every rule we had written and still shipped a fleet-breaking change. That says the written rules are read — and that this one was missing.

What this adds

docs/wire-compatibility.md — the contract for the daemon↔client surface:

• Who is downstream, and which of them we cannot update (App Store 1.0.4 ×2, Elgato 1.0.2, Ulanzi 1.0.3, flashed firmware — only the npm CLI updates on our schedule)
• What the X.Y version rule actually promises, and that a green verify-version is not evidence a wire change is safe
• Change classes: safe-additive vs. breaking-though-it-looks-additive (new row kind, new id namespace, reinterpreting a field, removing a field)
• The retain-on-absent merge rule (s.x = e.x ?? s.x) and its optional-boolean corollary — usageStale demonstrated both failure directions within eight days
• The three freshness axes (window ended / reading age / plan void) and why none may collapse into "hide the gauge"
• The two supported routes for a genuinely breaking change: capability negotiation via client_register, or a new event type
• A review checklist ending on the question that matters: would a 1.0.x client render something wrong, or merely render nothing?

Auth is deliberately not restated. docs/daemon.md's LAN security model already covers it thoroughly and is already cataloged as arch.daemon; duplicating it would create exactly the drift the coverage gate exists to prevent. The contract links to it and carries only the three invariants that constrain message shape.

docs/daemon.md gains the one thing it was missing — how to verify the boundary:

You cannot test this from the daemon's own machine. isLocalConnection() trusts loopback and every address on this host's own interfaces, so curl http://<my-own-LAN-IP>:9120/health returns the full token-bearing payload, and that is correct behaviour.

…plus the second-host procedure via ADB, and the two traps in reading the result: a 101 WebSocket upgrade is not a failure (the daemon closes 4001 before sending state), and several e-ink Android images have no curl.

Verified, not asserted

Claims in the doc were checked against the code before writing them — BridgeEventParser.parse returning nil on unknown type (which is what makes route 2 safe), rawSessionId/sameSession still existing, client_register's actual shape.

bridge/src/__tests__/docs-wire-contract.test.ts keeps the prose bound to the code: the documented public /health body must equal buildPublicHealth(), must carry no credential/inventory/state field, and GET /health must remain the only route an unauthorized peer reaches.

The gate was negative-tested in both drift directions:

mutation	result
doc sample regains pairingToken	2 tests fail
gate opens /setup-status to unauthenticated peers	1 test fails
restored	6/6 pass

docs:check (97 files), design-system:check (28 documents, coverage satisfied) and the security suite (22 tests across 4 files) all pass.

Note

catalog.json is +7/-0 — an earlier revision of this branch round-tripped it through a JSON writer and reformatted all 27 navigationLabels entries. That churn was removed; the entry is inserted textually beside spec.esp32-client, the other contract doc.