docs: point the superseded drafts at the design document

Twenty-three documents that MESHBAY_DESIGN.md absorbs gain a header saying so
and naming the sections their content went to. None is deleted: code comments,
tests and the documents themselves cite their sections and their labels, and
each records reasoning a synthesis compresses.

The header states the precedence, because two documents describing one system
will disagree eventually: where a draft disagrees with MESHBAY_DESIGN.md the
design document is right, and where either disagrees with the code the code is.

Seven status lines were corrected on the way through, all of them claiming less
than the truth. Videos, Music, Photos, partial-read hashing and account recovery
were headed "proposal, not implemented" months after they shipped; the desktop
client said "nothing here is implemented" with stages A through D running; draft
v6 still called itself the current specification.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YVoHVCcfBqud6ZjG4db3y7

23 files changed, 255 insertions, 10 deletions

diff --git a/docs/WINDOWS-PORT.md b/docs/WINDOWS-PORT.md
index e1acc66..efc00e3 100644
--- a/docs/WINDOWS-PORT.md
+++ b/docs/WINDOWS-PORT.md
@@ -1,5 +1,15 @@
 # MeshBay — Windows Port
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the Windows port audit and plan; its design
+> content now lives in §10 (portability), §11.2 (platform), §13.7 (W1–W9).
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Status: **W1–W9 done. Packaging (W4) built with both autostart modes, a
 > post-install mode toggle, and a static dependency audit — clean-machine
 > install still not run.**
diff --git a/docs/apps.md b/docs/apps.md
index 8054802..991af1b 100644
--- a/docs/apps.md
+++ b/docs/apps.md
@@ -1,6 +1,16 @@
 # Group applications — adding one
 
-> Status: **current, as built.** Describes the plug-in architecture that
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the group-application framework; its design
+> content now lives in §9.1–§9.4.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
+> Status: **superseded, and accurate as far as it goes.** Describes the plug-in architecture that
 > replaced the monolithic `static/app.js`, landed 2026-08-23. See
 > `meshbay-draft-v6.md` §2.7 for why this exists and what it changes; this
 > document is the how-to.
diff --git a/docs/auth-confirm.md b/docs/auth-confirm.md
index 96bf7d7..3e8b488 100644
--- a/docs/auth-confirm.md
+++ b/docs/auth-confirm.md
@@ -1,6 +1,18 @@
 # MeshBay — Password change and recovery
 
-> Status: **design, not built.** This is the decision record for two features that
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the passphrase change and recovery; its design
+> content now lives in §3.6.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
+> Status: **built** (the reset endpoints, the recovery key and the node fan-out
+> all shipped; this header said "not built" long after they did). The decision
+> record for two features that
 > look like one and are not: changing a passphrase you still know, and recovering
 > from one you have lost.
 > Follows the house convention: every claim names the adversary it holds against.
diff --git a/docs/captcha.md b/docs/captcha.md
index 4054e9f..7013804 100644
--- a/docs/captcha.md
+++ b/docs/captcha.md
@@ -1,5 +1,15 @@
 # reCAPTCHA on Registration and Password Reset
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the registration and reset captcha; its design
+> content now lives in §7.7.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Goal: verify the user is not a bot **before** sending any email — registration
 > verification code or password reset code. The captcha gate sits between form
 > submission and the email-sending call, so a failed check never triggers an email.
diff --git a/docs/cast-smart-tv.md b/docs/cast-smart-tv.md
index e7a50be..4e716ae 100644
--- a/docs/cast-smart-tv.md
+++ b/docs/cast-smart-tv.md
@@ -1,5 +1,15 @@
 # Phase 3 — Smart TV casting via DLNA/UPnP
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the Smart TV casting plan; its design
+> content now lives in §11.4.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 ## Context
 
 Phase 1 (HTTP relay) and Phase 2 (Chromecast) are shipped. The relay in
diff --git a/docs/chat-sender-keys.md b/docs/chat-sender-keys.md
index b7fb203..656ad42 100644
--- a/docs/chat-sender-keys.md
+++ b/docs/chat-sender-keys.md
@@ -1,5 +1,15 @@
 # Chat encryption — review of Phase 15 and an implementation plan
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the chat encryption design; its design
+> content now lives in §4.5 (encryption and epochs), §3.3 (sender authentication), §13.6.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Status: **Design A decided and BUILT (2026-09-07). MNP 2.0 — a break, and
 > deliberately not an option.** There is no switch: chat is encrypted, and a 1.x
 > peer is refused at the handshake with `version_too_old` rather than connecting
