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, 17 insertions, 15 deletions

diff --git a/packages/meshbay-hub/src/meshbay_hub/static/video-app.js b/packages/meshbay-hub/src/meshbay_hub/static/video-app.js
index d4af4ef..d4ec01a 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/video-app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/video-app.js
@@ -10,16 +10,16 @@ import { usePager, Pager, pageSizeFrom } from './pager.js';
 // ── Videos ───────────────────────────────────────────────────────────────────
 //
 // A poster-grid (TMDB-enriched) or flat (thumbnail-only) browser for a
-// group's video files, per docs/mediacenter.md. Grouping: one card per movie,
-// one card per show — shows are grouped by `display_title` (already
+// group's video files, per docs/MESHBAY_DESIGN.md §9.7. Grouping: one card per
+// movie, one card per show — shows are grouped by `display_title` (already
 // resolved/corroborated at index time, §3.4), not by folder path, since a
 // client-side path convention would have to guess how many roots/subfolders
 // deep a show folder sits, which display_title already settled once.
 //
 // TMDB metadata is fetched lazily, only for a tile once it is actually
-// visible (LazyTile below) — apps.md §5's virtualization requirement for a
-// grid of many tiles. Thumbnails go through the same `file_req`/chunk path
-// as a real file (docs/mediacenter.md §5.3) via MediaThumb, reusing
+// visible (LazyTile below) — the virtualization requirement for a grid of
+// many tiles. Thumbnails go through the same `file_req`/chunk path
+// as a real file (docs/MESHBAY_DESIGN.md §6.5) via MediaThumb, reusing
 // chat-app.js's ChatImage pattern.
 
 const VIEW_MODE_KEY = 'meshbay_video_view_mode';
@@ -121,7 +121,7 @@ function groupVideoEntries(entries, videoDirectories) {
   return { movies, shows };
 }
 
-// ── lazy-mount tile (apps.md §5 virtualization) ─────────────────────────────
+// ── lazy-mount tile (virtualization) ───────────────────────────────────────
 
 const LAZY_TILE_MARGIN = 300;
 
@@ -485,7 +485,7 @@ function OverviewText({ text, reserve }) {
   `;
 }
 
-// ── season picker (docs/mediacenter.md §5.4's fix for a mis-scoped overview) ─
+// ── season picker (docs/MESHBAY_DESIGN.md §9.7's per-season text) ────────────
 //
 // A row of tabs, which this was, scrolls horizontally once a show has more
 // seasons than fit — a scrollbar nobody finds, hiding the seasons that matter
@@ -708,7 +708,7 @@ function VideoDetailModal({
   const [rematching, setRematching] = useState(false);
   const mediaType = show ? 'tv' : 'movie';
 
-  // §10.1/V13: drop this file's cached match on the node and let it
+  // V13: drop this file's cached match on the node and let it
   // re-resolve with the current matcher — the one-click alternative to the
   // full search-and-pick flow above.
   const doRematch = useCallback(async () => {
@@ -779,10 +779,11 @@ function VideoDetailModal({
           `}
           ${/* Both of these act on a TMDB match, and with TMDB off for this
                 group there is none to act on: "Fix match" opens a search the
-                node answers with an empty result list (§5.7's silent
-                degradation), and "Rematch" drops a cached match that was
-                never made. Two buttons that cannot do anything, offered to
-                the one person who already knows why. */''}
+                node answers with an empty result list
+                (docs/MESHBAY_DESIGN.md §9.7's silent degradation), and
+                "Rematch" drops a cached match that was never made. Two
+                buttons that cannot do anything, offered to the one person
+                who already knows why. */''}
           ${isNodeAdmin && tmdbEnabled && html`
             <div class="video-admin-actions">
               <button class="admin-btn video-fix-match" onClick=${() => setSearching(true)}>
@@ -1182,9 +1183,10 @@ function VideoApp({
   `;
 }
 
-// MediaThumb and LazyTile are also used by music-app.js (docs/musicbay.md
-// §7.1): the same "decrypt a thumb_hash via the chunk path into a cached
+// MediaThumb and LazyTile are also used by music-app.js
+// (docs/MESHBAY_DESIGN.md §9.8): the same "decrypt a thumb_hash via the
+// chunk path into a cached
 // blob" and "mount only once actually scrolled near" mechanisms apply to a
 // track's cover art unchanged, so Music imports them here rather than
-// re-implementing (apps.md §4's checklist).
+// re-implementing (docs/MESHBAY_DESIGN.md §9.4's checklist).
 export { VideoApp, MediaThumb, LazyTile, groupVideoEntries, bumpMediaMetaGeneration, bumpThumbGeneration };