docs: cite MESHBAY_DESIGN.md and a section instead of the merged notes

The per-feature design notes were merged into docs/MESHBAY_DESIGN.md and
deleted from the tree on 2026-09-11, but ~230 comments across the three
packages still named them — usually written `docs/musicbay.md §3.2`, as
though the file were still in docs/. A reader had to know §16 existed to
resolve any of them. They now name the section directly.

Every mapping comes from §16, the concordance, which already records where
each old section landed: musicbay -> §9.8, mediacenter -> §9.7 for the
Videos app and §6.5 where the subject is derived data, photos -> §9.9,
auth-confirm -> §3.6, refactoring-search -> §9.11, invite-pairing-v1 ->
§3.4, per-node-identity-v1 -> §3.2, captcha -> §7.7, chat-sender-keys ->
§4.5, apps/refactor-groups -> §9.1–§9.4, desktop-client-v1 per section.
Bare citations of the same documents (`draft-v6 §2.11`, `§4.8`, `§3.4`)
are retargeted too: those collide with real section numbers in the design
document, so leaving them would have been worse than the named form.

Four cases the concordance does not cover, each decided rather than guessed:

  Sub-item references into documents that no longer exist — mediacenter's
  `§3.3 row 4`, `§3.4b/c`, `apps.md §3b` — name rows and sub-items §9.7 and
  §9.2 do not reproduce. The module-level citation stays; the sub-item
  pointer is dropped.

  The V-findings keep their labels but lose the dead `§10.1/` prefix.
  §13.8 lists V1–V13 as per-application open items, which is not what the
  labels mean in these comments, so pointing them at §13.8 would have been
  a false citation.

  `apps.md §5`'s virtualization requirement has no counterpart anywhere in
  the design document. The requirement is stated in the comment itself, so
  the citation is dropped rather than aimed at a section that does not say
  it.

  Comments that attributed a *sentence* to an old note — musicbay's "several
  thousand files" example, its "what got measured" note, its measured
  ~11%/~26% cover-art figures, the "original no root, whole shared tree"
  call — state the fact without attribution now. §9.8 does not contain those
  sentences and citing it for them would have been wrong.

CLAUDE.md's "a reference to a document that no longer exists" row now says
the concordance is for git history and out-of-tree material; the code cites
sections directly.