diff --git a/docs/desktop-client-v1.md b/docs/desktop-client-v1.md
index c11837c..6a3ad25 100644
--- a/docs/desktop-client-v1.md
+++ b/docs/desktop-client-v1.md
@@ -1,8 +1,21 @@
 # MeshBay — Desktop Client (design)
 
-> Status: **proposal**. Decided in discussion with the operator on 2026-08-17;
-> nothing here is implemented. Supersedes structural decision 18 in
-> `devel-phases-next.md` (pywebview) and rewrites Phase 13.
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the desktop client design and decision record; its design
+> content now lives in §8.2 (shell), §3.3 (devices), §3.6 (accounts), §6.2 (roots), §6.5 (derived data), §10 (portability), §13.8 and §14 (decisions).
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
+> Status: **largely built.** Decided in discussion with the operator on
+> 2026-08-17; Stages A–D are running, and §10's table is the per-stage record.
+> Stages D5, D6, D9, D11 and D12 remain — see `MESHBAY_DESIGN.md` §15.2. This
+> header said "nothing here is implemented" long after most of it was.
+> Supersedes structural decision 18 in `devel-phases-next.md` (pywebview) and
+> rewrites Phase 13.
 >
 > Read `docs/invite-pairing-v1.md` and `docs/per-node-identity-v1.md` first — this
 > document extends the roster and the pinning model, and it is wrong to read the
diff --git a/docs/devel-phases-next.md b/docs/devel-phases-next.md
index a155652..c00143a 100644
--- a/docs/devel-phases-next.md
+++ b/docs/devel-phases-next.md
@@ -1,5 +1,15 @@
 # MeshBay — Next Implementation Phases
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the implementation roadmap; its design
+> content now lives in §14.1 (structural decisions), §15 (state of the build).
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Base: Phases 1–12 complete (except 10.9 → Phase 18). Web SPA + admin panel + self-service UI + MSE video streaming live on meshbay.org. Node daemon is production-ready (WebRTC, WS, chat, HTTP, index push, swarm all wired).
 > Architecture reference: **meshbay-draft-v6.md** (2026-08-17; v5 remains
 > authoritative for everything v6 does not restate, v4 superseded 2026-08-13).
diff --git a/docs/first-review.md b/docs/first-review.md
index fffac4c..17d5b36 100644
--- a/docs/first-review.md
+++ b/docs/first-review.md
@@ -1,5 +1,15 @@
 # MeshBay — First Architecture & Security Review
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the first security review; its design
+> content now lives in §13.1, and the invariants each finding names throughout.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Date: 2026-08-10
 > Scope: design-level review of the cryptographic architecture, trust model, and
 > security properties as specified in draft v3 (archived in `old-draft.md`) and implemented
diff --git a/docs/indexing-v2.md b/docs/indexing-v2.md
index 6fc7990..a3522de 100644
--- a/docs/indexing-v2.md
+++ b/docs/indexing-v2.md
@@ -1,6 +1,18 @@
 # Indexing v2 — Partial-read hashing for large files
 
-> Status: **plan, not built.** Decision record and implementation checklist.
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the partial-read hashing; its design
+> content now lives in §6.3.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
+> Status: **built.** `hash_version` and partial-read hashing are in the indexer,
+> the protocol and the hash cache. Kept as the decision record and for the
+> migration notes; this header said "not built" long after it shipped.
 
 ---
 
diff --git a/docs/invite-pairing-v1.md b/docs/invite-pairing-v1.md
index ee4d257..8eb378f 100644
--- a/docs/invite-pairing-v1.md
+++ b/docs/invite-pairing-v1.md
@@ -1,5 +1,15 @@
 # MeshBay — Invitation and Pairing (design)
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the admission and pairing design; its design
+> content now lives in §3.4 and §3.5.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Status: **implemented and deployed** (2026-08-14). Written 2026-08-13 as a proposal;
 > §9bis records what shipped, what departed from the plan, and what a browser found
 > that the automated run could not.
