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.