1 files changed, 19 insertions, 20 deletions
diff --git a/packages/meshbay-hub/src/meshbay_hub/static/music-app.js b/packages/meshbay-hub/src/meshbay_hub/static/music-app.js
index baa3520..e0308cb 100644
--- a/packages/meshbay-hub/src/meshbay_hub/static/music-app.js
+++ b/packages/meshbay-hub/src/meshbay_hub/static/music-app.js
@@ -15,13 +15,13 @@ import * as P from './playlists.js';
 //
 // An album-grid (MusicBrainz-enriched, when a track has no usable embedded
 // cover) or flat (tag/filename-only) browser for a group's audio files, per
-// docs/musicbay.md. Grouping is by `artist`/`album` -- already resolved at
-// index time from embedded tags, falling back to filename/folder parsing
-// (indexer/enrich_audio.py) -- never guessed here.
+// docs/MESHBAY_DESIGN.md §9.8. Grouping is by `artist`/`album` -- already
+// resolved at index time from embedded tags, falling back to filename/folder
+// parsing (indexer/enrich_audio.py) -- never guessed here.
 //
 // Unlike Videos, MusicBrainz is looked up only when a track has no embedded
-// cover art at all (musicbay.md section 2.1's tiered trust: tags first,
-// filename parsing second, MusicBrainz last) -- most of a real, well-ripped
+// cover art at all (docs/MESHBAY_DESIGN.md §9.8's order of trust: tags
+// first, filename parsing second, MusicBrainz last) -- most of a real, well-ripped
 // library already carries good artist/album text and often its own cover, so
 // this avoids a network round trip most tiles never need. Playback never
 // touches this file: clicking a track calls the `onPlayQueue` prop the shell
@@ -52,7 +52,7 @@ function foldKey(s) {
 }
 
 // Same shape as video-app.js's underVideoRoot: an unset root means "show
-// nothing" (docs/musicbay.md's amended §2.1 — the node itself runs no
+// nothing" (docs/MESHBAY_DESIGN.md §9.8 — the node itself runs no
 // tag/cover enrichment for this group before a root is chosen either,
 // daemon.py's _enrich_new_audio_entries), not "the whole shared tree" —
 // falling back to that would just show files nothing has enriched.
@@ -212,17 +212,16 @@ function useMusicMeta(transportRef, fileId, active) {
 }
 
 // A drawn CD standing in for a cover nothing supplied one for -- most tiles
-// in a real, older/well-ripped library land here (musicbay.md's own
-// measurement: ~11% embedded art, ~26% once sibling image files are counted
-// too), so this is the *default* look of the grid, not a rare fallback, and
-// needed to read as a deliberate piece of art rather than a broken image.
-// A flat single-color icon (the first version of this) looked exactly like
-// "missing", not "no cover" -- an actual disc, with the iridescent sheen a
-// real CD's data side has, reads as intentional at a glance. Genuinely
-// unique gradient ids: a `<radialGradient>` id is a plain DOM id, and a grid
-// full of these renders many instances at once -- reusing one literal id
-// would leave every disc after the first pointing at whichever def the
-// browser resolves first.
+// in a real, older/well-ripped library land here (measured: ~11% embedded
+// art, ~26% once sibling image files are counted too), so this is the
+// *default* look of the grid, not a rare fallback, and needed to read as a
+// deliberate piece of art rather than a broken image. A flat single-color icon
+// (the first version of this) looked exactly like "missing", not "no cover" --
+// an actual disc, with the iridescent sheen a real CD's data side has, reads
+// as intentional at a glance. Genuinely unique gradient ids: a
+// `<radialGradient>` id is a plain DOM id, and a grid full of these renders
+// many instances at once -- reusing one literal id would leave every disc
+// after the first pointing at whichever def the browser resolves first.
 let _discIdSeq = 0;
 
 function DiscPlaceholder({ cls }) {
@@ -517,8 +516,8 @@ function FlatArtistFolder({ artist, onPlayQueue, onMenu }) {
       ${open && html`
         <div class="music-flat-children">
           ${/* A real artist folder with no album layer at all is common here
-                -- a pile of loose singles, not one release (musicbay.md
-                section 2.1's "flat per-artist folder" case). Nesting them
+                -- a pile of loose singles, not one release (a flat
+                per-artist folder, docs/MESHBAY_DESIGN.md §9.8). Nesting them
                 one more level behind their own always-empty "Unknown album"
                 row was exactly the friction reported live: an extra,
                 pointless expand before reaching a track that's playable
@@ -748,7 +747,7 @@ function MusicApp({
 }
 
 // foldKey rides along for the Search page's merge unit keys
-// (docs/refactoring-search.md §5.2). An album's *display* strings are the
+// (docs/MESHBAY_DESIGN.md §9.11). An album's *display* strings are the
 // first-seen spelling, and which group is seen first is the order its index
 // happened to arrive in — so keying a unit on them would let the chosen source
 // change between page loads. The folded key is the one grouping actually used,