diff --git a/docs/mediacenter.md b/docs/mediacenter.md
index 2b25011..a1dbe2f 100644
--- a/docs/mediacenter.md
+++ b/docs/mediacenter.md
@@ -1,6 +1,19 @@
 # MeshBay — Videos application (design)
 
-> Status: **proposal**, prepared 2026-08-23, not implemented. Read `docs/apps.md`
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the Videos application design; its design
+> content now lives in §9.7, with the node-side caching decision in §6.5.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
+> Status: **built** — `video-app.js`, the node-side matching, the metadata and
+> thumbnail caches all shipped, and §10.1–§10.7 record fixes made against a real
+> library since. This header said "not implemented" long after it was.
+> Read `docs/apps.md`
 > first — Videos is a new group application built on the plug-in mechanism
 > described there, and this document assumes that mechanism rather than
 > re-explaining it. Read `docs/desktop-client-v1.md` §6.10 before touching
diff --git a/docs/meshbay-draft-v5.md b/docs/meshbay-draft-v5.md
index de91c80..49aef75 100644
--- a/docs/meshbay-draft-v5.md
+++ b/docs/meshbay-draft-v5.md
@@ -1,5 +1,15 @@
 # MeshBay — Architecture Draft v5
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the architecture draft v5; its design
+> content now lives in §2 (claims), §5 (protocol), §6 (node), §7 (hub), §4 (cryptography), §12 (testing).
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > **SUPERSEDED 2026-08-17 by `docs/meshbay-draft-v6.md`.** v6 restates only what
 > changed; everything below that v6 does not touch is still authoritative — the
 > handshake (§4), node authority (§5), the hub's role (§6), cryptography (§7) and
diff --git a/docs/meshbay-draft-v6.md b/docs/meshbay-draft-v6.md
index 90f9bf9..1105d0e 100644
--- a/docs/meshbay-draft-v6.md
+++ b/docs/meshbay-draft-v6.md
@@ -1,6 +1,17 @@
 # MeshBay — Architecture Draft v6
 
-> Status: **current specification.** Supersedes `meshbay-draft-v5.md`.
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the architecture draft v6; its design
+> content now lives in §6.2 (roots), §3.3 (devices), §8.2 (client), §9 (applications), §7.4–§7.5 (hub policy), §5.1 (transport), §10 (portability).
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
+> Status: **superseded** (it was the current specification until this document
+> was written). Supersedes `meshbay-draft-v5.md` in its turn.
 > **Sections not restated here are unchanged from v5**, which remains the reference for
 > everything v6 does not touch — the handshake (§4), node authority (§5), the hub's role
 > (§6), cryptography (§7) and the testing posture (§10) are all still v5's.
diff --git a/docs/musicbay.md b/docs/musicbay.md
index d9794d2..0bcff38 100644
--- a/docs/musicbay.md
+++ b/docs/musicbay.md
@@ -1,6 +1,18 @@
 # MeshBay — Music application (plan)
 
-> Status: **proposal**, not implemented. Follows the plug-in mechanism in
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the Music application design; its design
+> content now lives in §9.8.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
+> Status: **built** — `music-app.js`, `music-app-settings.js` and the node-side
+> enrichment all shipped; this header said "not implemented" long after they did.
+> Follows the plug-in mechanism in
 > `docs/apps.md` — read that first, and `docs/mediacenter.md` second: Music
 > reuses its node-side pattern (metadata fetched and cached by the node,
 > never by a client) wherever the same shape applies, and this document only
diff --git a/docs/per-node-identity-v1.md b/docs/per-node-identity-v1.md
index 673fec1..da3c6d4 100644
--- a/docs/per-node-identity-v1.md
+++ b/docs/per-node-identity-v1.md
@@ -1,5 +1,15 @@
 # MeshBay — Per-node identity
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the per-node identity design; its design
+> content now lives in §3.2.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Status: **implemented 2026-08-14**, deployed and exercised end to end against a wiped
 > hub and a wiped node. Written first as a proposal; §9 records what shipped.
 > Reduces **C4** from "one crack yields the network" to "one crack yields one node".
diff --git a/docs/photos.md b/docs/photos.md
index c00a7e0..b5612ec 100644
--- a/docs/photos.md
+++ b/docs/photos.md
@@ -1,6 +1,18 @@
 # MeshBay — Photos application (design)
 
