Work has been starting from a chat message and a plan file, so two
people could pick up the same thing and neither could see the other.
The tracker is where that is visible.
Search before starting, claim before the first edit -- not before the
commit, since the point is that the other person can see the work is
taken while it is being done. If no issue covers it, open one first:
that is what makes the tracker a description of the project rather than
a description of the past.
The conventions were already right and are written down rather than
reinvented -- the Kind/Area/Priority/Platform/Reviewed/Status taxonomy,
its exclusive scopes, #73 as the roadmap, real Gitea dependencies for
hard blockers, and PR #83's body shape.
What #83 also demonstrated is that a Closes list closes nothing
reliably: it listed ten and five of them sat open in main for a
fortnight. So closing is a step you take and verify, not a keyword you
trust.
.planning/ stops being a queue and keeps design documents and measured
history -- NOTES.md, the audits, the completed plans and the arguments
in them. plans/pending/ is gone, because a plan nobody is executing is
an issue; everything unimplemented in it is now #85-#91, and each
completed plan says which issue carries its remainder. autotag.md is
kept as a historical record, marked stale where the scoring overhaul
overtook it.
The commit grammar is unchanged and is load-bearing for a different
reason, so the issue number lives in the branch name and the PR body
rather than the commit subject.
Refs #92
Moves plan 017 to completed with a recap, and lifts the three findings
that generalise into NOTES.md: a preset major that renders empty notes
with everything green, a 403 that looks like branch protection and is a
token scope, and tag-triggered workflows running the tagged commit's
own definitions.
21 conflicts, all from the same cause: three features were developed on
both lines and this branch's copies are the ones adapted to v3's
bindings and to the file-shaped schema. Resolutions:
- `frontend/wailsjs/` stays deleted — v2's generated bindings, replaced
by `frontend/bindings/`.
- remove-from-library, `library-status.ts`, the requested-badge spec and
its component test: took this branch's copies, which differ from
main's only in calling `pruneEmptyEntities`/`CountAudioFiles`,
importing `@go/download/models.js`, and staging a real UUID for the
catalog's `CHECK(length(mbid) = 16)`.
- `GetFilePathsByRecordingMBIDsByLibrary` dropped: it joined
`recordings`, which no longer exists, and `library_id = 0` answers
both scoped and unscoped now. `GetAudioFilesByPaths` was already here.
- The album page, the artist page and the library badge kept this
branch's versions, which supersede main's: ownership asked once from
the files, the partial-completeness ring, and the request action.
- Docs: no migration chain (013) over main's two-file column rule and
its pre-1.0 squashing note, both of which 013 retired. Kept main's
`CreateSmartPlaylist` read-pool example, which is a real second
instance of that bug.
Verified on the merge result, not on either parent: lint clean in all
three build configurations, `make test` green in all three, 776 Vitest
tests, `tsc --noEmit`, bindings-check and skill-check clean.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AfVYUVExXsx1nSWrXN8mAh
Plans 013 and 014, the album page that prompted them, and the smaller
fixes they turned up. Changelog, largest first.
## The local library is shaped like files, not like MusicBrainz
`audio_files` carries its own tags and points at `albums` and
`artists`; `file_genres` is the one real many-to-many. `recordings`,
`release_group_recordings`, `artist_credit`, `artist_credit_artist`,
`recording_genres`, `release_groups` and `release_to_rg` are gone from
the local side, and with them a six-way join in every read, a
`MIN(release_group_id)` subquery in eleven queries and a
first-credited-artist subquery in nine. Measured on a real 25,966-file
library, every many-to-many that model expressed was 1:1 in the data.
- Ownership is a file. `GetFilePathsByRecordingMBIDs`,
`LibraryMBIDIndex.CheckMBIDs`, `collectLibraryEntities` and
`pruneStaleLocalCrossReferences` all join `audio_files`, so the 812
orphaned recordings, 216 release groups and 260 artists that library
carried are now structurally impossible.
- One projection: every track query selects from the `track_metadata`
view, one row type, one mapper. Nine hand-rolled copies had drifted
far enough to report different years on different screens.
- `library_id = 0` means every library, so each list query exists once
instead of scoped and unscoped with a branch at every call site.
- No migration chain. `sql/schemas/` is the one description of the
shape; `sql/migrations/`, `applyMigrations` and `schema_migrations`
are squashed away, along with the drift between them that had sqlc
generating against a stale schema.
- `database.InsertTestTrack` is the one test seeder; twenty test files
had been assembling the old FK chain each in its own order.
## The catalog stores its ids as bytes
`explore_index`'s three 36-char MBID columns and its entity-type text
are 16 raw bytes and a small integer. The table and its six indexes go
780 MB to 405 MB on a real 2,052,200-row catalog, which is why a fresh
install is ~0.6 GB rather than ~1.0 GB.
- `backend/explore/mbid.go` is the only place the encoding is known;
everything above it speaks dashed strings.
- `CHECK(length(mbid) = 16)` makes a stringly write fail at the insert
rather than silently returning no rows, since SQLite does not coerce
between TEXT and BLOB.
- The importer asks the artifact what encoding it carries and converts
on the way in, so the artifact already published keeps working and no
format bump is needed.
- `indexRowColumns`/`scanIndexRow` replace four copies of a 22-column
list, and `TestStoredEncodingRoundTrips` sweeps every read path.
## An album page that says how much of the album is yours
- One question, asked once: is there a file. `filePaths` is filled by a
single batched lookup when the tracklist settles, and the badge, the
Play count, the dimmed rows and every menu item read it — replacing
four claims of decreasing confidence that could show a green tick on
an album whose every action did nothing.
- Play, Play 7 of 12, or no play button at all.
- `total_tracks` on `explore_index` (~2 bytes over 400,677 release
groups) and on `audio_files` from tags that have always carried it:
a complete MBID-matched album now makes no catalog call at all, where
it used to spend the most expensive request the app makes.
- A merged cluster shows the running order the most releases agree on,
and the version list marks the release you own rather than standing a
synthetic entry in for it.
- `AlbumReleasesFailed`: a slow fetch is no longer reported as a failed
one by a 12-second timer.
- Rows not in the library are dimmed in place (with `aria-disabled`)
instead of the owned ones wearing a green tick and a legend.
## Caches and cover art get ceilings
- Only the three tiers of a cover are stored; the full-resolution copy
nothing rendered was 1,134 MB of a 1.4 GB covers directory.
- One artist portrait is downloaded and the rest are remembered as
URLs — 4.1 GB of a 5.3 GB cache was candidates no code path reads.
- `browsedArtBudget` and `httpCacheBudget` bound what an age cannot:
the same install held art for 5,770 artists in a 1,301-artist
library.
- `OrphanedArtistImagesJob` joined a bare MBID onto a sharded
directory, so it deleted the rows that were the only record of the
files it left behind. `explore.ArtistImageDir` is that layout's one
definition now.
## The autotag queue asks whether there is work
`tagging_items` was a row per album folder, not a queue, and no query
read the `tag_status` column that held the answer. The four queue
queries ask the files, which matters most where it is least visible:
`startPrefetch` was scoring every album in a tagged library against
MusicBrainz.
## Phantom playlist tracks resolve in place
An M3U8 imported before its files leaves phantom rows; they now match
by path and fall back to position, keep their place in the playlist
when resolved, and pair best-first so two phantoms cannot claim the
same file.
## Playing a track plays the list it is in
Double-click, and Play on a single row's menu, queue the list as
displayed with `startIndex` on that row — the album page and the track
list used to queue one track and discard the album around it. A
multi-row selection still plays exactly itself.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AfVYUVExXsx1nSWrXN8mAh
RemoveFromLibrary deletes the audio_files rows the way the scan's own
orphan cleanup does and records each path in excluded_paths. The
exclusion is not an enhancement: without it the next scan finds the
file, sees no row and imports it again, so the button undoes itself.
The soft scan compares files on disk against rows in the database, so
surveyAudioFiles and countAudioFiles both take the exclusion set —
otherwise an excluded path makes the two disagree forever and queues a
full scan on every launch. Deleting a row cascades to queue_tracks, so
the removal calls the same CompactQueue hook RemoveLibrary does.
Also lands the requested badge: library-status-indicator is a button
again where it can act, utils/library-status.ts states once what owning
and wanting mean, and the long-declared queued state finally has a
producer.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UDCbcCZQepnpSQYJ6SxxZm
Plan 008 is complete and moves to completed/. The two findings worth
carrying forward are that a new table needs one schema file rather than
two (and a datamap entry, which is a gate nobody remembers), and that
excluding a path has to reach every place that counts what is in the
library — the soft scan's disk-vs-database comparison above all, which
would otherwise have rescanned the whole library on every launch with
nothing failing anywhere.
All six phases of 007 shipped. The plan moves to completed/ with a recap
rather than a rewrite: its seven "where the plan was wrong" lists are
seventy-nine entries and about a third of them are the audit being wrong,
which is the material 008 is planned against.
008 is a11y.md, the only audit with open items and the least verified
material in the repo. A grep pass closes at least five findings the
coverage map still shows open, including a11y.7, which the map assigns to
phase 6 and which phase 1 fixed. The triage in the plan is recorded as
hypotheses for that reason.
CLAUDE.md gains backend/home and the two cross-cutting frontend pieces
a list or detail view now has to know about: explore-link's
always-navigate rule with its double-click grace, and
<catalog-scope-notice> with the catalogPending/catalogLoaded
distinction behind it.
Ships the fresh-start schema cleanup: rebuilt explore catalog index
pipeline (dump import, artifact fetch/build, incremental listen-count
refresh), a new download subsystem (Lidarr/Prowlarr/qBittorrent/SABnzbd/
slskd/yt-dlp providers, staging, reconciliation, wanted list), and the
supporting schema/query/store changes across backend and frontend.
Also includes two smaller follow-ups: bump the central index's
rebuild-after cadence from 90 to 180 days, and remove the Explore
"library only" online/offline toggle entirely (frontend-only, no
backend counterpart) rather than carry unused UI/state.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y2Agd9af5hE7qzti2ackiS
yonlu
logan