Verified: 2851 passed, 4 skipped. The 12 errors in the run are the Firefox
leg of test_sticky_header.py's browser harness, which is broken at the
browser level on this machine — headless Firefox (snap) dies with
`[GFX1-]: RenderCompositorSWGL failed mapping default framebuffer`, renders
nothing, and the probe exits `{"error": "no measurement"}` after its full
90s wait. Chrome runs the same 12 assertions in 3.2s and passes. Nothing
here can affect it: every changed line in style.css is inside a comment.
Also checked: ast.parse on every changed .py, `node --check` on every
changed .js, the /* */ balance in style.css, and that no changed line
exceeds the width its file already used.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 18 insertions, 16 deletions

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/transport.js b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
index 72c831f..f4979f4 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/transport.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/transport.js
@@ -893,7 +893,7 @@ class MeshBayTransport {
             openErr = e;
             // The passphrase key did not open the bundle. If we hold a recovery
             // key and the node kept a recovery copy, try that — Flow B
-            // (docs/auth-confirm.md §4.5): recovering an identity after a lost
+            // (docs/MESHBAY_DESIGN.md §3.6): recovering an identity after a lost
             // passphrase, before re-wrapping it under the new one.
             if (this._recoveryKey && kpResp.bundle_enc_recovery) {
               try {
@@ -1357,7 +1357,7 @@ class MeshBayTransport {
   }
 
   /**
-   * TMDB metadata for one file (Videos app, docs/mediacenter.md §5.4).
+   * TMDB metadata for one file (Videos app, docs/MESHBAY_DESIGN.md §9.7).
    * Keyed by the entry's own `id` (its content hash) — never a path: a
    * path names the *folder* a file is in (indexer.py's `_virtual_dir`), so
    * two files sharing a folder (any multi-episode season) would resolve to
@@ -1388,7 +1388,7 @@ class MeshBayTransport {
   }
 
   /**
-   * One season's own overview/air_date/poster (docs/mediacenter.md §5.4's
+   * One season's own overview/air_date/poster (docs/MESHBAY_DESIGN.md §9.7's
    * per-season view) — a show's own tmdb_meta is one static field that does
    * not necessarily describe every season alike, found live: a 3-season
    * show whose overview read as season-3-specific for every season.
@@ -1445,7 +1445,7 @@ class MeshBayTransport {
 
   /**
    * Drop one file's cached TMDB match so it re-resolves with the node's
-   * current matcher (§10.1/V13) — the one-click alternative to the full
+   * current matcher (V13) — the one-click alternative to the full
    * search-and-pick flow. Signed for the same reason as overrideTmdbMatch.
    */
   async rematchTmdbMatch(fileId, signFn) {
@@ -1466,7 +1466,7 @@ class MeshBayTransport {
    * setTmdbEnabled below for the per-group on/off switch). Signed like
    * setAppsEnabled/updateRoot — an unsigned change would let any
    * member alter outbound third-party network traffic the operator never
-   * agreed to (docs/mediacenter.md §5.5, §8). `token: ''` explicitly clears
+   * agreed to (docs/MESHBAY_DESIGN.md §9.7, §6.5). `token: ''` explicitly clears
    * a previously-set custom token; omit it (undefined/null), like
    * `language`, to leave whatever is stored unchanged.
    */
@@ -1598,7 +1598,7 @@ class MeshBayTransport {
   }
 
   /**
-   * MusicBrainz metadata for one track (Music app, docs/musicbay.md §4.3)
+   * MusicBrainz metadata for one track (Music app, docs/MESHBAY_DESIGN.md §9.8)
    * — same shape as fetchMediaMeta, minus a season/episode concept:
    * album-level (release), resolved from the track's own artist/album
    * fields already in the index. Keyed by the track's own `id` (content
@@ -1659,7 +1659,7 @@ class MeshBayTransport {
 
   /**
    * Whether MusicBrainz lookups run for this group at all — per-group from
-   * the start (docs/musicbay.md §3.2/§6). Signed like setTmdbEnabled.
+   * the start (docs/MESHBAY_DESIGN.md §9.8). Signed like setTmdbEnabled.
    */
   async setMusicbrainzEnabled(enabled, signFn) {
     const msg = await this._sendAndWait({
@@ -1833,7 +1833,7 @@ class MeshBayTransport {
    * Who is in this group and which device keys they hold — verified here, not
    * taken on the node's word.
    *
-   * Tier 2 of `desktop-client-v1.md` §4.8. The node relays, for each device,
+   * Tier 2 of `docs/MESHBAY_DESIGN.md` §3.3. The node relays, for each device,
    * the already-pinned key that countersigned it and the signature itself; this
    * walks that from each account's first device outwards and keeps only the
    * devices it could actually reach. A device the node asserts but cannot
@@ -1843,7 +1843,7 @@ class MeshBayTransport {
    * The property this buys, stated exactly: once a client has seen an account,
    * a node that later substitutes a key for it is **detected**. It buys nothing
    * at first sight, where there is nothing to compare against — that boundary
-   * is `per-node-identity-v1.md`'s and does not move.
+   * is `docs/MESHBAY_DESIGN.md` §3.2's and does not move.
    */
   async groupRoster() {
     if (this._roster) return this._roster;
@@ -1875,8 +1875,9 @@ class MeshBayTransport {
    *   'changed'   a key this account has not shown before and cannot evidence
    *
    * Only `changed` is worth a person's attention, and it is the one notice
-   * §4.8 budgets for. `first` is not an alarm — every account is new once, and
-   * treating that as a warning is how a warning stops being read.
+   * docs/MESHBAY_DESIGN.md §3.3 budgets for. `first` is not an alarm — every
+   * account is new once, and treating that as a warning is how a warning stops
+   * being read.
    */
   async accountDeviceStatus(userId, devicePk) {
     let roster;
@@ -2658,7 +2659,7 @@ class MeshBayTransport {
   // Identity keys are per node, so a browser and a desktop client are two keys
   // on one account here. A new one is admitted by a key this node already
   // pinned — never by the hub, which holds no user keys and so cannot
-  // countersign anything. See docs/desktop-client-v1.md §4.
+  // countersign anything. See docs/MESHBAY_DESIGN.md §3.3.
 
   /**
    * Ask to be added, and return the code to show the person.
@@ -3286,7 +3287,7 @@ class MeshBayTransport {
       });
     }
     // Same shape: the operator dropped one file's match to have it
-    // re-resolved (§10.1/V13). No tmdbId — the node re-derives it.
+    // re-resolved (V13). No tmdbId — the node re-derives it.
     if (msg.type === 'tmdb_rematch_ack' && this._onTmdbOverride) {
       this._onTmdbOverride({ fileId: msg.file_id || '', tmdbId: '', mediaType: '' });
     }
@@ -4044,7 +4045,7 @@ function pinnedNodeCount() {
 
 // ── Passphrase change: re-wrap every reachable identity bundle ───────────────
 //
-// docs/auth-confirm.md §3.2. The passphrase-derived bundle_key encrypts this
+// docs/MESHBAY_DESIGN.md §3.6. The passphrase-derived bundle_key encrypts this
 // account's per-node identity on every node it has joined. Changing the
 // passphrase changes that key, so each bundle must be read with the old key and
 // written back with the new one — on the node, while both keys are in hand.
@@ -4086,7 +4087,8 @@ function _acWithTimeout(promise, ms, label) {
  * @param {string} o.userId
  * @param {string} [o.oldPassphrase]  omit in Flow B — connect falls back to the recovery copy
  * @param {string} o.newPassphrase
- * @param {string} [o.recoveryKey]   the recovery mnemonic (Flow B, docs/auth-confirm.md §4.5).
+ * @param {string} [o.recoveryKey]   the recovery mnemonic (Flow B,
+ *                                   docs/MESHBAY_DESIGN.md §3.6).
  *                                   When given, the recovery-wrapped copy is read where the
  *                                   passphrase copy cannot be, and a fresh one is written back.
  * @param {(p:{done:number,total:number})=>void} [o.onProgress]
@@ -4100,7 +4102,7 @@ async function rewrapAllNodes(o) {
   let oldKey, newKey;
   if (o.bundleKey) {
     // "Keep the current passphrase key, just add / refresh the recovery copy"
-    // — the Profile backfill (docs/auth-confirm.md §4.3). `o.bundleKey` is the
+    // — the Profile backfill (docs/MESHBAY_DESIGN.md §3.6). `o.bundleKey` is the
     // live {v2,v1} session key, so no passphrase is needed.
     oldKey = newKey = o.bundleKey;
   } else {