-> Status: **proposal**, not implemented. Read `docs/apps.md` first — Photos is
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the Photos application design; its design
+> content now lives in §9.9.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
+> Status: **built** — `photos-app.js`, `photos-app-settings.js` and
+> `enrich_photo.py` all shipped; this header said "not implemented" long after
+> they did. Read `docs/apps.md` first — Photos is
 > a new group application built on the plug-in mechanism described there.
 > Read `docs/mediacenter.md` and `docs/musicbay.md` second: Photos reuses
 > their node-side pattern (thumbnails generated and cached by the node,
diff --git a/docs/refactor-groups.md b/docs/refactor-groups.md
index 147afda..9e0ecf1 100644
--- a/docs/refactor-groups.md
+++ b/docs/refactor-groups.md
@@ -1,5 +1,15 @@
 # Groups Refactor — Per-Root Permissions & App Plugin Architecture
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the roots and app-settings refactor; its design
+> content now lives in §6.2 (RO/RW, eject), §9.3 (enablement and settings).
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Status: **Complete** (2026-09-07). All three phases built, reviewed and
 > tested against a running node.
 >
diff --git a/docs/refactor-node-ui.md b/docs/refactor-node-ui.md
index 7bab5d2..7dbf3da 100644
--- a/docs/refactor-node-ui.md
+++ b/docs/refactor-node-ui.md
@@ -1,5 +1,15 @@
 # Refactor: fold the node's local admin surface into the desktop Node page
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the node admin surface refactor; its design
+> content now lives in §6.7.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Status: **complete** (2026-09-01) — all six phases landed; see §11 for what
 > each did. This stays as the decision record.
 > Scope: the node's *own* administration surface. Group-level settings
diff --git a/docs/refactoring-search.md b/docs/refactoring-search.md
index d39bd36..3172a24 100644
--- a/docs/refactoring-search.md
+++ b/docs/refactoring-search.md
@@ -1,5 +1,15 @@
 # Refactor: one file, one entry — merging duplicate sources in the Search view
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the cross-group source merging; its design
+> content now lives in §9.10.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Status: **complete** (2026-09-02) — all nine phases landed. This stays as
 > the decision record.
 > Branch `feat/search-source-merge`. Videos, Music and Photos are merged,
diff --git a/docs/second-review.md b/docs/second-review.md
index 36caabb..aca65d7 100644
--- a/docs/second-review.md
+++ b/docs/second-review.md
@@ -1,5 +1,15 @@
 # MeshBay — Second Architecture & Security Review
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the second security review; its design
+> content now lives in §13.3, and the invariants each finding names throughout.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Date: 2026-08-13
 > Scope: architecture and security design review of the hub ↔ node ↔ client protocol,
 > as specified in draft v4 and the Phase 1–12 log (both archived in `old-draft.md`), `devel-phases-next.md`,
diff --git a/docs/third-review.md b/docs/third-review.md
index 531f73e..62ab5f6 100644
--- a/docs/third-review.md
+++ b/docs/third-review.md
@@ -1,5 +1,15 @@
 # MeshBay — Third Architecture & Security Review
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the third security review; its design
+> content now lives in §13.4, and the invariants each finding names throughout.
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Date: 2026-09-01
 > Scope: the code as it stands on `main` at `8a6294b`, with emphasis on what
 > changed since `second-review.md` (2026-08-13): the unified handshake
diff --git a/docs/tmp-decisions.md b/docs/tmp-decisions.md
index 70f5171..524f4f4 100644
--- a/docs/tmp-decisions.md
+++ b/docs/tmp-decisions.md
@@ -1,5 +1,15 @@
 # Client architecture — decisions
 
+> **Superseded by `MESHBAY_DESIGN.md`.** This was the client architecture decisions; its design
+> content now lives in §14.2 (D1–D4).
+>
+> It is kept because code comments, tests and other documents cite its
+> sections and its labels, and because it records reasoning a synthesis
+> compresses. **Where it disagrees with `MESHBAY_DESIGN.md`, the design
+> document is right; where either disagrees with the code, the code is.**
+> `MESHBAY_DESIGN.md` §16 maps every section reference here onto its
+> replacement, and §13 defines every label.
+
 > Created 2026-08-13 after the second security review. D1/D2/D3 decided the same day;
 > D4 (hub minimization) deferred. Fold into `meshbay-draft-v5.md`.
 > The analysis below is kept as the rationale behind the decisions, not as open questions.