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>

29 files changed, 63 insertions, 56 deletions

diff --git a/packages/meshbay-node/tests/conftest.py b/packages/meshbay-node/tests/conftest.py
index 692a118..2ca0c8a 100644
--- a/packages/meshbay-node/tests/conftest.py
+++ b/packages/meshbay-node/tests/conftest.py
@@ -8,7 +8,7 @@ from meshbay_node.roots import RootSet
 
 # ffmpeg / ffprobe run via asyncio.create_subprocess_exec, which needs the
 # ProactorEventLoop — but the repo-root conftest forces the SelectorEventLoop
-# on win32 so aiortc's ICE stack works there (see devel/windows-devel.md §5).
+# on win32 so aiortc's ICE stack works there (see docs/MESHBAY_DESIGN.md §11.2).
 # The two are mutually exclusive on one Windows asyncio loop; until the media
 # path gets a thread-based subprocess runner, these tests can't run on win32.
 needs_subprocess = pytest.mark.skipif(
@@ -39,7 +39,7 @@ def _restore_media_tool_paths():
     _plat._ffmpeg_path, _plat._ffprobe_path = before
 
 
-# Windows-only gaps still to close (see devel/windows-devel.md §5/§6).
+# Windows-only gaps still to close (see docs/MESHBAY_DESIGN.md §11.2).
 win32_todo = pytest.mark.skipif(
     sys.platform == "win32",
     reason="Windows behaviour not implemented yet (W3 / platform specifics)",
diff --git a/packages/meshbay-node/tests/test_audio_root_gates_enrichment.py b/packages/meshbay-node/tests/test_audio_root_gates_enrichment.py
index d353d27..251617c 100644
--- a/packages/meshbay-node/tests/test_audio_root_gates_enrichment.py
+++ b/packages/meshbay-node/tests/test_audio_root_gates_enrichment.py
@@ -1,12 +1,11 @@
 """
-Music-app enrichment (tag/cover extraction, docs/musicbay.md §2.1/§6) only
+Music-app enrichment (tag/cover extraction, docs/MESHBAY_DESIGN.md §9.8) only
 ever runs for a group that has an audio_root configured, and only for files
 under it — see daemon.py's _enrich_new_audio_entries. Same reasoning as
 Videos' video_root gate (test_video_root_gates_enrichment.py), added later:
-musicbay.md's original "no root, whole shared tree" call turned out wrong
-against a real messy library, where everything under every shared folder
-got mixed together with no way to scope Music down to just the actual
-music library.
+the original "no root, whole shared tree" call turned out wrong against a
+real messy library, where everything under every shared folder got mixed
+together with no way to scope Music down to just the actual music library.
 
 Setting or changing the folder (ops.set_app_directory) fires a one-off sweep
 (_enrich_audio_root_now) of whatever it already contains — same shape as
diff --git a/packages/meshbay-node/tests/test_audio_transcode.py b/packages/meshbay-node/tests/test_audio_transcode.py
index c2f7f64..3e6015d 100644
--- a/packages/meshbay-node/tests/test_audio_transcode.py
+++ b/packages/meshbay-node/tests/test_audio_transcode.py
@@ -1,6 +1,6 @@
 """
 Tests for the Music app's one exception to "no node-side transcode pool"
-(docs/musicbay.md §2.2): WMA and Musepack tag/cover fine (enrich_audio.py)
+(docs/MESHBAY_DESIGN.md §9.8): WMA and Musepack tag/cover fine (enrich_audio.py)
 but decode in no mainstream browser's <audio> element at all, so
 `_do_audio_transcode_request` converts to AAC/M4A on request and caches the
 result — served back through the ordinary file_req/chunk path, generalized
diff --git a/packages/meshbay-node/tests/test_bundle_store_recovery.py b/packages/meshbay-node/tests/test_bundle_store_recovery.py
index 10a3400..d649716 100644
--- a/packages/meshbay-node/tests/test_bundle_store_recovery.py
+++ b/packages/meshbay-node/tests/test_bundle_store_recovery.py
@@ -1,5 +1,5 @@
 """
-The recovery-wrapped keypair copy (docs/auth-confirm.md §4.3, MNP 0.14).
+The recovery-wrapped keypair copy (docs/MESHBAY_DESIGN.md §3.6, MNP 0.14).
 
 `bundle_enc_recovery` is a second copy of the identity bundle wrapped under the
 account's recovery key. The store has to add the column to a database that
diff --git a/packages/meshbay-node/tests/test_chat_encryption.py b/packages/meshbay-node/tests/test_chat_encryption.py
index 0401d27..e286306 100644
--- a/packages/meshbay-node/tests/test_chat_encryption.py
+++ b/packages/meshbay-node/tests/test_chat_encryption.py
@@ -1,7 +1,7 @@
 """
 Chat encryption: what the node stores, what it refuses, and what survives.
 
-Design A of `docs/chat-sender-keys.md`. Every test here is written as "this
+Design A of `docs/MESHBAY_DESIGN.md` §4.5. Every test here is written as "this
 does not work" or "this still works after X" — the regressions the plan's
 register names, in the order they would bite.
 
diff --git a/packages/meshbay-node/tests/test_chat_history_binary.py b/packages/meshbay-node/tests/test_chat_history_binary.py
index 18efbf5..e2397a0 100644
--- a/packages/meshbay-node/tests/test_chat_history_binary.py
+++ b/packages/meshbay-node/tests/test_chat_history_binary.py
@@ -10,7 +10,7 @@ possible place to look for a wire-format error.
 
 The fix keeps plaintext exactly where it has always been (a string in
 `payload`, which older clients read) and gives ciphertext its own `ct` field.
-That way this is not a compatibility break either — `docs/chat-sender-keys.md`
+That way this is not a compatibility break either — `docs/MESHBAY_DESIGN.md` §4.5
 R3.
 """
 
diff --git a/packages/meshbay-node/tests/test_chat_multidevice.py b/packages/meshbay-node/tests/test_chat_multidevice.py
index d718b2a..bb61285 100644
--- a/packages/meshbay-node/tests/test_chat_multidevice.py
+++ b/packages/meshbay-node/tests/test_chat_multidevice.py
@@ -11,8 +11,9 @@ what they said.
 Neither shows up as an error anywhere. The first is a message that silently
 reaches nobody after a second device connects and disconnects; the second is a
 phone that never shows what was typed on the laptop. Both are
-`docs/chat-sender-keys.md` F7, and both are the same "keyed by account where it
-should be keyed by connection" mistake as `pin_identity`'s old INSERT OR REPLACE.
+finding F7 (`docs/MESHBAY_DESIGN.md` §13.6), and both are the same "keyed by
+account where it should be keyed by connection" mistake as `pin_identity`'s
+old INSERT OR REPLACE.
 """
 
 from pathlib import Path
diff --git a/packages/meshbay-node/tests/test_cli_dispatch.py b/packages/meshbay-node/tests/test_cli_dispatch.py
index 64f96f1..9bf43d4 100644
--- a/packages/meshbay-node/tests/test_cli_dispatch.py
+++ b/packages/meshbay-node/tests/test_cli_dispatch.py
@@ -168,7 +168,7 @@ def test_the_verb_list_here_matches_the_parser():
         f"VERBS above")
 
     # The server-rendered admin UI (and its `ui` verb) were removed in
-    # docs/refactor-node-ui.md phase 5. The control API stays; the browser
+    # docs/MESHBAY_DESIGN.md §6.7. The control API stays; the browser
     # page does not.
     assert "ui" not in declared, "the `ui` verb came back"
 
diff --git a/packages/meshbay-node/tests/test_device_on_connection.py b/packages/meshbay-node/tests/test_device_on_connection.py
index 3da8a8c..03ed9ca 100644
--- a/packages/meshbay-node/tests/test_device_on_connection.py
+++ b/packages/meshbay-node/tests/test_device_on_connection.py
@@ -12,7 +12,7 @@ oldest live device" and calling it the answer:
   * `_admin_exec_file_delete`, which authorized deletion against **that exact
     key** — so a person could not delete their own file from their other device,
     and the only symptom was "Signature verification failed" on their own upload
-    (`docs/desktop-client-v1.md` §4.8 A).
+    (`docs/MESHBAY_DESIGN.md` §3.3).
 
 `device_hello` closes the first: additive, signed, refused unless the key is a
 live device *of this account in the node's own roster*. The second is closed by
@@ -224,8 +224,9 @@ class _Entry:
 async def test_a_second_device_can_delete_the_first_devices_upload(
         tmp_path, roster):
     """
-    §4.8 A. Alice uploads from her phone and deletes from her desktop. Before
-    the fix this failed with "Signature verification failed" on her own file.
+    docs/MESHBAY_DESIGN.md §3.3. Alice uploads from her phone and deletes
+    from her desktop. Before the fix this failed with "Signature verification
+    failed" on her own file.
     """
     sk_phone, pk_phone, pk_x_phone = _keys()
     sk_desk, pk_desk, pk_x_desk = _keys()
diff --git a/packages/meshbay-node/tests/test_enrich.py b/packages/meshbay-node/tests/test_enrich.py
index 75cf0ee..e059bbe 100644
--- a/packages/meshbay-node/tests/test_enrich.py
+++ b/packages/meshbay-node/tests/test_enrich.py
@@ -134,7 +134,7 @@ def test_synthetic_episode_number_does_not_collide_across_per_season_bonus_folde
 # ── end-to-end against a real (tiny, synthetic) video file ──────────────────
 
 # ffprobe runs via asyncio subprocess, which the win32 selector loop (forced
-# for aiortc, see devel/windows-devel.md §5) cannot spawn.
+# for aiortc, see docs/MESHBAY_DESIGN.md §11.2) cannot spawn.
 pytestmark_ffmpeg = pytest.mark.skipif(
     not _HAVE_FFMPEG or sys.platform == "win32",
     reason="needs ffprobe installed and a ProactorEventLoop",
diff --git a/packages/meshbay-node/tests/test_enrich_photo.py b/packages/meshbay-node/tests/test_enrich_photo.py
index 7684f40..81367eb 100644
--- a/packages/meshbay-node/tests/test_enrich_photo.py
+++ b/packages/meshbay-node/tests/test_enrich_photo.py
@@ -172,7 +172,7 @@ async def test_enricher_corrects_orientation(tmp_path, media_cache):
 
 def test_gps_is_never_read_by_this_module():
     """
-    docs/photos.md §2.4/§11: GPS must never be extracted, cached, or handed
+    docs/MESHBAY_DESIGN.md §9.9: GPS must never be extracted, cached, or handed
     to a caller — a location disclosure the instant it is surfaced to every
     group member. Grep-based, the same discipline test_hub_address_seam.py/
     test_task_lifetime.py already apply elsewhere in this codebase to a
diff --git a/packages/meshbay-node/tests/test_group_roster.py b/packages/meshbay-node/tests/test_group_roster.py
index cb9828c..a41cce2 100644
--- a/packages/meshbay-node/tests/test_group_roster.py
+++ b/packages/meshbay-node/tests/test_group_roster.py
@@ -1,9 +1,9 @@
 """
 Tier 2: a member verifies another member's device for themselves.
 
-`docs/desktop-client-v1.md` §4.8, and `docs/chat-sender-keys.md` §13, which
-recorded why it could not ship with the encryption: **the evidence was not being
-kept.** `_do_device_add` verified the countersignature and stored only
+`docs/MESHBAY_DESIGN.md` §3.3, which records why it could not ship with the
+encryption: **the evidence was not being kept.** `_do_device_add` verified the
+countersignature and stored only
 `added_by_pk` — *which* key approved, never the proof — and the transcript binds
 `nonce_node`, the approving connection's handshake nonce, so even a stored
 signature was unverifiable by anyone who was not on that connection.
diff --git a/packages/meshbay-node/tests/test_media_cache.py b/packages/meshbay-node/tests/test_media_cache.py
index f12a366..dc78d8d 100644
--- a/packages/meshbay-node/tests/test_media_cache.py
+++ b/packages/meshbay-node/tests/test_media_cache.py
@@ -133,7 +133,7 @@ async def test_prune_file_also_clears_the_override_marker(cache):
     assert await cache.clear_tmdb_matches(["gone"]) == 1
 
 
-# ── Music app (docs/musicbay.md §6) — file_mbid/mbid_meta ────────────────────
+# ── Music app (docs/MESHBAY_DESIGN.md §9.8) — file_mbid/mbid_meta ────────────
 
 @pytest.mark.asyncio
 async def test_file_mbid_round_trip(cache):
diff --git a/packages/meshbay-node/tests/test_musicbrainz.py b/packages/meshbay-node/tests/test_musicbrainz.py
index cff7fea..ccf7597 100644
--- a/packages/meshbay-node/tests/test_musicbrainz.py
+++ b/packages/meshbay-node/tests/test_musicbrainz.py
@@ -156,7 +156,8 @@ async def test_no_contact_configured_makes_no_request():
     result, ratio = await client.search_release("Anyone", "Anything")
 
     assert result is None
-    assert calls == [], "an unidentified client must never be sent — see musicbay.md §3.1"
+    assert calls == [], ("an unidentified client must never be sent "
+                        "— see docs/MESHBAY_DESIGN.md §9.8")
     await client.close()
 
 
@@ -227,7 +228,7 @@ async def test_cover_art_found_returns_bytes():
 @pytest.mark.asyncio
 async def test_calls_are_paced_at_least_min_interval_apart():
     """
-    docs/musicbay.md §3.2: the ~1 req/s courtesy limit is this node's own
+    docs/MESHBAY_DESIGN.md §9.8: the ~1 req/s courtesy limit is this node's own
     job, not something the server hands out — verified by timing two calls
     back to back rather than mocking the clock, so a change to the pacing
     implementation that still meets the contract doesn't break this test.
diff --git a/packages/meshbay-node/tests/test_musicbrainz_enabled_policy.py b/packages/meshbay-node/tests/test_musicbrainz_enabled_policy.py
index e86a3f3..76b687e 100644
--- a/packages/meshbay-node/tests/test_musicbrainz_enabled_policy.py
+++ b/packages/meshbay-node/tests/test_musicbrainz_enabled_policy.py
@@ -1,7 +1,8 @@
 """
-Whether MusicBrainz lookups run *at all* for a group — docs/musicbay.md
-§3.2/§6. Per-group from the start (unlike tmdb_enabled, which started
-node-wide and moved per-group later once the lesson was already learned).
+Whether MusicBrainz lookups run *at all* for a group —
+docs/MESHBAY_DESIGN.md §9.8. Per-group from the start (unlike tmdb_enabled,
+which started node-wide and moved per-group later once the lesson was already
+learned).
 Same shape as test_tmdb_enabled_policy.py: a signed operator instruction,
 scoped to self._group_id (not passed explicitly on the wire), stored via
 roster.py's group_settings table under the real group_id.
diff --git a/packages/meshbay-node/tests/test_roster_pairing.py b/packages/meshbay-node/tests/test_roster_pairing.py
index 14285e7..2e8c183 100644
--- a/packages/meshbay-node/tests/test_roster_pairing.py
+++ b/packages/meshbay-node/tests/test_roster_pairing.py
@@ -7,7 +7,7 @@ or a mistake that must not work. The one to keep an eye on is
 sovereignty inert as shipped, and it fails closed, so nothing else in the suite
 notices if it comes back.
 
-See `docs/invite-pairing-v1.md`.
+See `docs/MESHBAY_DESIGN.md` §3.4.
 """
 
 import base64
diff --git a/packages/meshbay-node/tests/test_season_and_search_requests.py b/packages/meshbay-node/tests/test_season_and_search_requests.py
index 44d7da6..9dcc6ce 100644
--- a/packages/meshbay-node/tests/test_season_and_search_requests.py
+++ b/packages/meshbay-node/tests/test_season_and_search_requests.py
@@ -1,6 +1,7 @@
 """
 `_do_season_meta_request` (per-season TMDB overview/poster/air_date, for the
-season-tab view — docs/mediacenter.md §5.4's fix for a 3-season show whose
+season-tab view — docs/MESHBAY_DESIGN.md §9.7's per-season text, found live
+against a 3-season show whose
 overview read as season-3-specific for every season) and
 `_do_tmdb_search_request` (raw TMDB candidates for an operator correcting a
 wrong automatic match). Neither is a signed admin op — see each handler's own
diff --git a/packages/meshbay-node/tests/test_security_regressions.py b/packages/meshbay-node/tests/test_security_regressions.py
index a229153..d6ecb71 100644
--- a/packages/meshbay-node/tests/test_security_regressions.py
+++ b/packages/meshbay-node/tests/test_security_regressions.py
@@ -1,10 +1,10 @@
 """
 Phase 11.5 security regression tests.
 
-Each test here encodes a finding from `second-review.md`. They are negative tests:
-they assert that an attack does NOT work. The pre-11.5 code passed 209 feature
-tests while every one of these attacks succeeded — the suite only ever exercised
-happy paths, never an authorization boundary.
+Each test here encodes a finding from `docs/MESHBAY_DESIGN.md` §13.3. They are
+negative tests: they assert that an attack does NOT work. The pre-11.5 code
+passed 209 feature tests while every one of these attacks succeeded — the suite
+only ever exercised happy paths, never an authorization boundary.
 
 If one of these starts failing, a fix has been reverted. Do not "fix" the test.
 """
@@ -447,7 +447,7 @@ def test_daemon_sets_no_global_chat_store(tmp_path):
 
 def test_no_member_can_hand_the_node_key_material(tmp_path):
     """
-    C5b, strengthened by the invite redesign (docs/invite-pairing-v1.md).
+    C5b, strengthened by the invite redesign (docs/MESHBAY_DESIGN.md §3.4).
 
     This test used to assert that `gek_bundle_store` answered with an admin
     challenge and stored nothing without an operator signature. The message is now
@@ -818,7 +818,7 @@ def test_node_control_api_serves_no_html():
     H2 was stored XSS in the server-rendered admin dashboard: a member-chosen
     filename, or a hub-supplied username, landed in an HTML page on the
     operator's machine unescaped. That dashboard is gone
-    (docs/refactor-node-ui.md phase 5) — the control API is JSON only, so there
+    (docs/MESHBAY_DESIGN.md §6.7) — the control API is JSON only, so there
     is no server-side template to inject into. The Node page that replaced it
     ships in the desktop client and escapes by default (Preact).
 
diff --git a/packages/meshbay-node/tests/test_startup_scan_enrichment.py b/packages/meshbay-node/tests/test_startup_scan_enrichment.py
index d2cbc3e..f43c6e9 100644
--- a/packages/meshbay-node/tests/test_startup_scan_enrichment.py
+++ b/packages/meshbay-node/tests/test_startup_scan_enrichment.py
@@ -12,8 +12,8 @@ is already running (seen by the watchdog), would trigger it. Found live
 against a real library after the first restart with this feature enabled.
 
 Enrichment only runs once a group has a video_root configured (a group
-with none set gets no TMDB/thumbnail work at all, docs/mediacenter.md
-§5.2/§10) — this test's fake roster reports the shared root itself as the
+with none set gets no TMDB/thumbnail work at all, docs/MESHBAY_DESIGN.md
+§6.5) — this test's fake roster reports the shared root itself as the
 configured video_root, so the enrichment-scheduling behaviour under test
 is exercised the same way a real operator's group would be.
 """
diff --git a/packages/meshbay-node/tests/test_stream_video_transcode.py b/packages/meshbay-node/tests/test_stream_video_transcode.py
index 0fd12c6..316fdce 100644
--- a/packages/meshbay-node/tests/test_stream_video_transcode.py
+++ b/packages/meshbay-node/tests/test_stream_video_transcode.py
@@ -19,8 +19,8 @@ None — there is nothing to put in `stream_init` for the client to check. Until
 live against an episode rip in a `.avi` — mpeg4 video, mp3 audio, 720x404 —
 which the reporting machine re-encodes at about six times playback speed. The setting
 that governs it, `transcode_incompatible_video`, was documented from the start
-as covering "HEVC *and other browser-incompatible video codecs*" (draft-v6
-§2.11); only HEVC was ever wired up.
+as covering "HEVC *and other browser-incompatible video codecs*"
+(docs/MESHBAY_DESIGN.md §6.8); only HEVC was ever wired up.
 
 These tests spawn real ffmpeg/ffprobe against small synthetic files (lavfi
 test sources, ~1s), the same style as test_stream_audio_transcode.py.
diff --git a/packages/meshbay-node/tests/test_title_parse.py b/packages/meshbay-node/tests/test_title_parse.py
index bbe9afa..2c4573a 100644
--- a/packages/meshbay-node/tests/test_title_parse.py
+++ b/packages/meshbay-node/tests/test_title_parse.py
@@ -1,6 +1,6 @@
 """
 Tests for indexer/title_parse.py — synthetic filenames only, one per
-docs/mediacenter.md §3.3/§3.4 rule. The real ~1950-file library validation
+docs/MESHBAY_DESIGN.md §9.7 rule. The real ~1950-file library validation
 is a manual acceptance step (§11), not something this repo's corpus holds.
 """
 
@@ -72,7 +72,7 @@ def test_sequel_variants_empty_when_no_trailing_digit():
     assert sequel_variants("Some Movie") == []
 
 
-# ── §10.1/V10: wider sequel-index handling ──────────────────────────────────
+# ── V10: wider sequel-index handling ────────────────────────────────────────
 
 def test_sequel_variants_roman_numeral_offers_the_digit_form():
     v = sequel_variants("Old Frontier III")
@@ -81,7 +81,7 @@ def test_sequel_variants_roman_numeral_offers_the_digit_form():
 
 
 def test_sequel_variants_rewrites_a_part_keyword_index_but_keeps_the_name():
-    # §10.1/V14: with a "Part"/"Episode"/… keyword the bare base is
+    # V14: with a "Part"/"Episode"/… keyword the bare base is
     # withheld — "Some Saga" alone collides with a franchise-origin film.
     v = sequel_variants("Some Saga Part 2")
     assert "Some Saga II" in v
@@ -97,7 +97,7 @@ def test_sequel_variants_reads_a_spelled_out_index():
 
 def test_sequel_variants_saga_shape_does_not_offer_the_bare_franchise():
     # Every "<Saga> Chapter <N>" was matching the franchise's first entry
-    # because the bare "<Saga>" variant hit it at ratio 1.0 (§10.1/V14).
+    # because the bare "<Saga>" variant hit it at ratio 1.0 (V14).
     v = sequel_variants("Some Saga Chapter III")
     assert "Some Saga" not in v
     assert "Some Saga 3" in v
@@ -125,7 +125,7 @@ def test_clean_query_despaces_a_folder_name_without_eating_the_last_word():
     assert naive_title("Some.Show.Name") != "Some Show Name"  # the trap it avoids
 
 
-# ── §10.1/V14: telling a real episode marker from a mangled number ──────────
+# ── V14: telling a real episode marker from a mangled number ────────────────
 
 def test_has_episode_marker_accepts_real_markers():
     for name in ["Some.Show.S01E08.mkv", "some.show.s1.e8.mkv",
@@ -244,7 +244,7 @@ def test_non_season_folder_name_returns_none():
     assert season_from_folder_name("Some Show Name") is None
 
 
-# ── §3.4c: a bare leading episode number, guessit's 3-digit blind spot ───────
+# ── V-findings: a bare leading episode number, guessit's 3-digit blind spot ─
 
 def test_leading_episode_number_reads_the_whole_number():
     assert leading_episode_number("001    Episode's Own Title.mkv") == 1
diff --git a/packages/meshbay-node/tests/test_tmdb.py b/packages/meshbay-node/tests/test_tmdb.py
index ab452ce..299ff2a 100644
--- a/packages/meshbay-node/tests/test_tmdb.py
+++ b/packages/meshbay-node/tests/test_tmdb.py
@@ -40,7 +40,7 @@ async def test_search_movie_returns_top_result_and_confidence():
     await client.close()
 
 
-# ── §10.1/V9: year-exact preference, only when the top hit is weak ──────────
+# ── V9: year-exact preference, only when the top hit is weak ────────────────
 
 @pytest.mark.asyncio
 async def test_year_exact_result_wins_when_the_top_hit_is_low_confidence():
diff --git a/packages/meshbay-node/tests/test_tmdb_config_policy.py b/packages/meshbay-node/tests/test_tmdb_config_policy.py
index c1781e3..cef4fda 100644
--- a/packages/meshbay-node/tests/test_tmdb_config_policy.py
+++ b/packages/meshbay-node/tests/test_tmdb_config_policy.py
@@ -1,6 +1,7 @@
 """
-The operator's custom TMDB API token and query language — docs/mediacenter.md
-§5.5. Same shape as test_apps_enabled_policy.py/test_scan_settings_policy.py:
+The operator's custom TMDB API token and query language —
+docs/MESHBAY_DESIGN.md §9.7. Same shape as
+test_apps_enabled_policy.py/test_scan_settings_policy.py:
 a signed operator instruction, node-wide (group_id="") rather than per-group,
 stored via roster.py's group_settings table.
 
diff --git a/packages/meshbay-node/tests/test_tmdb_enabled_policy.py b/packages/meshbay-node/tests/test_tmdb_enabled_policy.py
index 8e945ad..0a748cd 100644
--- a/packages/meshbay-node/tests/test_tmdb_enabled_policy.py
+++ b/packages/meshbay-node/tests/test_tmdb_enabled_policy.py
@@ -1,5 +1,5 @@
 """
-Whether TMDB lookups run *at all* for a group — docs/mediacenter.md §5.5.
+Whether TMDB lookups run *at all* for a group — docs/MESHBAY_DESIGN.md §9.7.
 Per-group (2026-08-24 — used to be node-wide, folded into tmdb_config): a
 real media-library group and a test/demo group on the same node need not
 share the decision to spend TMDB quota and make outbound requests. Same
diff --git a/packages/meshbay-node/tests/test_tmdb_rematch_policy.py b/packages/meshbay-node/tests/test_tmdb_rematch_policy.py
index ff259c1..198d75b 100644
--- a/packages/meshbay-node/tests/test_tmdb_rematch_policy.py
+++ b/packages/meshbay-node/tests/test_tmdb_rematch_policy.py
@@ -1,5 +1,5 @@
 """
-`tmdb_rematch` (§10.1/V13) — an operator dropping one file's cached TMDB
+`tmdb_rematch` (V13) — an operator dropping one file's cached TMDB
 match so it re-resolves with the current matcher. Signed like
 `tmdb_override` (media_cache is shared node-wide); unlike `clear_file_tmdb`
 it forgets a manual override marker too, since the operator is explicitly
diff --git a/packages/meshbay-node/tests/test_tmdb_search_ladder.py b/packages/meshbay-node/tests/test_tmdb_search_ladder.py
index 9865c77..dc83733 100644
--- a/packages/meshbay-node/tests/test_tmdb_search_ladder.py
+++ b/packages/meshbay-node/tests/test_tmdb_search_ladder.py
@@ -208,7 +208,7 @@ async def test_strong_direct_match_costs_a_single_request():
     assert client.calls == [("A Quiet Film", 2010)]
 
 
-# ── §10.1/V11: a decent primary hit with nothing more specific to try ──────
+# ── V11: a decent primary hit with nothing more specific to try ────────────
 
 async def test_decent_primary_with_no_stronger_candidate_costs_one_call():
     result, _, client = await _run(
@@ -222,7 +222,7 @@ async def test_decent_primary_with_no_stronger_candidate_costs_one_call():
         "is not worth a second request once the primary hit is decent")
 
 
-# ── §10.1/V8: the show branch uses the same scored ladder ─────────────────
+# ── V8: the show branch uses the same scored ladder ───────────────────────
 
 async def test_show_scored_ladder_beats_a_weak_primary_hit():
     result, _, _ = await _run_show(
diff --git a/packages/meshbay-node/tests/test_transfer_settings.py b/packages/meshbay-node/tests/test_transfer_settings.py
index 79502e7..aa24782 100644
--- a/packages/meshbay-node/tests/test_transfer_settings.py
+++ b/packages/meshbay-node/tests/test_transfer_settings.py
@@ -4,7 +4,8 @@ of setting.
 
 The **pools** are the machine's: how many transfers this node runs at once,
 across every group, from `[node]` in node.toml with a roster override — the
-§2.11 pattern, changed from the Node page or the CLI, applied live.
+docs/MESHBAY_DESIGN.md §6.8 pattern, changed from the Node page or the CLI,
+applied live.
 
 The **per-member cap** is a group's: how many one member may run at once here.
 It lives on the node like every other group setting (not the hub, which would
diff --git a/packages/meshbay-node/tests/test_video_root_gates_enrichment.py b/packages/meshbay-node/tests/test_video_root_gates_enrichment.py
index fd0e040..d06b3f4 100644
--- a/packages/meshbay-node/tests/test_video_root_gates_enrichment.py
+++ b/packages/meshbay-node/tests/test_video_root_gates_enrichment.py
@@ -1,5 +1,5 @@
 """
-Videos-app enrichment (ffprobe/thumbnailing/TMDB, mediacenter.md §5.2/§10)
+Videos-app enrichment (ffprobe/thumbnailing/TMDB, docs/MESHBAY_DESIGN.md §6.5)
 only ever runs for a group that has a video_root configured, and only for
 files under it — see daemon.py's _enrich_new_video_entries. Burning TMDB's
 rate limit and the node's CPU on an operator's whole shared index before
diff --git a/packages/meshbay-node/tests/test_webrtc_transport.py b/packages/meshbay-node/tests/test_webrtc_transport.py
index 3010fe9..0839d42 100644
--- a/packages/meshbay-node/tests/test_webrtc_transport.py
+++ b/packages/meshbay-node/tests/test_webrtc_transport.py
@@ -768,7 +768,8 @@ async def test_webrtc_peer_cleanup_on_close(sk_node, sk_hub, gek, shared_dir):
     browser_pc, channel, received = await _setup_peer(
         transport, sk_hub, gek, "peer-cleanup")
 
-    # Keyed per connection, not per account (docs/chat-sender-keys.md F7), so
+    # Keyed per connection, not per account (finding F7,
+    # docs/MESHBAY_DESIGN.md §13.6), so
     # membership is asserted by the session object rather than by user_id —
     # one account may hold several entries here.
     peers = transport._ctx["_peers"]