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>

4 files changed, 15 insertions, 15 deletions

diff --git a/packaging/caddy/meshbay.org.Caddyfile b/packaging/caddy/meshbay.org.Caddyfile
index c161202..7eaa336 100644
--- a/packaging/caddy/meshbay.org.Caddyfile
+++ b/packaging/caddy/meshbay.org.Caddyfile
@@ -11,10 +11,10 @@
 #   /sw.js         the service worker MUST stay at the root or its scope stops
 #                  covering the pages it intercepts downloads for. A 404 here
 #                  silently breaks streamed downloads on Firefox and Safari.
-#   /a/<hash>/*    the versioned module graph. The old snippet in
-#                  devel-phases-next.md proxied `/style.css` and `/*.js`, which
-#                  matches neither this prefix nor /locales/*.js — it predates
-#                  asset versioning and would 404 the entire bundle.
+#   /a/<hash>/*    the versioned module graph. The old snippet proxied
+#                  `/style.css` and `/*.js`, which matches neither this prefix
+#                  nor /locales/*.js — it predates asset versioning and would
+#                  404 the entire bundle.
 #   /style.css     old bookmarks, still served unversioned by the hub.
 #
 # Deployment: the site is NOT pushed by the hub deploy procedure. Sync it
diff --git a/packaging/conf/hub.toml.example b/packaging/conf/hub.toml.example
index b5f3830..5407436 100644
--- a/packaging/conf/hub.toml.example
+++ b/packaging/conf/hub.toml.example
@@ -51,7 +51,7 @@ access_token_ttl  = 14400      # 4 h
 # reCAPTCHA v2 on registration and password reset, so no mail is ever sent
 # before a human has been seen. Absent, or either key empty, disables it
 # entirely — which is right for development and for a hub nobody can reach.
-# See docs/captcha.md.
+# See docs/MESHBAY_DESIGN.md §7.7.
 site_key   = ""
 secret_key = ""
 
@@ -80,7 +80,7 @@ allowed_hosts = []
 # page or somebody else's Electron application look identical from here. The
 # captcha still has to be solved per token; what is given up is the origin
 # restriction for those clients. Leave it off unless you ship the desktop
-# client. See docs/captcha.md §6.
+# client. See docs/MESHBAY_DESIGN.md §7.7.
 allow_unattributed_host = false
 
 
diff --git a/packaging/systemd/meshbay-node-user.service b/packaging/systemd/meshbay-node-user.service
index feb415b..0c60671 100644
--- a/packaging/systemd/meshbay-node-user.service
+++ b/packaging/systemd/meshbay-node-user.service
@@ -27,11 +27,11 @@ Type=simple
 # the node authenticates to the hub with an Ed25519 signature (NS7).
 # MESHBAY_TMDB_DEFAULT_TOKEN (Videos app, optional) also lives here — never
 # in source. Absent means TMDB lookups are inert until the operator sets one
-# here or configures a custom token in Settings (docs/mediacenter.md §5.5).
+# here or configures a custom token in Settings (docs/MESHBAY_DESIGN.md §9.7).
 # MESHBAY_MUSICBRAINZ_CONTACT_DEFAULT (Music app, optional) lives here too,
 # same reasoning — not a credential (MusicBrainz needs none), but still
 # never a literal value in source: it's a personal contact address sent
-# as-is in every request's User-Agent (docs/musicbay.md §3.2). Absent means
+# as-is in every request's User-Agent (docs/MESHBAY_DESIGN.md §9.8). Absent means
 # MusicBrainz lookups are inert until the operator sets one here or
 # configures a contact in Settings.
 EnvironmentFile=-%h/.config/meshbay/node.env
diff --git a/packaging/systemd/meshbay-node.service b/packaging/systemd/meshbay-node.service
index ad4dc40..aa720b5 100644
--- a/packaging/systemd/meshbay-node.service
+++ b/packaging/systemd/meshbay-node.service
@@ -15,13 +15,13 @@ WorkingDirectory=%h
 # Secrets: MESHBAY_PASSWORD (hub login), MESHBAY_UNLOCK_KEY (keystore),
 # MESHBAY_TMDB_DEFAULT_TOKEN (Videos app — optional, no literal default
 # ships in source; absent means TMDB lookups are inert until the operator
-# sets one here or configures a custom token in Settings, docs/mediacenter.md §5.5).
-# MESHBAY_MUSICBRAINZ_CONTACT_DEFAULT (Music app — optional, no literal
-# default ships in source either; not a credential, but still never a
-# literal value in git — it's a personal contact address sent as-is in
-# every MusicBrainz request's User-Agent, docs/musicbay.md §3.2). Absent
-# means MusicBrainz lookups are inert until the operator sets one here or
-# configures a contact in Settings.
+# sets one here or configures a custom token in Settings,
+# docs/MESHBAY_DESIGN.md §9.7). MESHBAY_MUSICBRAINZ_CONTACT_DEFAULT (Music app
+# — optional, no literal default ships in source either; not a credential, but
+# still never a literal value in git — it's a personal contact address sent
+# as-is in every MusicBrainz request's User-Agent, docs/MESHBAY_DESIGN.md
+# §9.8). Absent means MusicBrainz lookups are inert until the operator sets one
+# here or configures a contact in Settings.
 EnvironmentFile=-%h/.config/meshbay/node.env
 
 ExecStart=/opt/meshbay-common/venv/bin/meshbay-node --config %h/.config/meshbay/node.toml