test(database): the next destructive repair fails a test, not a volume

The fix for the dropped catalog pins one table in one wrong shape, which is the failure that happened. What cost the rebuild was more general: a destructive repair added at `database.NewDB` -- the chokepoint every binary in this project shares -- without asking which binary it runs in. The next one will have a different name and a different reason. So `TestNoCacheTableIsRetiredHere` asserts the outcome instead: put every `datamap` Cache table into a shape the schema has moved past, open the database the way cmd/indexbuild does, and require all of them to still be there. Driving it from `datamap.ByKind` is what makes it cover tables nobody remembered -- flipping the policy back fails on five, including the two artist-credit tables added the same day, where the existing test fails on one. It asserts the rows survive too, because SQLite does an implicit DELETE before a DROP and a repair that recreated the table would look identical. And it accepts an error from `NewDB`, because that is the documented trade: loud is recoverable, gone is not. `scripts/index-cache-snapshot.sh` covers the half no test can reach. The volume holds the only copy of a catalog that costs hours of someone else's bandwidth to re-derive. `VACUUM INTO` rather than `cp`, since a byte copy of a live SQLite file is a corrupt file of plausible size; the resumable staging directory is skipped; and each snapshot is reopened and asked for its catalog row count before anything is rotated out. A corrupt source and an empty catalog were both exercised: each exits non-zero, removes its own output, and leaves the previous snapshots alone. docs/index-cache.md is the restore, and the reason to bother: a restored snapshot resolves to `refresh` and folds in the listens since, which is minutes against the 3-23h this rebuild has been estimating.
2026-08-17 13:54:35 -04:00
275 changed files with 4815 additions and 28315 deletions
@@ -129,35 +129,6 @@ jobs:
          fi
          v="${v#v}"
          # v0.0.0 is semantic-release's version floor, not a shipment —
          # see the bootstrap step in release.yml.  It is skipped cleanly
          # rather than failing the guard below, because a 45-minute red
          # run against a tag that was never meant to ship is noise, and
          # this is the most expensive of the four workflows a tag fires.
          if [ "$v" = "0.0.0" ]; then
            echo "v0.0.0 is the version floor, not a release; nothing to build"
            echo "skip=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          # Nor is a prerelease, and this trigger is `v*`, which matches
          # `v0.4.0-beta.1`.  Two reasons it is worst here.  The APK goes
          # to the *generic* registry, which is readable without
          # credentials so Obtainium can poll a plain URL — a beta would
          # be offered to every device on it.  And the versionCode maths
          # below splits on dots and would read "1" out of "0-beta",
          # producing a code that is wrong rather than a build that
          # fails: Android orders releases by that integer and refuses
          # anything not greater than what is installed.
          case "$v" in
            *-*)
              echo "v$v is a prerelease; not publishing an APK for it"
              echo "skip=true" >> "$GITHUB_OUTPUT"
              exit 0
              ;;
          esac
          echo "skip=false" >> "$GITHUB_OUTPUT"
          # Android orders releases by an integer and refuses anything
          # not greater than what is installed.  1.3.1 -> 10301, which
          # increases as long as minor and patch stay below 100.
@@ -172,24 +143,9 @@ jobs:
          echo "version=$v"     >> "$GITHUB_OUTPUT"
          echo "code=$code"     >> "$GITHUB_OUTPUT"
          echo "tag=v$v"        >> "$GITHUB_OUTPUT"
          echo "building $v (versionCode $code)"
          # Releases restarted at 0.0.1 when they became automatic (plan
          # 017), so versionCode restarted at 1 — *below* the 10300 an
          # installed 1.3.0 build carries.  Android refuses a downgrade
          # outright, and the only remedy is an uninstall, which takes the
          # user's library with it.  Said here because this is the file
          # that computes the number.
          if [ "$code" -lt 10600 ]; then
            echo
            echo "note: versionCode $code is below the 10600 that v1.6.0 shipped."
            echo "      An existing install must be removed before this one will"
            echo "      install, and that removal takes its library with it."
          fi
      - name: Go toolchain
        if: steps.version.outputs.skip == 'false'
        run: |
          set -eu
          if [ ! -x /cache/tool/go/bin/go ] || ! /cache/tool/go/bin/go version | grep -q "$GO_VERSION"; then
@@ -200,7 +156,6 @@ jobs:
          /cache/tool/go/bin/go version
      - name: Node toolchain
        if: steps.version.outputs.skip == 'false'
        run: |
          set -eu
          curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
@@ -212,7 +167,6 @@ jobs:
      # but still spends minutes verifying, so the guards are what make
      # this cheap on every run after the first.
      - name: Android SDK and NDK (cached)
        if: steps.version.outputs.skip == 'false'
        run: |
          set -eu
          mkdir -p "$ANDROID_HOME/cmdline-tools"
@@ -272,7 +226,6 @@ jobs:
      # that are *verbatim* a secret, so a trimmed one could print in
      # clear — or repeating the trimming logic in both.
      - name: Build the signed APK
        if: steps.version.outputs.skip == 'false'
        working-directory: /src
        env:
          KEYSTORE_B64: ${{ secrets.ANDROID_KEYSTORE_B64 }}
@@ -396,7 +349,6 @@ jobs:
      - name: Verify the APK
        id: apk
        if: steps.version.outputs.skip == 'false'
        working-directory: /src
        run: |
          set -eu
@@ -438,7 +390,6 @@ jobs:
      # file, so `latest` is deleted first.  Credentials are the same
      # OWNER/PACKAGE_TOKEN pair arch-package.yml publishes with.
      - name: Publish to the Gitea package registry
        if: steps.version.outputs.skip == 'false'
        working-directory: /src
        env:
          VERSION: ${{ steps.version.outputs.version }}
@@ -474,18 +425,3 @@ jobs:
          echo
          echo "Obtainium URL:"
          echo "  $base/latest/yellowjacket.apk"
      # The generic registry is what Obtainium polls; the release page is
      # what a person looks at.  Same file, already built and already
      # verified by the step above — so this cannot publish something the
      # signature check would have refused.
      - name: Attach the APK to the release
        if: steps.version.outputs.skip == 'false'
        working-directory: /src
        env:
          TAG: ${{ steps.version.outputs.tag }}
          VERSION: ${{ steps.version.outputs.version }}
        run: |
          set -eu
          ./scripts/release-asset.sh "$TAG" bin/yellowjacket.apk \
            "yellowjacket-${VERSION}-android-arm64.apk"
@@ -1,23 +1,8 @@
 name: Build & publish Arch package
 # Keyed on the tag, not on main.  It used to publish on every push,
 # deriving a version from `git describe` — so the registry accumulated a
 # package per merge and none of them corresponded to anything a user
 # could be told to install.  release.yml decides what a release is now,
 # and this builds the tag it cuts.
 on:
  push:
-    tags: ["v*"]
+    branches: [main]
  workflow_dispatch:
    inputs:
      version:
        description: "Version to build (default: the latest v* tag)"
        required: false
 concurrency:
  group: arch-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  arch-package:
@@ -32,7 +17,6 @@ jobs:
      REPO: ${{ github.repository }}
      OWNER: ${{ github.repository_owner }}
      SHA: ${{ github.sha }}
      REF_NAME: ${{ github.ref_name }}
      # Arch registry name (the "$repo" in clients' pacman.conf). Arbitrary label.
      ARCH_REPO: stable
    steps:
@@ -42,9 +26,8 @@ jobs:
          # gtk3 was v2's stack and is now only the `-tags gtk3` escape hatch.
          # These must match the PKGBUILD's depends=() — makepkg installs
          # nothing itself, so a mismatch fails at link time, not at check time.
          # jq is scripts/release-asset.sh's, not the build's.
          pacman -Syu --noconfirm --needed \
-            base-devel git go nodejs pnpm curl sudo jq \
+            base-devel git go nodejs pnpm curl sudo \
            webkitgtk-6.0 gtk4 alsa-lib
      - name: Create unprivileged build user
@@ -53,59 +36,15 @@ jobs:
          install -d -o builder -g builder /build
          echo 'builder ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/builder
      # v0.0.0 is semantic-release's version floor, not a shipment — see
      # the bootstrap step in release.yml.  A clean skip rather than a
      # failure: a red run against a tag that was never meant to ship is
      # noise, and this is one of the four workflows that would otherwise
      # fire on it.
      - name: Resolve the version
        id: version
        run: |
          set -eu
          v="${{ inputs.version }}"
          [ -n "$v" ] || v="$REF_NAME"
          case "$v" in v*) ;; *) v="v$v" ;; esac
          if [ "$v" = "v0.0.0" ]; then
            echo "v0.0.0 is the version floor, not a release; nothing to build"
            echo "skip=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          # A prerelease is not a shipment either, and this trigger is
          # `v*` — which matches `v0.4.0-beta.1`.  Nothing produces one
          # today; the guard is here because the thing that would is
          # semantic-release's `prerelease: true` channel, a one-line
          # change in .releaserc.yml whose blast radius is four public
          # package channels.  Same argument as release.yml's
          # `chore(release):` guard: cheap, against something a future
          # edit turns on somewhere else entirely.
          case "$v" in
            *-*)
              echo "$v is a prerelease; not packaging it for pacman"
              echo "skip=true" >> "$GITHUB_OUTPUT"
              exit 0
              ;;
          esac
          echo "skip=false" >> "$GITHUB_OUTPUT"
          echo "tag=$v"     >> "$GITHUB_OUTPUT"
          echo "building $v"
      - name: Clone repo at the pushed commit
        if: steps.version.outputs.skip == 'false'
        run: |
          # Token auth works for private repos and needs no SSH key in CI.
          sudo -u builder git clone \
            "https://x-access-token:${PACKAGE_TOKEN}@${SERVER_URL#https://}/${REPO}.git" \
            /build/yellowjacket
          # A tag push carries the tag's own commit in $SHA, so this checks
          # out exactly what was tagged.  pkgver() then reads the tag from
          # the clone's own git history.
          sudo -u builder git -C /build/yellowjacket checkout --detach "$SHA"
      - name: Build package with makepkg
        if: steps.version.outputs.skip == 'false'
        run: |
          cd /build/yellowjacket/packaging/arch
          # Point the PKGBUILD at this local clone / exact commit; pkgver() then
@@ -115,7 +54,6 @@ jobs:
            makepkg -f --noconfirm --cleanbuild
      - name: Publish to the Gitea Arch registry
        if: steps.version.outputs.skip == 'false'
        run: |
          cd /build/yellowjacket/packaging/arch
          # makepkg also produces a -debug package (detached symbols); end users
@@ -129,20 +67,3 @@ jobs:
              --upload-file "$pkg" \
              "${SERVER_URL}/api/packages/${OWNER}/arch/${ARCH_REPO}"
          done
      # The pacman registry is for people who have added it to pacman.conf;
      # the release page is for everyone else.  Same file, and it is
      # already built.
      - name: Attach the package to the release
        if: steps.version.outputs.skip == 'false'
        env:
          TAG: ${{ steps.version.outputs.tag }}
        run: |
          set -eu
          cd /build/yellowjacket/packaging/arch
          for pkg in yellowjacket-*.pkg.tar.zst; do
            case "$pkg" in
              yellowjacket-debug-*) continue ;;
            esac
            /build/yellowjacket/scripts/release-asset.sh "$TAG" "$(pwd)/$pkg"
          done
@@ -1,6 +1,6 @@
 name: CI
-# The other five workflows package, publish or release; none of them test
+# The other three workflows package and publish; none of them test
 # anything, so a green tick on this repo used to mean "the Arch package
 # built", which is not the question anyone was asking.  This is the
 # workflow that gates.
@@ -9,23 +9,9 @@ name: CI
 # before being written here, so every step below is a transcription of
 # something observed working rather than something expected to.
 # **A branch push and its PR are the same commit, and testing it twice
 # costs the only runner there is.**  `branches: ['**']` here meant every
 # PR booked four runs — `check` and `e2e` for the branch push, then both
 # again for `refs/pull/N/head` — on a host with capacity 1, where the
 # queue is shared with an index build that can hold it for three hours.
 #
 # `pull_request` covers feature branches, and `main` is kept because a
 # post-merge run is the record of the trunk's health.  Since main now
 # refuses direct pushes, that run happens exactly once per merge.
 #
 # The trade is explicit: a branch pushed with **no** PR open gets no CI.
 # That is consistent with the workflow this repo committed to — every
 # change goes through a PR — and the signal returns the moment one is
 # opened, on the same commit.
 on:
  push:
-    branches: [main]
+    branches: ['**']
  pull_request:
  workflow_dispatch:
@@ -92,7 +78,7 @@ jobs:
      # Cloned by hand rather than with actions/checkout: that is a JS
      # action and needs node inside the job container before any step
      # has had a chance to install it.  Same approach as the other
-      # other workflows in this directory.
+      # three workflows in this directory.
      - name: Clone repo at this commit
        run: |
          set -eu
@@ -1,189 +0,0 @@
 name: Attach the desktop build to the release
 # The Arch package goes to the pacman registry and the APK to the generic
 # one, but a release page with nothing on it to download is a release page
 # nobody can use.  This builds the plain Linux x86_64 binary and attaches
 # it, so "get the latest version" has an answer that needs no package
 # manager at all.
 #
 # **Linux only, and macOS is not an oversight.**  `GOOS=darwin
 # CGO_ENABLED=0` fails at `wails/v3/pkg/mac: build constraints exclude all
 # Go files` — the darwin backend is Objective-C behind cgo, so a .app
 # needs a macOS host, and the runner is a Linux container.  That is
 # exactly why the Homebrew formula builds from source on the user's own
 # Mac, and it stays the macOS channel.
 #
 # Windows *does* cross-compile (GOOS=windows CGO_ENABLED=0 succeeds in a
 # couple of seconds — nothing in the audio, database or webview path needs
 # cgo there), and is deliberately not published: no Windows build of this
 # app has ever been run, and no tier here can exercise one.  Shipping it
 # would be a promise nothing in this repo can keep.  Revisit when someone
 # has actually booted it.
 on:
  push:
    tags: ["v*"]
  workflow_dispatch:
    inputs:
      version:
        description: "Version to build and attach (default: the latest v* tag)"
        required: false
 concurrency:
  group: desktop-assets-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  linux:
    runs-on: ubuntu-latest
    container:
      image: ubuntu:24.04
      volumes:
        - /home/logan/docker/gitea/data/runner/cache/tool:/cache/tool
        - /home/logan/docker/gitea/data/runner/cache/pnpm-store:/cache/pnpm-store
    env:
      PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
      SERVER_URL: ${{ github.server_url }}
      REPO: ${{ github.repository }}
      SHA: ${{ github.sha }}
      REF_NAME: ${{ github.ref_name }}
      DEBIAN_FRONTEND: noninteractive
      GO_VERSION: '1.25.0'
      npm_config_store_dir: /cache/pnpm-store
    steps:
      # The same set ci.yml's check job installs: the app is cgo, and
      # without alsa.pc oto/v3 fails at `pkg-config --cflags -- alsa`
      # before anything is compiled.
      - name: System packages
        run: |
          set -eu
          apt-get update -qq
          apt-get install -y -qq --no-install-recommends \
            ca-certificates curl git jq build-essential pkg-config \
            libwebkitgtk-6.0-dev libgtk-4-dev libasound2-dev
      - name: Clone repo at this commit
        run: |
          set -eu
          git clone --quiet \
            "https://x-access-token:${PACKAGE_TOKEN}@${SERVER_URL#https://}/${REPO}.git" /src
          git -C /src checkout --quiet --detach "$SHA"
          git config --global --add safe.directory /src
          git -C /src log --oneline -1
      - name: Resolve the version
        id: version
        working-directory: /src
        run: |
          set -eu
          v="${{ inputs.version }}"
          if [ -z "$v" ]; then
            case "$REF_NAME" in
              v*) v="$REF_NAME" ;;
              *)  v=$(git describe --tags --abbrev=0 --match 'v[0-9]*') ;;
            esac
          fi
          case "$v" in v*) ;; *) v="v$v" ;; esac
          # v0.0.0 is semantic-release's version floor, not a shipment —
          # see the bootstrap step in release.yml.  Nothing is built for
          # it, and this is a clean skip rather than a failure because a
          # red run against a tag that was never meant to ship is noise.
          if [ "$v" = "v0.0.0" ]; then
            echo "v0.0.0 is the version floor, not a release; nothing to build"
            echo "skip=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          # Nor is a prerelease, and this trigger is `v*`, which matches
          # `v0.4.0-beta.1`.  The mildest of the four — assets attach to
          # the prerelease's own Gitea release and no package manager
          # reads them — but four workflows sharing one trigger should
          # share one answer about what a shipment is.
          case "$v" in
            *-*)
              echo "$v is a prerelease; not attaching desktop assets"
              echo "skip=true" >> "$GITHUB_OUTPUT"
              exit 0
              ;;
          esac
          echo "skip=false"   >> "$GITHUB_OUTPUT"
          echo "tag=$v"       >> "$GITHUB_OUTPUT"
          echo "version=${v#v}" >> "$GITHUB_OUTPUT"
          echo "building $v"
      - name: Go toolchain
        if: steps.version.outputs.skip == 'false'
        run: |
          set -eu
          if [ ! -x /cache/tool/go/bin/go ] || ! /cache/tool/go/bin/go version | grep -q "$GO_VERSION"; then
            mkdir -p /cache/tool && rm -rf /cache/tool/go
            curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz" | tar -C /cache/tool -xz
          fi
          echo "/cache/tool/go/bin" >> "$GITHUB_PATH"
          /cache/tool/go/bin/go version
      - name: Node toolchain
        if: steps.version.outputs.skip == 'false'
        run: |
          set -eu
          curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
          apt-get install -y -qq --no-install-recommends nodejs
          corepack enable
          node --version
      # `make build-prod` is the production task: -trimpath and -w -s are
      # already in it, so only the version stamp is passed, through the
      # LDFLAGS_EXTRA variable this repo added to build/linux/Taskfile.yml.
      # (`wails3 build` has no -ldflags of its own; that was v2.)
      - name: Build
        if: steps.version.outputs.skip == 'false'
        working-directory: /src
        env:
          TAG: ${{ steps.version.outputs.tag }}
        run: |
          set -eu
          export PATH="/src/scripts/toolbin:$PATH"
          commit=$(git rev-parse --short HEAD)
          go generate ./...
          go tool wails3 task build \
            LDFLAGS_EXTRA="-X 'main.version=${TAG}' -X 'main.commit=${commit}'"
          # Described, never run: main.go has no flag parsing, so any
          # invocation here would try to open a window in a container with
          # no display and hang the job rather than printing a version.
          test -x bin/yellowjacket
          ls -la bin/yellowjacket
          file bin/yellowjacket || true
      # The .desktop file and the icon go in the tarball because without
      # them the binary is a window with no menu entry — the Arch package
      # installs both, and this is the same app for people not using it.
      - name: Package the tarball
        if: steps.version.outputs.skip == 'false'
        working-directory: /src
        env:
          VERSION: ${{ steps.version.outputs.version }}
        run: |
          set -eu
          dir="yellowjacket-${VERSION}-linux-amd64"
          mkdir -p "/tmp/$dir"
          cp bin/yellowjacket "/tmp/$dir/"
          cp packaging/arch/yellowjacket.desktop "/tmp/$dir/"
          cp frontend/src/assets/images/icons/music/compact-disc.svg \
             "/tmp/$dir/yellowjacket.svg"
          tar -C /tmp -czf "/tmp/${dir}.tar.gz" "$dir"
          ls -la "/tmp/${dir}.tar.gz"
      - name: Attach it to the release
        if: steps.version.outputs.skip == 'false'
        working-directory: /src
        env:
          TAG: ${{ steps.version.outputs.tag }}
          VERSION: ${{ steps.version.outputs.version }}
        run: |
          set -eu
          ./scripts/release-asset.sh "$TAG" \
            "/tmp/yellowjacket-${VERSION}-linux-amd64.tar.gz"
@@ -14,15 +14,6 @@ on:
  push:
    tags:
      - "v*"
  workflow_dispatch:
    inputs:
      version:
        description: "Version to sync (default: the pushed tag)"
        required: false
 concurrency:
  group: homebrew-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  sync-formula:
@@ -39,37 +30,10 @@ jobs:
        uses: actions/checkout@v4
      - name: Compute version and tarball checksum
        id: version
        run: |
          set -euo pipefail
-          TAG="${{ inputs.version }}"
+          TAG="${GITHUB_REF_NAME}"          # e.g. v1.3.0
-          [ -n "$TAG" ] || TAG="${GITHUB_REF_NAME}"   # e.g. v0.0.1
+          VERSION="${TAG#v}"                 # e.g. 1.3.0
          case "$TAG" in v*) ;; *) TAG="v$TAG" ;; esac
          VERSION="${TAG#v}"                          # e.g. 0.0.1
          # v0.0.0 is semantic-release's version floor, not a shipment —
          # see the bootstrap step in release.yml.  Skipped cleanly rather
          # than failing: this one would otherwise push a formula for a
          # version that does not exist into a *public* tap.
          if [ "$VERSION" = "0.0.0" ]; then
            echo "v0.0.0 is the version floor, not a release; nothing to sync"
            echo "skip=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          # Nor is a prerelease, and this trigger is `v*`, which matches
          # `v0.4.0-beta.1`.  It matters most here of the four: the tap
          # is public, and `brew upgrade` would offer a beta to everyone
          # on it.
          case "$VERSION" in
            *-*)
              echo "$TAG is a prerelease; not syncing it to a public tap"
              echo "skip=true" >> "$GITHUB_OUTPUT"
              exit 0
              ;;
          esac
          echo "skip=false" >> "$GITHUB_OUTPUT"
          TARBALL="${SOURCE_TARBALL_BASE}/${TAG}.tar.gz"
          echo "Fetching ${TARBALL}"
@@ -89,7 +53,6 @@ jobs:
          echo "SHA256=${SHA256}"   >> "$GITHUB_ENV"
      - name: Render the formula with the new version and checksum
        if: steps.version.outputs.skip == 'false'
        run: |
          set -euo pipefail
          src="packaging/homebrew/Formula/yellowjacket.rb"
@@ -103,7 +66,6 @@ jobs:
          cat yellowjacket.rb
      - name: Push to the Homebrew tap repo
        if: steps.version.outputs.skip == 'false'
        run: |
          set -euo pipefail
          git clone "https://x-access-token:${TAP_TOKEN}@github.com/${TAP_REPO}.git" tap
@@ -7,29 +7,31 @@ name: Search index maintenance
 #   import older than 6mo -> rebuild (re-import from the newest dump)
 #   otherwise             -> refresh (fold in new incremental listens)
 #
-# **There is deliberately no `push` trigger, and restoring one is a
+# A refresh is cheap and no-ops when nothing new has been published, so
-# decision rather than a cleanup.** A refresh is individually cheap, so
+# running it on every push to main is safe.
 # running it on every push to main looked free; what it actually does is
 # put an unattended job that mutates the only copy of a ~205 GB catalog
 # on the same trigger as an ordinary code change, on a runner with
 # capacity 1.
 #
-# That is not hypothetical. On 2026-08-17 `fix(database): retire a table
+# ---------------------------------------------------------------------
-# whose shape the schema moved past` landed on main, green — the CI
+# TEMPORARY (2026-08-17): the `push` trigger is off while the catalog
-# database is deliberately in the older encoding, so the stale-shape
+# rebuilds.
 # repair judged its `explore_index` stale and dropped it, and this job
 # fell back to a full import from the dumps. `fix(database): never
 # retire the catalog the index build derives` stops that specific repair
 # and cannot undo it. Every push to main then booked another `budget`
 # (3h) of the one runner while ordinary CI queued behind it.
 #
-# So the rule this file is an instance of: **a job that mutates state
+# `fix(database): retire a table whose shape the schema moved past`
-# which cannot be rebuilt in ten minutes is triggered deliberately, not
+# dropped this job's `explore_index` on its first run -- the CI database
-# by a push.** The weekly cron keeps the catalog current, and
+# is deliberately in the older encoding, so the repair judged it stale --
-# workflow_dispatch resumes or forces a build — indexbuild picks up from
+# and the job fell back to a full ~205 GB import from the dumps.
-# its checkpoint either way, so nothing is lost by not running on every
+# `fix(database): never retire the catalog the index build derives`
-# merge. See docs/index-cache.md for the snapshot and the restore.
+# stops it happening again but cannot undo it.
 #
 # Until that import reports complete, every push to main books another
 # `budget` (3h) of a runner with capacity 1, and ordinary CI queues
 # behind it. The weekly cron and workflow_dispatch still resume the
 # build, which is all it needs: indexbuild picks up from its checkpoint.
 #
 # RESTORE the two `push` lines below once a run reports
 # `complete=true`. Nothing else here changed.
 # ---------------------------------------------------------------------
 on:
  # push:
  #   branches: [main]
  schedule:
    # Weekly update pass. The 6-month rebuild is triggered by the same
    # command when it notices the import has aged out.
@@ -1,228 +0,0 @@
 name: Release
 # The sixth workflow, and the one that decides whether the other three
 # run at all.  It reads the Conventional Commits since the last tag, and
 # if any of them is releasable it writes the changelog, pushes the tag,
 # and creates the Gitea release whose body is that changelog section.
 # The publishing workflows are keyed on `v*`, so the tag push is what
 # starts them.
 #
 # **It is triggered by hand, and there is deliberately no `push`
 # trigger.**  There was one, on `main`, which made the trigger "a PR was
 # merged" and nothing else: eight releases in twenty-two hours
 # (v0.0.1 -> v0.3.1) for one session's work, each fanning out to four
 # publishers on a runner with capacity 1, so ~40 packaging jobs shipped
 # three issues and ordinary PR CI queued behind them.  A version per
 # merged PR is a version per unit of *work*, not per *shipment*, and
 # pacman, Homebrew and Obtainium see every one.
 #
 # Nothing else had to change to batch them: semantic-release already
 # reads every commit since the last tag, so five fixes and two feats
 # become one minor release with all seven in the notes.  Release
 # frequency was only ever how often this file fired.
 #
 # This is the rule `index-artifact.yml` states and is the other instance
 # of: **a job that mutates state which cannot be rebuilt in ten minutes
 # is triggered deliberately, not by a push.**  A release here is a tag,
 # a Gitea release, an Arch package, a Homebrew formula, a signed APK and
 # desktop assets — and an Android version going backwards costs the user
 # their library (docs/android-release.md).
 #
 # A schedule was considered and rejected: a cron batches without anyone
 # having to remember, but it puts the decision back on a timer, which is
 # the thing being removed.
 #
 # **Why the tag is pushed with PACKAGE_TOKEN and not the Actions token.**
 # Gitea, like GitHub, does not start a workflow from a ref pushed by a
 # workflow's own token (go-gitea#33123).  The token is what decides this,
 # not the workflow — so semantic-release is handed a repositoryUrl
 # carrying a *user* PAT, and the resulting push is attributed to a person
 # and triggers the `v*` workflows normally.
 #
 # That limitation is used deliberately in the bootstrap step below, where
 # a tag that must *not* trigger anything is pushed with the Actions token
 # instead.
 on:
  workflow_dispatch:
    inputs:
      dry_run:
        description: "Report what would be released and stop"
        required: false
        default: "false"
 # Cutting a tag is not a thing to cancel halfway: a superseded run must
 # finish, not be killed between `git push --tags` and the release POST.
 concurrency:
  group: release-main
  cancel-in-progress: false
 jobs:
  release:
    runs-on: ubuntu-latest
    container:
      image: ubuntu:24.04
    env:
      SERVER_URL: ${{ github.server_url }}
      OWNER: ${{ github.repository_owner }}
      REPO: ${{ github.repository }}
      PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
      DEBIAN_FRONTEND: noninteractive
    steps:
      - name: System packages
        run: |
          set -eu
          apt-get update -qq
          apt-get install -y -qq --no-install-recommends ca-certificates curl git jq
      - name: Node toolchain
        run: |
          set -eu
          curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
          apt-get install -y -qq --no-install-recommends nodejs
          node --version
      # By hand rather than actions/checkout, like the other five: that is
      # a JS action and needs node inside the container before any step has
      # installed it.  The full history is required — semantic-release
      # reads tags and walks commits, and a shallow clone silently makes
      # every release look like the first one.
      - name: Clone repo at this commit
        run: |
          set -eu
          git clone --quiet \
            "https://x-access-token:${PACKAGE_TOKEN}@${SERVER_URL#https://}/${REPO}.git" /src
          # -B main rather than --detach, which the other five workflows
          # use: semantic-release resolves the release branch and then
          # pushes a commit and a tag to it, and a detached HEAD is a
          # worse starting point for both than a local branch named after
          # the one being released.  Pinned to this commit, not to
          # whatever main points at by the time the container started.
          git -C /src checkout --quiet -B main "${{ github.sha }}"
          git config --global --add safe.directory /src
          git -C /src log --oneline -1
      # Nothing currently pushes a `chore(release):` commit — main is a
      # protected branch, so .releaserc.yml carries no @semantic-release/git
      # and the release page is the changelog.  This guard is kept for the
      # day someone adds that plugin back: without it the commit-back is a
      # push to the branch this workflow runs on, and the loop is a release
      # per release.  Six lines against that is cheap.
      - name: Skip a changelog commit, if one ever exists
        id: guard
        working-directory: /src
        run: |
          set -eu
          subject=$(git log -1 --format='%s')
          case "$subject" in
            "chore(release):"*)
              echo "this is the release commit itself; nothing to do"
              echo "skip=true" >> "$GITHUB_OUTPUT"
              ;;
            *)
              echo "skip=false" >> "$GITHUB_OUTPUT"
              ;;
          esac
      # semantic-release calls the first release of a repo with no tags
      # 1.0.0, and offers no option to say otherwise.  A floor tag is the
      # only way to start at 0.0.1, so this creates one — once, ever.
      #
      # **It is pushed with the Actions token on purpose.**  v0.0.0 is a
      # floor, not a shipment: pushing it with a user PAT would start the
      # Arch, Homebrew and Android workflows for a version that does not
      # exist.  The very limitation the header describes is what makes
      # this inert.
      - name: Seed the version floor
        if: steps.guard.outputs.skip == 'false'
        working-directory: /src
        env:
          ACTIONS_TOKEN: ${{ secrets.GITEA_TOKEN }}
        run: |
          set -eu
          git fetch --quiet --tags origin
          if [ -n "$(git tag --list 'v[0-9]*')" ]; then
            echo "floor already set; newest tag is $(git describe --tags --abbrev=0 --match 'v[0-9]*')"
            exit 0
          fi
          # Prefer the Actions token because a ref it pushes starts no
          # workflow, which is the whole point for a tag that is a floor
          # rather than a shipment.  Falling back to the PAT is safe
          # rather than merely convenient: all four publishing workflows
          # skip v0.0.0 explicitly, so the worst case is four jobs that
          # start and immediately say there is nothing to build.
          token="${ACTIONS_TOKEN:-$PACKAGE_TOKEN}"
          [ -n "$ACTIONS_TOKEN" ] || echo "note: GITEA_TOKEN is unset; using the PAT"
          # **On the parent, not on HEAD.**  The floor marks what has
          # already been released, so tagging the commit being pushed
          # leaves nothing between the floor and HEAD — semantic-release
          # then correctly reports there is nothing to release, which is
          # exactly what the first run of this workflow did.  HEAD^ is the
          # first parent, so on the merge commit this fires for it is main
          # as it was before the merge, and everything the merge brought
          # in is releasable.
          floor=$(git rev-parse "${{ github.sha }}^" 2>/dev/null || true)
          if [ -z "$floor" ]; then
            echo "HEAD has no parent, so no commit can precede the floor" >&2
            exit 1
          fi
          echo "no v* tag exists — seeding v0.0.0 so the first release is 0.0.1"
          git tag v0.0.0 "$floor"
          git push --quiet \
            "https://x-access-token:${token}@${SERVER_URL#https://}/${REPO}.git" \
            refs/tags/v0.0.0
          echo "seeded v0.0.0 at $floor (parent of ${{ github.sha }})"
      # Pinned rather than installed into the repo: this is a Go project
      # and a package.json at its root invites the npm plugin and every
      # tool that looks for one.  conventional-changelog-conventionalcommits
      # is in the list because both the analyzer and the notes generator
      # name that preset and neither depends on it.
      #
      # **That preset is held at 9 and the reason is worth keeping.**  At
      # 10 it is silently incompatible with the writer that
      # release-notes-generator@14 pulls in (^8): every release note comes
      # out as a bare `## 0.0.1 (date)` heading with **no sections and no
      # commits under it**, and nothing errors.  The version would have
      # been right, the tag would have been right, every job would have
      # been green, and the release body would have been empty.  Check the
      # notes, not the exit code, before moving any of these.
      # The point of a manual trigger is deliberateness, and deliberate
      # means being able to look before pulling the lever.  `--dry-run`
      # reports the version and the notes and writes nothing: no tag, no
      # release, no publishers.  `make release-dry` is the same answer
      # locally; this is it from the runner, against the same commit and
      # the same tag history, which is what actually decides.
      - name: Run semantic-release
        if: steps.guard.outputs.skip == 'false'
        working-directory: /src
        env:
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          set -eu
          git config user.name  "yellowjacket-ci"
          git config user.email "yj@yellowjacket.app"
          # Anything but a literal "true" releases for real.  A typo in a
          # dispatch box must not silently turn a shipment into a no-op
          # that reports success — the failure worth avoiding is the one
          # where nothing happens and the run is green.
          dry=""
          if [ "${DRY_RUN:-false}" = "true" ]; then
            echo "DRY RUN — no tag will be pushed and no release created"
            dry="--dry-run"
          fi
          npx --yes \
            -p semantic-release@25 \
            -p @semantic-release/commit-analyzer@13 \
            -p @semantic-release/release-notes-generator@14 \
            -p @semantic-release/changelog@7 \
            -p @semantic-release/exec@7 \
            -p conventional-changelog-conventionalcommits@9 \
            semantic-release $dry \
              --repository-url "https://x-access-token:${PACKAGE_TOKEN}@${SERVER_URL#https://}/${REPO}.git"
@@ -1,107 +0,0 @@
 name: Unclaim
 # A `Closes #N` footer in a commit body closes the issue on merge — and
 # leaves `Status/In Progress` on it, because Gitea's auto-close touches
 # state and nothing else.  So #100 was closed and simultaneously marked
 # as being actively worked on, and `scripts/issue.sh close` (which does
 # drop the label) is exactly the thing the footer exists to avoid
 # calling.
 #
 # **This hooks the close, not the merge.**  Stripping the label in the
 # PR would work and would be a per-PR habit; habits are what the footer
 # removed.  `issues: [closed]` covers every path an issue can close by —
 # the footer on merge, `issue.sh close`, someone clicking Close in the
 # web UI — and asks nothing of anyone at any of them.
 #
 # **Reopening deliberately does not restore it.**  Reopening says the
 # work was not finished, not that somebody is at a keyboard doing it
 # now; the claim gets re-made by whoever picks it up.
 #
 # **This is not instant, and should not be described as it.**  The
 # runner has capacity 1 and is shared with an index build that can hold
 # it for three hours, so a label tweak can queue behind one. Stale for
 # an afternoon beats stale forever, which is what it was.
 #
 # The audit that answers "is this still firing" stays in CLAUDE.md and
 # is one command:
 #
 #   ./scripts/issue.sh list --state closed --label "Status/In Progress"
 #
 # A workflow that silently stops working is the failure mode this whole
 # area has already produced once.
 on:
  issues:
    types: [closed]
 jobs:
  unclaim:
    runs-on: ubuntu-latest
    container:
      image: ubuntu:24.04
    steps:
      - name: Drop the claim label
        # **Inside a container the act runner selects `sh`, not bash**, so
        # `set -o pipefail` fails the job on its second line with "Illegal
        # option" and the step never reaches the API.  `homebrew-formula.yml`
        # carries the same `set -euo pipefail` without trouble because it
        # runs with **no container**, on the host image where bash is the
        # default — so "another workflow does it" is not evidence here.
        shell: bash
        env:
          # The automatic Actions token, as release.yml uses for the
          # floor tag.  It needs no more than write access to this repo.
          TOKEN: ${{ secrets.GITEA_TOKEN }}
          API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
          ISSUE: ${{ github.event.issue.number }}
        run: |
          set -euo pipefail
          # `ca-certificates` is named because `--no-install-recommends`
          # skips it, and `ubuntu:24.04` ships no CA bundle of its own —
          # so curl comes up unable to verify TLS against our own Gitea
          # and fails with "error setting certificate file" (exit 77).
          # Every other containerised workflow here spells it out for the
          # same reason; this one did not, and cost a release cycle.
          apt-get update -qq
          apt-get install -y -qq --no-install-recommends \
            ca-certificates curl jq >/dev/null
          label_id=$(
            curl -sSf -H "Authorization: token $TOKEN" "$API/labels?limit=100" |
              jq -r '.[] | select(.name == "Status/In Progress") | .id'
          )
          # The label not existing is a repo somebody reorganised, not a
          # failure of this run — say so and stop, rather than failing a
          # job on every close from then on.
          if [ -z "$label_id" ]; then
            echo "unclaim: no 'Status/In Progress' label in this repo; nothing to do"
            exit 0
          fi
          # DELETE is idempotent here: an issue that never carried the
          # label answers the same as one that did, which is what makes
          # this safe to run on *every* close rather than only the ones
          # that were claimed.
          # The body is captured, not discarded, so a refusal is
          # diagnosable from this log alone.  Whether the automatic
          # token carries issue-write scope is still unproven, and
          # "DELETE returned 403" without Gitea's own sentence costs
          # another merge to find out which of the two it is.
          body=$(mktemp)
          code=$(
            curl -sS -o "$body" -w '%{http_code}' -X DELETE \
              -H "Authorization: token $TOKEN" \
              "$API/issues/$ISSUE/labels/$label_id"
          )
          case "$code" in
            204) echo "unclaim: #$ISSUE is closed and unclaimed" ;;
            *)
              echo "unclaim: DELETE returned $code for #$ISSUE" >&2
              cat "$body" >&2
              exit 1
              ;;
          esac
@@ -84,12 +84,3 @@ build/android/build/
 build/android/.gradle/
 build/android/gen/
 build/android/overlay.json
 # Written by @semantic-release/changelog purely to carry the release notes
 # into scripts/gitea-release.sh; the release page is the changelog.
 .release-notes.md
 # Agent session log: local scratch, not repo memory (that is CLAUDE.md
 # and .planning/). Written by the scheduled backlog runs.
 .pi/journal.md
 .pi/schedule-prompts.json
@@ -0,0 +1,118 @@
 # Work log
 Temporal memory: what happened and what's next. Structure lives in
 `CLAUDE.md`, operational instructions in `.pi/skills/yellowjacket-dev/`,
 measured discoveries in `.planning/NOTES.md`. Don't duplicate those here.
 ## Current state
 Plan 005 (agent development harness) is **complete — all seven
 phases**. Everything from phase 1 onward is still **uncommitted**: one
 large but coherent working-tree diff, nothing pushed.
 All four tiers verified green from a cold, cleaned state:
 `make ui-test` 313 passed, `make lint` 0 issues × 3 configurations,
 `make test` green × 3 passes, `make e2e` 19 passed. Both CI jobs
 verified green in a bare `ubuntu:24.04` container, including 19/19 on
 WebKit.
 **Committed and pushed** as `5ca6cad` (the harness) + `ccacd67` (a CI
 fix), and **green on the real runner**: job `check` ~4 min, job `e2e`
 ~3 min with 19/19 chromium *and* 19/19 webkit. One commit rather than
 seven because the working tree was the end state, not per-phase
 snapshots — `Makefile`, `CLAUDE.md` and `lefthook.yml` are touched by
 nearly every phase, so a split would have been fabricated history.
 Still unverified, because no run has failed yet: the
 `actions/upload-artifact` step (`continue-on-error`, so it cannot mask
 a real failure) and whether pnpm honours `npm_config_store_dir` for
 store caching. Worth checking the next time a spec legitimately fails.
 - [ ] `gitea_ci`'s `job_logs` returns 404 on Gitea 1.27.1 — the endpoint
      is not exposed. Logs come from the VPS instead: `zstdcat` the file
      under `gitea/actions_log/<owner>/<repo>/<xx>/<task_id>.log.zst`,
      and note `zstdcat` is not in the gitea container, so
      `docker cp` it out first. Job status is `action_run_job.status`
      (1 success, 2 failure, 4 skipped, 5 waiting, 6 running).
      Probably belongs in the `gitea` skill, not here.
 Open items deliberately not fixed: WAV tags are write-only
 (`TestWAVTagsAreNotReadableYet`), `themeStore.loadFromBackend`'s failure
 handler cannot recover, `backend/playlist` has no CRUD suite.
 ## Log
 ### 2026-08-11 — cold skill run, then phase 7 (CI)
 - **Followed the skill cold first**, as the last session asked. It
  works: app up from a wiped `.dev/`, an undocumented flow driven
  (queue panel + shuffle, asserted on `QueueModeChanged`), stopped —
  ~1 minute, no dead ends. One real config bug: `outputDir` in
  `.playwright/cli.config.json` resolves against **cwd**, not the
  config file's directory (only `initScript` does that), so snapshots
  were landing above the repo and a *stale* one from the previous
  session answered `ls -t` instead. That cost a DOM walk to disprove a
  regression that did not exist. Four smaller doc gaps fixed
  (`sandbox-seed` already runs `testdata`; `ui-setup`/`e2e-setup` were
  undocumented prerequisites; `snapshot` prints a path; `dev-stop`
  leaves the browser open), plus `dev-headless.sh`'s own banner, which
  was suggesting the bare `window.go` call its next paragraph warns
  against.
 - **Built both CI jobs as container scripts before writing any YAML**,
  then transcribed the YAML back out and re-ran it to prove the
  transcription. Push-and-see is a bad loop on a self-hosted runner.
 - **It found a real bug immediately**: `make lint` omitted
  `webkit2_41` on all three passes, so it was linting configurations
  nothing builds. Invisible on Arch (which still ships
  `webkit2gtk-4.0.pc`), fatal on Ubuntu 24.04. Tag sets now match
  `make test`.
 - **Both open decisions settled by measurement**: ALSA `null` PCM for
  audio (no daemon; the elapsed clock really advances), dead-address
  stub for the explore artifact (and setting it for the *app* run, not
  just seeding, is worth 8x on suite wall clock). **WebKit is a
  required step** — it had never been run anywhere, so one throwaway
  container run replaced a coin flip with 19/19 at +11 s.
 ### 2026-08-10 — phase 6, pi affordances
 - Added `.pi/skills/yellowjacket-dev/` as a directory rather than a flat
  file: only the description is always in context, so `SKILL.md` stays
  short enough that reading it whole is never a decision, and the deeper
  material sits in `references/{harness,fixtures,ui-tier,schema-change}.md`.
 - Settled the CLAUDE.md-vs-skill split **grammatically, not topically**,
  because a topical split is what rots — every new fact gets two
  plausible homes. Three docs, three tenses: NOTES.md is past
  (measured, dated, append-only), CLAUDE.md is present (what the system
  is), the skill is imperative (what to run). A new paragraph's tense
  decides where it goes.
 - The five gotchas (binding timeouts, first-run wizard, `pkill -f`,
  seeds-by-running, WebKit-is-CI-only) went **inline in SKILL.md**, not
  into a reference: you need them before the failure, not after.
 - Trimmed CLAUDE.md's "Fixtures and the headless harness" section by
  about half — the command sequences and gotchas it was carrying are now
  the skill's, and leaving both would have created exactly the duplicate
  description this repo has a standing rule against.
 - Added `make skill-check` / `scripts/skill-check.sh` + a pre-commit
  hook: every command in `.pi/**/*.md` must be a real `make` target, so
  the Makefile stays the source of truth for invocation and a renamed
  target fails a commit instead of misleading an agent later. Verified
  it fails (it caught its own not-yet-created target) and passes.
 - Added the `/e2e` prompt template: promoting a hand-driven
  `playwright-cli` session into a spec is a transcription with four
  fixed substitutions (refs → testids, sleeps → `waitForEvent`, raw
  `window.go` → `callBinding`, short fixture → `LONG_TRACK`), plus three
  runs — pass, pass again, pass after a DB restore — because the usual
  failure is a spec depending on state the hand-driving left behind.
 - One shell trap: under `set -euo pipefail`, `x="$(make -pqRr | …)"`
  fails the whole assignment, because `make -q` exits non-zero when a
  target is out of date and `pipefail` propagates it.
 ### Earlier
 Phases 1–5 of plan 005: fixture generator and manifest, headless launch
 and seeds, the event bridge + `data-testid` pass + `backend/testctl` +
 `e2e/`, the Vitest component tier + `make bindings-check`, and the
 `events.Emit` wrapper with its in-process service-event tests. Recaps
 and the five "verified end to end" blocks are in
 `.planning/plans/active/005-agent-development-harness.md`; the lessons
 are in `.planning/NOTES.md`.
@@ -1,142 +0,0 @@
 ---
 description: Take on the next actionable backlog issue end to end, and stop
 ---
 Take on exactly one issue from the YellowJacket backlog, end to end, and stop.
 Repo: yonlu/yellowjacket at https://git.ljones.me — API base
 https://git.ljones.me/api/v1/repos/yonlu/yellowjacket, auth with
 `-H "Authorization: token $GITEA_TOKEN"`. Default branch is `main`.
 ## 1. Orient before you pick
 Read, in this order: `CLAUDE.md` (the architecture and the reasons behind
 it), `.pi/journal.md` (what happened last), `.planning/NOTES.md` (what was
 already considered and rejected), and `.planning/plans/active/`. Do not skip
 this because the issue looks small — most of this codebase's traps are
 written down in exactly one of those four places, and the ones that bite are
 the ones you didn't read.
 ## 2. Pick the issue
 List open issues. Choose the single highest-value one that is *actionable
 right now*:
 - Order by `Priority/Critical` → `High` → `Medium` → `Low`. Within a tier,
  prefer `Reviewed/Confirmed`, then `Kind/Bug` over `Kind/Enhancement` over
  `Kind/Feature`.
 - Consult issue #73 (the roadmap) — if it sequences the candidates, that
  ordering wins over the label ordering.
 - **Skip** anything labelled `Status/Blocked`, `Status/In Progress`,
  `Status/Abandoned`, `Reviewed/Won't Fix`, `Reviewed/Duplicate`,
  `Reviewed/Invalid`, or already carrying an open PR.
 - **Skip anything someone else is already on.** The label is not the only
  claim, because a concurrent session may not have applied it — several pi
  sessions run against this repo from separate worktrees under
  `~/.paseo/worktrees/`. Run `git ls-remote --heads origin` and skip any
  issue whose number or slug matches an existing branch (`60-…`,
  `fix/<slug>`). A duplicated fix costs more than a skipped issue.
 - **Skip** anything that cannot be verified without hardware you do not
  have: physical-device Android behaviour (audio output, on-device file
  writes, real gesture input). A browser at 424px is not a phone — see the
  Chrome 113 section of `CLAUDE.md`.
 - **Skip** intermittent-failure issues unless you can reproduce the failure
  on demand within a few minutes. Chasing a 1-in-3 flake is an unbounded
  task and does not belong in a scheduled run.
 - If nothing qualifies, say so, do nothing, and stop. An empty run is a
  correct outcome.
 ## 3. Claim it
 Add `Status/In Progress` to the issue and comment that you are picking it
 up. Then branch:
 ```
 git fetch origin && git checkout -b <type>/<short-slug> origin/main
 ```
 `<type>` matches the issue's `Kind` (`fix/`, `feat/`, `refactor/`, `test/`,
 `docs/`, `ci/`). Branch from `origin/main`, never by checking out `main`
 itself — this repo is worked from several git worktrees at once and `main`
 is checked out in one of them, so `git checkout main` fails outright.
 ## 4. Do the work
 Fix the issue that was reported and nothing else. Match the surrounding
 code's style. Follow the constraints in `CLAUDE.md` rather than reasoning
 from first principles — where it explains why something is shaped the way it
 is, that shape is load-bearing and there is usually a test pinning it.
 **Anything else you discover becomes a new issue, not a bigger diff.** File
 it with the right `Area/`, `Kind/`, `Priority/` labels, describe the
 symptom before the theory, and link it from your PR. Scope creep is the
 failure mode this instruction exists to prevent.
 If the work turns out to be materially larger than the issue implied, stop:
 comment on the issue with what you found and what it would actually take,
 remove `Status/In Progress`, push nothing, and end the run.
 ## 5. Verify — the right tier, not the cheapest one
 Run `make generate` if you touched `.sql` or `.templ`, and `make bindings`
 if you changed a bound Go signature. Then run what the change actually
 demands:
 - Go change → `make lint` and `make test` (both cover all three build
  configurations).
 - Frontend component or store → `make ui-test`.
 - User-visible flow → `make e2e` against `make dev-headless`. **Check the
  port first**: `ss -ltn | grep 34115`. If it is occupied, another worktree
  is already running the app — do not start a second one and do not run
  `make e2e`. Attaching to someone else's build produces a green result
  about code that is not yours, which is worse than no result. Either
  choose an issue that does not need this tier, or stop and say why.
 - Anything cosmetic or layout-related → look at a screenshot. Several bugs
  in this repo's history were invisible to every assertion and obvious in an
  image.
 A tier you skipped is a claim you did not check. If a tier fails for reasons
 unrelated to your change, say so explicitly rather than quietly moving on.
 ## 6. Keep the documentation true
 If you changed structure, behaviour, or a constraint, update `CLAUDE.md` in
 the same commit. That file is this project's memory; a change that leaves it
 describing the old shape is worse than no change. Append a short entry to
 `.pi/journal.md` covering what you did, what you verified, and what you left
 open.
 ## 7. Commit and open the PR
 Conventional Commits, imperative subject, ≤72 chars, scope optional. The
 body explains *why*. Push the branch — never push to `main`, never
 force-push.
 Open the PR:
 ```
 curl -sS -X POST \
  -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  https://git.ljones.me/api/v1/repos/yonlu/yellowjacket/pulls \
  -d '{"head":"<branch>","base":"main","title":"<subject>","body":"<body>"}'
 ```
 The body states: what the issue was, what you changed and why, **which
 verification tiers you ran and their results**, anything you deliberately
 did not do, and `Closes #<n>`.
 Then wait for CI (`ci.yml`, jobs `check` and `e2e`) and report the result on
 the PR. If it fails, read the log — `gitea_ci`'s `job_logs` 404s on this
 Gitea build, so use
 `GET /api/v1/repos/yonlu/yellowjacket/actions/runs/<run>/jobs` for per-step
 status and `GET /api/v1/repos/yonlu/yellowjacket/actions/jobs/<id>/logs` for
 the log — and fix it. Two consecutive failed CI runs on the same cause: stop,
 comment what you know on the PR, and leave it for a human.
 **Do not merge.** Comment on the issue linking the PR, leave
 `Status/In Progress` on, and end the run.
 ## Finally
 Report in three lines: which issue you took, what state it is in
 (PR open / CI green / stopped and why), and any issues you filed.
@@ -195,12 +195,6 @@ Two rules about climbing:
 - **Do not write an e2e spec first.** Drive the flow by hand, then
  promote it with `/e2e`. Specs written blind assert on selectors that
  do not exist.
 - **Not every view has a nav item.** Since #25 the destinations are
  configurable, Autotag is hidden by default and Downloads is absent
  until a download client exists — so `getByTestId('nav-<view>')` waits
  30 s for a locator that will never resolve. `navigateTo(page, view)`
  (`e2e/support/fixtures.ts`) dispatches the app's own `navigate` event.
  Click the nav item when the *nav* is what the spec is about.
 Before a commit, the gate is `make lint`, `make test`, `make ui-test`,
 `make bindings-check`, `make css-check` and — from `frontend/` —
@@ -194,13 +194,9 @@ like the app's fault and none is:
 |---|---|---|
 | x86_64 | modernc's raw `lstat` vs seccomp | SIGSYS, syscall 6 |
 | arm64, translated | Go reads `ID_AA64ISAR0_EL1` | SIGILL |
-| arm64, real device | **runs** (2026-08-20) | — |
+| arm64, real device | — | unverified, still |
-**A physical arm64 device remains the only verification path**, and it
+**A physical arm64 device remains the only verification path.**
 has now been walked: a Light Phone III (TLP301, Android 14 / SDK 34,
 arm64-v8a, WebView Chrome 113 at 424x439). The app builds, installs,
 launches and stays up; `make android-smoke SECONDS=60` passes on it.
 What that run *found* is the lifecycle fault below.
 ### What was fixed to get here
@@ -214,11 +210,6 @@ no-op. `backend/system` gained no import of the Wails application
 package, which matters for the same reason `backend/events` is split by
 the `indexbuild` tag.
 **And `main()` is now latched to one run per process** (#52). That is
 the second `os.Exit(1)` in this file's history and it had the same
 signature as the first, which is the argument for #160: both were named
 exactly by an `slog` line that went to `/dev/null`.
 ### What is still not done
 The shell is still a desktop shell, and the x86_64 half of the APK is
@@ -258,25 +249,10 @@ one.
 `build/android/Taskfile.yml` ships more than the Makefile wraps, and
 they are the right thing to reach for when you want something one-off:
 > **These four were unsafe until #159 and are now the way in.** All of
 > them began with `adb uninstall {{.APP_ID}}`, where `APP_ID` defaulted
 > to `app.yellowjacket` — the **release** id — while `run` and
 > `run:device` build the **debug** variant, whose id is
 > `app.yellowjacket.dev`. So they uninstalled the user's app, taking
 > the library with it, installed a different package, and then failed
 > to launch the one they had removed.
 >
 > They share `scripts/android-deploy.sh` now, which **never**
 > uninstalls (`install -r`, and a changed signing certificate is
 > reported with the command rather than acted on), reads the package id
 > back out of the built APK, and refuses a target that is not the kind
 > the task names. There is nothing left to avoid; the manual sequence
 > below is kept because it is still the smallest thing that works.
 ```
 wails3 task android:run              # debug build + emulator install + launch
-wails3 task android:run:device       # debug build + install + launch on a phone
+wails3 task android:run:device       # same, first connected physical device
-wails3 task android:deploy-device    # release build, same
+wails3 task android:deploy-device    # production APK to a device
 wails3 task android:bundle:fat       # AAB, for a Play Store upload
 wails3 task android:studio           # open build/android/ in Android Studio
 wails3 task android:device:list
@@ -284,16 +260,6 @@ wails3 task android:logs:all
 wails3 task android:clean
 ```
 **`run` and `deploy-emulator` mean the emulator, and now say so to
 adb.** They used a bare `adb install`, which with exactly one device
 attached picks that device whatever it is — so with a phone plugged in
 and no emulator running, the task whose summary reads "in the Android
 Emulator" installed on the phone. They pass `--target emulator` and
 refuse with `make android-emulator` as the remedy.
 **`DEVICE_ID=<serial>` still names a device, and several attached
 devices is now an error rather than a silent pick of the first.**
 Two are deliberately **not** wrapped. `android:logs` greps logcat for
 `(Wails|yellowjacket)`, which catches the `WailsBridge` tag but misses
 the app's own process tag (`app.yellowjacket` — lowercase, so `Wails`
@@ -303,51 +269,16 @@ instead. And `ensure-emulator` boots whatever `-list-avds | tail -1`
 returns, with no pidfile and no boot wait, so it cannot be stopped or
 sequenced.
-## The identity is read back from the APK
+## The identity is declared twice
 It used to be **declared twice**, and that is what #159 was.
 `applicationId` in `build/android/app/build.gradle` is what Gradle
-installs; `APP_ID` in `build/android/Taskfile.yml` was what every
+installs. `APP_ID` in `build/android/Taskfile.yml` is what every
-adb-driven task uninstalled, launched and filtered, and nothing
+adb-driven task uninstalls, launches and filters. **Nothing enforces
-enforced that they agree. They did not: the debug buildType carries
+that they agree**, and `ANDROID.md`'s advice to set `APP_ID` in
-`applicationIdSuffix ".dev"`, so every task that assembles a debug APK
+`build/config.yml` does not work in beta.8 — `wails3 task` never reads
-addressed the release id. This file flagged the hazard for five phases
+that file (verified with `--dry`), and even when set it feeds only the
-and it cashed out twice — once as a wrong `am start`, once as an
+adb commands, never Gradle. Change both or the official `run`/`deploy`
-uninstall of the user's library.
+tasks address a package that is not installed.
 **`scripts/android-pkgid.sh` is the one answer now.** It prints the
 package id an APK declares (`aapt2 dump packagename`, falling back to
 `aapt dump badging`), and the deploy path installs and launches *that*.
 The APK is the authority because the task that installs it has just
 built it: whatever Gradle resolved the applicationId to, suffixes and
 flavours included, is in the file, and no default can disagree with it.
 An APK it cannot read is a hard failure, never a fallback to a written
 down default — guessing is the bug.
 **`APP_ID` survives as an assertion, not a setting**, and has no
 default. `wails3 task android:run APP_ID=app.yellowjacket` says "this
 build had better declare that id" and is refused, naming both, *before*
 anything is installed or a device is even chosen. It could never have
 been a setting: `ANDROID.md`'s advice to put it in `build/config.yml`
 does not work in beta.8 — `wails3 task` never reads that file (verified
 with `--dry`) — and even when set it fed only the adb commands, never
 Gradle.
 `scripts/android-emulator.sh` derives `PKG` the same way, from
 `bin/yellowjacket.apk` when one is built, so `make android-install`,
 `android-launch`, `android-logs` and `android-smoke` follow whichever
 variant is actually in `bin/`. `YJ_ANDROID_PKG` still overrides, and
 the old literal survives only for a tree with no APK built yet.
 **The uninstall is gone and is not coming back.** It existed to make
 the bare `install` on the next line work at all — without `-r` Android
 refuses an install over an existing package — so `install -r` removes
 the *reason* for it rather than merely removing it. What is left is the
 one case an uninstall really is the remedy, a changed signing
 certificate, and that is exactly the case where performing it silently
 costs the user their library. So it is named and not done, which is the
 answer `scripts/android-emulator.sh` had already reached for
 `make android-install`.
 Related, and it will bite once: the launcher activity is
 `com.wails.app.MainActivity` and the applicationId is
@@ -356,27 +287,6 @@ resolves the leading dot against the *applicationId* and fails with a
 class-not-found that reads like a broken build. Always the
 fully-qualified form.
 **`wails3 task android:run:device` is the way to put a debug build on a
 real device**, since #159. What #52 used, before it was safe, was the
 longer form, and it is still the smallest thing that works if you want
 no script between you and adb:
 ```bash
 wails3 task android:build ARCH=arm64 && wails3 task android:assemble:apk
 adb install -r bin/yellowjacket.apk      # -r, never uninstall
 adb shell am start -n app.yellowjacket.dev/com.wails.app.MainActivity
 ```
 The id in that last line is the one thing to keep an eye on by hand —
 `./scripts/android-pkgid.sh bin/yellowjacket.apk` is what the tasks ask,
 and it is a good habit before any `am start` written out in full.
 `YJ_ANDROID_PKG=app.yellowjacket.dev` still overrides what
 `scripts/android-emulator.sh` — and therefore `make android-smoke`,
 `android-logs`, `android-launch` — addresses, but it is rarely needed
 now: that default is read from `bin/yellowjacket.apk`, so it already
 follows whichever variant was built last.
 ## What only a device can answer
 The emulator cannot run this app (three separate reasons, none of them
@@ -401,91 +311,6 @@ system bars, the back gesture, focus and audio interruptions,
 permission dialogs, the keyboard — not about what the app draws. The
 drawing is what the other five tiers already cover.
 **The third such fault was the activity lifecycle** (#52), and it is
 the one to re-check after touching `main()`, `WailsBridge` or
 `MainActivity`. Android destroys and recreates an activity **without
 restarting the process**, and Wails' `nativeInit` — which
 `MainActivity.onCreate` calls — runs `go mainFunc()` every time. So
 Go's `main()` ran again on a live app, `app.Run()` refused (`a.starting`
 is still true behind Android's `select{}`), and the `os.Exit(1)` under
 it took the healthy first app down with it.
 ### The lifecycle check, and how to trigger it on demand
 This is the regression guard for #52 on this tier, because no other
 tier runs `main()` on Android at all. The Go-side guard
 (`TestMainClaimsBeforeItDoesAnything`) catches work creeping above the
 latch; only the device catches the latch not working.
 **Trigger a relaunch with a configuration change the manifest does not
 declare.** `AndroidManifest.xml` lists
 `orientation|screenSize|keyboardHidden|uiMode`, so those are handled
 in-place and are *not* triggers. `fontScale` is not listed, and it is a
 one-liner:
 ```bash
 adb shell settings put system font_scale 1.15   # restore the old value after
 ```
 That is the same in-process destroy/recreate that "Don't keep
 activities", a locale change and a memory trim produce, but on demand.
 **"Don't keep activities" is the report's own lever and did not work on
 this device**: `settings put global always_finish_activities 1` reads
 back as `1`, `am set-always-finish-activities` does not exist on this
 build, and the activity was never finished on backgrounding. Do not
 spend an afternoon on it; use the config change.
 **The assertion is the pid, and the tell is two bridge inits in one.**
 ```bash
 adb logcat -d | grep -E "Wails bridge initialized|has died|finishDrawing of relaunch"
 ```
 Healthy is one pid appearing twice — the process surviving the
 recreation:
 ```
 I/WailsBridge(28420): Wails bridge initialized
 I/WailsBridge(28420): Wails bridge initialized     <- same pid, recreated
 ```
 Broken is that pair followed within a second by:
 ```
 I/WindowManager: finishDrawing of relaunch: Window{...MainActivity} 603ms
 I/ActivityManager: Process app.yellowjacket.dev (pid 22956) has died: fg  TOP
 W/ActivityTaskManager: Force removing ActivityRecord{...}: app died, no saved state
 ```
 Two things about reading that. **`has died: fg  TOP` is not a memory
 kill** — the system does not reclaim the foreground process, so this is
 the app leaving of its own accord. And there is **no crash record
 anywhere**: `logcat -b crash` is empty, no `AndroidRuntime`, no
 `libc: Fatal signal`, no tombstone. That is the `os.Exit` signature,
 and it is why "the system killed it" is the wrong first hypothesis.
 **Surviving is only half of it — check the recreated WebView is still
 wired to the running app.** A plausible-looking fix (making
 `WailsBridge.initialized` static, so the second `nativeInit` is skipped)
 keeps the process alive and silently breaks this, because `nativeInit`
 is also what re-points the JNI reference at the new bridge. Go would go
 on executing JavaScript against the destroyed activity's WebView: the
 app opens, renders, and never receives another backend event.
 Ask the page, after a relaunch and a resume:
 ```bash
 make android-inspect
 make android-eval EXPR='(()=>{window.__probe=[];const o=window._wails.dispatchWailsEvent.bind(window._wails);window._wails.dispatchWailsEvent=(e)=>{window.__probe.push(e&&e.name);return o(e)};return "ok"})()'
 # background and foreground the app, then:
 make android-eval EXPR='JSON.stringify(window.__probe)'
 ```
 A healthy build answers with events from the live services —
 `["IndexStatusChanged","JobsChanged","JobsChanged","android:storageAccess"]`.
 `[]` means the bridge reference is stale.
 ## Asking the device, not just looking at it
 A real phone can be inspected, and that turns this tier from "reported
@@ -515,75 +340,6 @@ Four things about it, each of which costs an hour if met cold:
  script. Plug in over USB for anything longer than a couple of probes.
 - **The socket name carries the pid**, which changes on every launch, so
  it is resolved rather than remembered.
 - **A reinstall resets the runtime permissions**, and the grant dialog
  is a separate activity that takes focus — so the app is up, `am start`
  reports "delivered to currently running top-most instance", and
  `pidof` is empty because it never got to the foreground.
  `dumpsys window | grep mCurrentFocus` naming
  `GrantPermissionsActivity` is the tell. `adb shell pm grant
  app.yellowjacket.dev android.permission.READ_MEDIA_AUDIO` (and
  `POST_NOTIFICATIONS`) ahead of the launch skips it.
 ### Calling a binding on the device
 **The runtime call does not go over HTTP on Android**, and this is worth
 knowing before an hour is spent on it. The WebView cannot deliver a
 `fetch()` POST body to `shouldInterceptRequest`, so v3 routes runtime
 calls through the `addJavascriptInterface` bridge instead: the
@wailsio/runtime installs a `customTransport` that calls
 `window.wails.invokeAsync(id, payload)` and receives the answer on
 `window._wailsAndroidCallback`. Two consequences:
 - **`.playwright/init-events.js` does not transfer to the device.** Its
  outbound half hooks `fetch`, which sees nothing here, and its
  `call()` posts to `/wails/runtime`, which answers
  `Invalid runtime call: missing object value` — the interceptor got the
  URL with no body. Its *inbound* half is still right, because
  `dispatchWailsEvent` is the entry point in every mode.
 - **Hooking `fetch` from an eval is too late anyway**, on any platform:
  the bundle captured its reference at module scope, so a wrapper
  installed afterwards records nothing. That is why the harness is an
  `initScript` and not a step in a spec.
 What works is to borrow the bridge, chaining the runtime's own callback
 so its pending calls still resolve:
 ```js
 const pending = new Map();
 const prev = window._wailsAndroidCallback;
 window._wailsAndroidCallback = (id, response, error) => {
  if (!pending.has(id)) return prev && prev(id, response, error);
  const p = pending.get(id); pending.delete(id);
  const env = JSON.parse(response || "{}");
  return env.ok ? p.resolve(env.data ?? env.text) : p.reject(new Error(env.error));
 };
 window.__yj = { call(name, args) {
  return new Promise((resolve, reject) => {
    const id = "yj" + Math.random().toString(36).slice(2);
    pending.set(id, { resolve, reject });
    window.wails.invokeAsync(id, JSON.stringify({
      object: 0, method: 0, windowName: "",
      args: { "call-id": id, methodName: "yellowjacket/backend/" + name, args: args || [] },
      clientId: window._wails.clientId,
    }));
  });
 } };
 ```
 That turns the device into a tier that can be *driven* rather than only
 looked at — `__yj.call("player.Player.LoadFile", [path])` and
 `__yj.call("library.Library.AddLibrary", ["/sdcard/Music/..."])` are how
 #53 was measured. Names are the Go ones (`GetTracks`, not
 `GetAllTracks`); an unknown one comes back as a plain
 `unknown bound method name`, so a wrong guess is loud.
 **Getting audio onto the phone**: `adb push` into
 `/sdcard/Android/data/<pkg>/files/` looks like it works and then the
 files are not there — scoped storage. `/sdcard/Music/...` plus
 `pm grant … READ_MEDIA_AUDIO` does work, and `AddLibrary` takes the
 plain path. The generated fixtures are **~2 seconds** each, which is
 fine for a scan and useless for watching a seek bar, so synthesise a
 long one: `ffmpeg -f lavfi -i sine=frequency=440:duration=240`.
 **And the reason to bother: the phone is an engine, not a screen.** The
 first device here renders in **Chrome 113** at 424x439 CSS px. Every
@@ -13,7 +13,7 @@ reviews. Nothing was changed.
 Findings below are numbered `H-n` (hands-on) and cross-reference the
 static reports where they overlap. The reconciliation plan built from
-all four files is `.planning/plans/completed/007-ui-reconciliation.md`.
+all four files is `.planning/plans/pending/007-ui-reconciliation.md`.
 ---
@@ -1,7 +1,5 @@
 # Autotag (v1.3) — MusicBrainz Autotagger
 > **Historical record.** Phases 008–010 shipped, and the scoring engine was subsequently overhauled (`recommend.go`, `rank.go`, `mixedbag.go`), which makes the 011/012 sections below stale in their details. What is actually left is **#90** (auto-accept and entry points) and **#91** (settings, and a way back from the dismissed file-write warning).
 The MusicBrainz autotagger, collectively **v1.3**. Builds on the explore-browser API client + cache foundation. Five sequential phases (008–012), each depending on the prior one.
 | Phase | Title | Status |
@@ -1,7 +1,5 @@
 # 015 — Android release pipeline
 > **Completed.** The pipeline ships a signed APK from CI on every `v*` tag; `docs/android-release.md` is its operating document.
 Ship an Android APK from CI on every version tag, published to the Gitea
 generic package registry so Obtainium can poll a plain URL.
@@ -1,7 +1,5 @@
 # 015 — Multi-artist credits, navigable
 > **Completed.** Phases 1, 2 and 4 shipped. Running the ingest against the real dump and publishing an artifact that carries credits is **#88**; Phase 3 (`file_artists`) is **#89**, blocked on it.
 ## The problem
 A track credited to more than one artist has exactly one navigable
@@ -1,87 +0,0 @@
 # 017 — Releases that happen by themselves
 **Shipped as `v0.0.1`.** A merge to `main` now reads the Conventional
 Commits since the last tag, cuts the tag and the Gitea release whose body
 is the generated changelog, and the four publishing workflows build that
 tag and attach their artifacts. Nothing is released by hand.
 ## What it looks like now
 `release.yml` on push to `main` → semantic-release → tag → four `v*`
 workflows in parallel (serialised in practice by the capacity-1 runner):
 | workflow | publishes | attaches |
 | --- | --- | --- |
 | `arch-package` | pacman registry | `…-x86_64.pkg.tar.zst` |
 | `android-apk` | generic registry (Obtainium) | `…-android-arm64.apk` |
 | `desktop-assets` | — | `…-linux-amd64.tar.gz` |
 | `homebrew-formula` | the public tap | — (builds from source) |
 Verified on the real thing: all five green, three assets on the release,
 the tap at `0.0.1`, and the Obtainium `latest` URL serving 200.
 ## The five decisions, and what they cost
 1. **semantic-release, not a shell script.** The first draft of this plan
   proposed hand-rolling it and the argument did not survive checking:
   `@semantic-release/exec` is first-party and current, and the
   Gitea-shaped part is one `curl`. What I would have hand-rolled —
   commit parsing, semver ordering, note rendering — is the part with the
   edge cases and none of it is Gitea-shaped.
 2. **`@saithodev/semantic-release-gitea` is a dead end** and was offered
   before it was checked: last published 2022, `got@10`, and no peer
   dependency on semantic-release at all.
 3. **No `@semantic-release/git`.** `main` is protected, so a changelog
   commit-back is rejected by the pre-receive hook — and would be
   rejected *after* the tag was pushed, leaving a tagged release the run
   reports as failed. The release page is the changelog;
   `.release-notes.md` is a gitignored carrier and `CHANGELOG.md` is a
   signpost.
 4. **Versions restart at `0.0.1`**, a downgrade on every channel. No
   `epoch`, no `versionCode` offset: both are permanent, a reinstall is
   once. Documented in `packaging/homebrew/README.md` and
   `docs/android-release.md`.
 5. **No macOS and no Windows.** `GOOS=darwin CGO_ENABLED=0` fails at
   `wails/v3/pkg/mac` and there is no macOS runner, so Homebrew-from-source
   stays that channel. Windows cross-compiles in ~2.5 s and is withheld
   because no build of it has ever been *run*.
 ## Four things that only showed up by running it
 - **`conventional-changelog-conventionalcommits@10` renders empty
  notes.** Silently: right version, right tag, every step green, and a
  release body that is a bare `## 0.0.1 (date)` heading with nothing
  beneath it. Held at `9`, in `release.yml` and `make release-dry`, with
  the reason beside both. **Check the rendered notes, never the exit
  code.**
 - **semantic-release core dry-run-pushes to the release branch** as a
  permission check, independently of any plugin. `PACKAGE_TOKEN` had
  package-write and repo-*read* — enough to clone, not enough for this —
  and it failed with a flat `403 Forbidden` that reads exactly like
  branch protection. It is not: a `--dry-run` push never reaches the
  pre-receive hook, which a one-line experiment settled. The token needed
  `write:repository`.
 - **The floor tag must go on `HEAD^`, not `HEAD`.** Seeded on the merge
  commit itself it leaves nothing between the floor and HEAD, and
  semantic-release correctly reports there is nothing to release. The
  first run did exactly that and cut nothing.
 - **A tag-triggered workflow runs from the tagged commit's tree.**
  Moving `v0.0.0` back to `6fb7b5e` ran the *pre-merge* homebrew
  workflow, which predates the `v0.0.0` skip guard, and pushed a `0.0.0`
  formula to the public tap. Self-corrected at `0.0.1`. The corollary is
  general: a guard added today does not protect a tag pointing at
  yesterday.
 ## Two mechanisms confirmed, having been assumptions
 - **A tag pushed with a user PAT does start the `v*` workflows**; one
  pushed with the Actions token does not (go-gitea#33123). Both halves
  are load-bearing and both were observed: the floor seed triggered
  nothing, and the release tag triggered all four.
 - **Tags are not protected** on this repo, only `main` — which is what
  lets semantic-release tag at all.
 ## Left behind deliberately
 `v0.0.0` stays on `origin` as the floor. It carries no release, and all
 four publishers skip it by name.
@@ -1,327 +0,0 @@
 # 018 — Supported sizes, and what the queue panel is
 **Issue:** #24 (`Area/Shell-Nav`, `Priority/High`, `Reviewed/Confirmed`)
 **Unblocks:** #55 (queue as a screen) — a real Gitea dependency
 **Relates:** #69 (page-header overflow), #12 (mini-player), #51 (small-screen umbrella)
 **Status:** complete — #24 shipped as PR #132, and the matrix's last
 unkept promise closed with #69.
 #73 puts this first in Phase 2 and hangs the rest of the phase off it,
 so the decision has to be written down and arguable before any CSS
 moves. This document is the decision. Everything below the matrix is
 either a measurement or an argument for one of the four choices #24
 asks for.
 ---
 ## What is actually wrong, measured
 Against the running app (`make dev-headless SEED=default`, Chromium),
 Playlists, sweeping the viewport with the queue open and closed. The
 number that matters is how much of the page header survives.
 | viewport | sidebar | queue | main panel | header needs | actions clipped |
 |---|---|---|---|---|---|
 | 1280×800 | 200 | open 321 | 759 | 759 | — |
 | 1000×700 | 200 | open 321 | 479 | 747 | New Playlist, New Smart Playlist |
 | **900×600** | 200 | open 321 | **379** | 747 | **all three** |
 | 800×600 | 56 | open 321 | 423 | 747 | all three |
 | 700×600 | 56 | open 321 | 323 | 747 | all three |
 | 390×780 | — | open 321 | **69** | 747 | all three |
 | 320×600 | — | open 321 | **0** | 747 | all three |
 | 900×600 | 200 | closed | 700 | 747 | New Smart Playlist |
 | **800×600** | 56 | closed | 744 | 747 | **New Smart Playlist (158/162px)** |
 | 320×600 | — | closed | 320 | 747 | all three |
 Five things in that table are not in the issue.
 **The header clips at the supported minimum with the queue closed.**
 At 800×600 — the size `backend/config/window.go` enforces and the only
 size this app *promises* — "New Smart Playlist" loses 4px of its 162.
 #24 reads as a queue-panel bug; the queue makes it dramatic, but the
 header overflows on its own at the minimum window.
 **900×600 is worse than 800×600, because the sidebar expands at 900.**
 `AUTO_COLLAPSE_VIEWPORT` collapses the sidebar to icons *below* 900, so
 at 899px the main panel is 843px and at 900px it is 700px. The worst
 desktop case is therefore not the minimum window; it is the pixel
 immediately above the collapse. Anything that tests "the minimum" and
 stops has not tested the worst case, which is what
 `layout-overflow.spec.ts` does today.
 **At phone widths the queue is not a drawer, it is an amputation.**
 `queue-panel`'s host is `flex-shrink: 0; width: 0`, going to
 `width: var(--queue-width, 320px)` under `[open]` — it is *in the flow*
 of `.content-area`, so it takes its width from the main panel rather
 than covering it. At 390px that leaves 69px of the page; at 320px it
 leaves **0px**, and the app is not degraded but gone. This is the
 measurement #55 needs and did not have.
 **Only Playlists overflows.** Sweeping all ten primary views at 900×600
 and at 390×780, every other header reports `scrollWidth ==
 clientWidth`, and Albums at 390px renders title, count and sort
 legibly (checked on a screenshot, not just the number). #69 is
 therefore one view's action set — three text buttons totalling 390px —
 and not a systemic header failure, though the *rule* still belongs in
 `page-header`.
 **Both reasons in `MinWidth`'s comment are stale.** It says the floor is
 800×600 because "below ~780 the header's subtitle wraps" and "below
 ~600 tall the eleven sidebar items no longer fit". The subtitle is
 `display: none` below 900 (index.css), and the sidebar host is
 `overflow-y: auto` — at 600×460 its `scrollHeight` is 434 against a
 332px client, and Settings is reachable after scrolling. Neither
 mechanism can happen any more. That does not mean the floor should
 move; it means its stated reason no longer supports it, which is worse
 than either answer.
 *(Care needed: my first probe for the sidebar scroller searched
 `shadowRoot.querySelectorAll('*')` and reported "items are
 unreachable", because the scroller is the **host** and a host is not in
 its own shadow root. The claim in CLAUDE.md is correct.)*
 ---
 ## Decision 1 — the supported size matrix
 Three bands. Two of them already exist and are already argued; what is
 new is that they are written down as a *promise*, and that the queue is
 part of it.
 | band | width | navigation | queue | promise |
 |---|---|---|---|---|
 | **Phone** | < 600 | `bottom-nav` + drawer | overlay, full width | reflows; nothing needs sideways scrolling; fits 320px |
 | **Compact** | 600 – 899 | icon sidebar | overlay + scrim | nothing is clipped or unreachable at any width in the band |
 | **Desktop** | ≥ 900 | labelled sidebar | inline where it fits (see decision 2), else overlay | as Compact |
 And one promise across all three: **no action is ever unreachable.**
 That is the sentence #69 asks for and it is the one the matrix exists
 to make checkable.
 **400% zoom** keeps the meaning it already has: WCAG 1.4.10 names 320px
 as the reflow target, the phone band covers it, and
 `layout-overflow.spec.ts` already asserts a 320px viewport needs no
 sideways scrolling. What changes is that the *queue* must be part of
 that assertion — it is not today, and with the queue open at 320px the
 main panel is 0px wide, which no current test can see.
 **The window minimum stays 800×600**, and its comment gets the real
 reason. The old mechanisms are gone, but the floor is still where the
 Compact band's chrome stops being comfortable, and lowering it would
 mean promising the desktop layout at sizes where only the phone layout
 works. The interesting consequence is decision 4.
 ---
 ## Decision 2 — the queue is an overlay when it cannot afford to be a column
 **The rule.** The queue panel renders inline — in the flow, as today —
 only while
 ```
 viewport − sidebar − queueWidth ≥ 480
 ```
 and as an overlay with a scrim otherwise.
 **Why it cannot be a media query**, which is the load-bearing half:
 the queue's width is *user state*. It is drag-resizable between 200 and
 500px and persisted (`--queue-width`, `MIN_WIDTH`/`MAX_WIDTH` in
 `queue-panel.ts`). A breakpoint at a fixed viewport width silently
 assumes the default 320, and is wrong by 180px for a user who has
 dragged the panel wide — in the direction that hurts, since a wider
 queue is exactly when the content can least afford it. So the mode is
 computed from the measured widths and published as an attribute, the
 way `data-active-view` already is, and the CSS keys off that.
 **Why 480, honestly.** There is no cliff to derive it from. The track
 list rescales its columns continuously — at main widths from 900 down
 to 544 its `--grid-cols` shrink from 213px to 124px with
 `rowOverflow=0` throughout — and the album grid steps 3 columns to 2
 somewhere between 564 and 644 without breaking. So this is a judgement,
 anchored on two things: it keeps the *default* window (1100 wide, main
 = 580) inline, because the inline queue is a desktop affordance people
 choose and turning it into an overlay for the common case would be a
 regression in feel; and it puts every case measured as broken —
 900×600 at main=379, and every phone width — on the overlay side.
 1024×768 lands at main=504 and stays inline.
 **The scrim is the other half of the issue's complaint** ("make the
 queue obviously an overlay *over* the content so it reads as something
 to close"). An overlay queue gets a scrim, closes on scrim click and on
 Escape, and returns focus to `#queue-button`.
 **What must not change**: #55's Direction is explicit — one component,
 two mount points, do not fork it. The overlay is a *presentation* of
 the same `queue-panel`, so the roving tab stop, Alt+Arrow reorder, drag
 reorder, selection semantics and the `virtualizer.requestUpdate()` on
 selection and current-track change all come along untouched. This
 decision deliberately stops short of #55's detail-view mount, but it is
 the shape that makes it possible, and it unblocks it.
 ---
 ## Decision 3 — #69 is its own PR, and here is the finding that decides it
 `page-header` **cannot collapse its own actions**, and that is not an
 effort estimate but a fact about the API. Actions arrive through
 `<slot name="actions">` as arbitrary light-DOM markup — Playlists slots
 a `<div class="header-actions">` of three `<button>`s with click
 handlers, drag handlers and a conditional class. A component cannot
 move another component's light-DOM children into a dropdown and keep
 their behaviour; there is nothing generic to render as a menu item.
 So the overflow rule needs an *actions API* — hosts declaring
 `{icon, label, handler, priority}` data that `page-header` can render
 either as buttons or as menu items — which is a change to all three
 hosts that slot actions, not a rule added in one place. That is a
 different piece of work from this one, it is independently verifiable,
 and the desktop half of #69's symptom is removed by decision 2 anyway
 (the queue stops eating the header's width).
 It therefore stays #69, gets the finding above recorded on it, and
 follows immediately after this. What *this* plan owes it is the
 promise in the matrix — no action unreachable at any supported size —
 and the measurement that the only offender today is Playlists.
 **And the promise is not kept yet, which is the honest version of a
 claim this document made in its first draft.** "Decision 2 removes the
 desktop half of #69's symptom" was too strong. Measured after phase 2,
 at 900×600 on Playlists:
 | | before | after |
 |---|---|---|
 | queue open | main 379px, **all three** actions clipped | main 700px, **one** clipped |
 | queue closed | main 700px, one clipped | unchanged |
 So the queue's *contribution* is gone — open and closed are now
 identical, which is the whole of what this decision owed — and the
 residual "New Smart Playlist: 114/162px" is the header overflowing on
 its own, at a size the queue never touched. #69 is still a live defect
 at a supported size, and the matrix's promise is what will close it.
 ---
 ## Decision 4 — a very small window becomes the phone layout, not the mini-player
 #24 asks whether a very small window should switch to the mini-player
 (#12) "or simply refuse to go there". Both options in the question are
 worse than the one the codebase already has.
 **#12 is a second window, not a mode.** Its findings say so: v3
 supports multiple windows, `AlwaysOnTop` is a window *option*, and the
 frontend would need an entry branch mounting only the mini-player root
 for a second window loading the same bundle. Turning the main window
 into a mini-player at some width conflates the two: it would throw away
 the user's navigation state on a resize, and it puts the MPRIS question
 (#12's own open question — media controls are process-level and must
 not be per-window) on a code path that a drag can trigger by accident.
 **And "refuses" is unnecessary, because the reflow already exists.**
 The phone band is real, tested, and reached by width alone — a desktop
 window narrowed below 600px already gets `bottom-nav` and the phone
 shell. That is a better answer than refusing: it is strictly more
 usable than a hard minimum, it costs nothing new, and it is the same
 code Android runs, so it stays exercised.
 So: the main window reflows and never becomes a mini-player; #12 stays
 a separate always-on-top window and is not blocked by, or coupled to,
 this decision. The window minimum stays 800×600 for the reason in
 decision 1 — but the phone band is what happens below it, not a
 refusal, which is why the minimum is a comfort floor rather than a
 correctness one.
 ---
 ## Phases
 1. **This document**, linked from #24, with the matrix reported on the
   issue and #55 told whether it is unblocked. *(no code)* — **done**
 2. **The queue's overlay mode** — computed mode attribute, scrim,
   Escape and scrim-click close, focus return. The inline path is
   unchanged above the threshold. — **done**
 3. **The window minimum's comment** — replace both stale reasons with
   the measured ones. No value change. — **done**
 4. **Verification**, below. Including the specs that must change
   because they assert the old behaviour. — **done**
 #69 follows as its own branch; #55 became unblocked at phase 2.
 ## What landed, measured
 Main panel width with the queue open, before and after:
 | viewport | before | after | mode |
 |---|---|---|---|
 | 1280×800 | 759 | 759 | inline |
 | 1100×720 (default window) | 579 | 579 | inline |
 | 1024×768 | 503 | 503 | inline |
 | 900×600 | **379** | **700** | overlay |
 | 800×600 | 423 | 744 | overlay |
 | 390×780 | **69** | **390** | overlay |
 | 320×600 | **0** | **320** | overlay |
 The scrim is perceptible but subtle on a dark ramp, which is worth
 knowing before someone "fixes" it: sampled from the screenshots at
 900×600, the main panel's background goes 33,37,41 → 18,20,23 and a
 row's text 242 → 133. It covers the **content area only** — not the
 sidebar or the transport — on purpose: the queue is not modal, and
 leaving the navigation live means the scrim reads as "this is over the
 content" (which is what #24 asked for) without pretending the rest of
 the app is unavailable.
 ## What #69 did with the promise, and one thing this plan got wrong
 #69 landed on its own branch as decision 3 said it would, and the
 matrix's *no action is ever unreachable at any supported size* is now
 kept rather than promised. Measured on Playlists, actions clipped:
 | viewport | before #24 | after #24 | after #69 |
 |---|---|---|---|
 | 900×600, queue open | all three | one (114/162px) | none |
 | 900×600, queue closed | one | one | none |
 | 800×600, queue closed | one (158/162px) | one | none |
 | 390×780 | all three | all three | none |
 | 320×600 | all three | all three | none |
 The shape was the one decision 3 predicted — an actions API first, an
 overflow rule second — and all three hosts that slot actions migrated.
 **What this document got wrong is smaller and worth keeping.** Decision
 1 says the header's minimum is a *comfort* floor and that only the
 queue and the actions compete for the header's width. They are not the
 only two: every child of that flex row was `flex-shrink: 0`, so
 whatever came last lost, and the actions come last. At 320px the sort
 control alone is 172px of the header — so with every action already
 collapsed into the menu, the *menu button* was 76px off the right edge.
 The promise was still broken with nothing left to collapse.
 That is why #69 also had to decide what gives way: the title (which the
 navigation also states) and, below 600px, the word "Sort:" (which the
 direction arrow implies). Neither is an action, which is the rule the
 matrix actually encodes — **an action is a capability and everything
 else on that row is a label.**
 ## Verification, and what each tier cannot see
 - `make ui-test` — the queue panel's mode logic is component-tier
  work and belongs there. It **cannot** see the shell: the threshold is
  computed from the sidebar and viewport, which do not exist in that
  tier.
 - `make e2e` — `layout-overflow.spec.ts` gains the queue-open case at
  every band (it has none today, which is why main=0px at 320px has
  never failed anything) and **gains 900×600**, since the minimum is
  not the worst case. `queue-toggle-state.spec.ts` and
  `phone-shell.spec.ts` both touch the panel and must be re-read before
  editing.
 - **Screenshots at every band, read by a human.** This is not optional
  here: `layout-overflow.spec.ts` asserts the *shell* needs no sideways
  scrolling and passes on a build whose album header clips its own
  buttons (measured this session at 390px; filed on #66). Clipping
  *inside* a component is invisible to it, and clipping is this issue.
 - `make ui-visual` **cannot help at all** — the component tier renders
  the token fallbacks, because the theme only reaches `:root` in the
  real app.
 - Accessible names via `page.getByRole(...)`, never a shadow-root
  query. A drawer with a scrim is exactly the shape that grows a
  nameless control, and this repo has shipped one three times.
@@ -0,0 +1,195 @@
 # 010 — Owned albums, offline
 **Status:** not started — and **much smaller than when it was written**
 **Branch:** none yet
 **Created:** 2026-08-13
 **Depends on:** nothing
 **Related:** the `AlbumReleasesFailed` fix that prompted it, and the
 tag-derived completeness that landed after it (same session)
 ---
 ## What already shipped, and what it leaves
 The common case is solved without this plan. `GetAlbumCompleteness`
 reads the "5/12" denominator off the files' own tags — persisted to
 `release_group_recordings.total_tracks`, having been extracted at every
 scan since forever and discarded — and an album that is **MBID-matched
 and complete** now opens with **no catalog call at all**. Identity from
 the MBID, tracklist from the tags; those were the two things the browse
 was being spent on.
 So the set this plan still has to serve is not "albums you own a track
 of". It is:
 - albums that are genuinely **incomplete** (the catalog is the only way
  to say *which* tracks are missing — tags give the count, not the
  names), and
 - albums whose tags **never declared a total**, where completeness is
  unknowable locally and the catalog is the only source.
 On a well-tagged library that is a small minority, which changes the
 economics below considerably: the run is shorter, and the rate limiter
 contention that dominates this design is proportionally less severe.
 Re-measure before building — the answer may now be "the prefetch is
 enough".
 ---
 ## The problem
 Opening an album detail page for an album **you already own** hits
 MusicBrainz. Every time it is not in the response cache, which for most
 of a library is every time, because nothing warms that cache except a
 capped prefetch on the artist page.
 The user's framing: *this is a classic example of an album we should
 have had locally.*
 ## Why we do not have it, despite the discography backfill
 `BackfillLibraryDiscographies` / `EnsureArtistDiscography`
 (`backend/explore/searchindex.go:301`, `:397`) do less than the name
 suggests. Per artist, `indexOneArtist` fetches:
 - `fetchTopReleaseGroups` — capped at `indexMaxRGs` (50)
 - `fetchTopRecordings` — capped at `indexMaxRecs` (200)
 and writes them as **flat `explore_index` rows**. There is no release
 group → tracklist relation anywhere in the index, and no release-level
 rows at all. `explore_index` recordings carry `caa_release_mbid` and
 `release_name`, which name the release used for cover art — not a
 tracklist.
 So "we have full discographies for library artists" means *we know
 which albums the artist made, offline*. It has never meant we know
 what is on any of them.
 The only store of release-level catalog data in the app is `http_cache`
 under `mb:browse:releases:<rg>` (90-day TTL, `musicbrainz.go:27`),
 populated **only** by a live `BrowseReleases` with
 `Includes: ["recordings", "media"]` at `MaxLimit` — the most expensive
 call the app makes to MusicBrainz. It is warmed by exactly one thing:
 `PrefetchReleases` (`explore.go:746`), capped at 8, called only when an
 artist page renders.
 An album opened from the library grid therefore always browses live.
 ## What to build
 **A post-scan backfill that warms the release cache for release groups
 that are owned but not known-complete** — bounded, resumable, and
 shaped exactly like `BackfillLibraryDiscographies`, which is the proven
 pattern for this in the codebase.
 The scoping rule is the user's and it is the right one: not "every
 album by every artist in the library" (50 release groups per artist,
 mostly never opened) but albums with owned tracks — narrowed further,
 now, to the ones a local answer cannot already cover. The query gains
 one clause: skip release groups whose `GetAlbumCompleteness` reports
 `complete`.
 Sketch:
 1. A query for release groups with ≥1 owned track and no warm release
   cache entry. `release_groups.mbid` is the key; the owned-track join
   is `audio_files → recordings → release_group_recordings`, the same
   shape `unenrichedLibraryArtistMBIDs` already uses one table over.
 2. Order by owned-track count descending, so the albums the user has
   most of are warmed first — same reasoning as the discography
   backfill's ordering, same benefit if a run is cut short.
 3. Run through `releasesSF`, so it never double-fetches a release group
   an interactive open is already handling.
 4. Bound a run (`discogBackfillMaxPerRun` has a value to copy) and make
   it resumable: the resume marker is the response cache itself —
   `BrowseReleasesCached` already answers "is this one done", so unlike
   the discography path this needs **no new flag column**.
 5. Trigger it where `BackfillLibraryDiscographies` is triggered, and
   register it with `jobs` so it has progress, pause and cancel like
   every other long-running operation.
 ### The rate limiter is the whole design constraint
 > **Update (2026-08-13): the priority half is built, and the sentence
 > below is wrong on a detail.** `e.mb` runs on `mbSearchLimiter`
 > (`NewRateLimiterBurst(3, 1)`); the 1 req/s `NewRateLimiter()` cited
 > here is the *artist image* limiter. Both are shared and both were
 > FIFO. `RateLimiter.WithBackgroundLane` + `WithBackgroundPriority(ctx)`
 > now make a marked caller yield to interactive work and pace at 1/s,
 > and `jobs.KindCatalogEnrich` + `startBackfillJob` give the existing
 > backfills progress and cancel. **"Do not start until the priority
 > question has an answer" is satisfied** — mark this backfill's context
 > and register it the way `BackfillLibraryDiscographies` now is.
 > `PrefetchReleases`' cap of 8 is still unrevisited.
 One shared `NewRateLimiter()` at 1 req/s (`explore.go:84`) serves this,
 `PrefetchReleases`, and every interactive browse. A backfill over a
 few thousand owned albums is *hours* of wall clock at that rate — which
 is fine for a background job, and not fine if it starves the album page
 the user is looking at right now.
 That is the real work in this plan, and it is not the query:
 - Interactive browses need to **jump the queue**. Today they cannot;
  there is one limiter and it is FIFO.
 - `PrefetchReleases`' cap of 8 was sized when nothing else competed for
  the limiter. Revisit it in the same change.
 - The 60 s fallback the `AlbumReleasesFailed` fix installed is sized
  for today's contention. If a backfill can queue behind it, that
  number is wrong again — which is an argument for priority, not for a
  bigger number.
 Do not start the query until the priority question has an answer.
 ## The alternative that was considered and rejected
 **Project release-group tracklists in the dump build and ship them in
 the artifact.** The data is there: `canonical_musicbrainz_data.csv`
 carries `release_mbid` *and* `recording_mbid`
 (`dumpcatalog.go:520`), and `release_to_rg` already maps release →
 release group. It is derivable from bytes the index build already
 streams, with no new API surface at all, and it would work offline on
 first launch with no per-user backfill.
 It is rejected **for this plan** because the artifact is built
 centrally and is byte-identical for every user, so "albums the user
 owns a track of" cannot be a filter on it. Shipping tracklists for the
 whole catalog means per-recording rows against a ~900 MB artifact
 budget (~426 B/row measured), and gating on a popularity floor means it
 is absent for exactly the obscure albums a local backfill would have
 covered.
 Worse than absent, in fact — and this is the argument that actually
 kills it. The floor is not one number over artists; it is a **per
 artist track budget** (`dumpcatalog.go:58-89`): 50 tracks for a tier-A
 artist, 25 for tier B, 12 for tier C. A projected tracklist would
 therefore be *whichever* of an album's tracks survived that budget,
 with nothing marking the rest as absent — so the album page would count
 owned against a truncated denominator and render "Play 7 of 9" for a
 twelve-track album. That is a confident lie, where the honest states
 this plan's alternative produces (complete / incomplete / unknown) are
 at worst silent.
 Note that `markLibraryArtists` (`dumpcatalog.go:246`) already grants
 every library artist full coverage — 500 tracks, 100 release groups —
 by reading the local library, so the per-user tailoring this option
 supposedly cannot have does exist in code. It is a no-op in the CI
 build (empty library), and reaching it means a **local** dump build:
 the ~205 GB, half-a-day download the entire artifact design exists to
 avoid. Whoever finds that function next should read this paragraph
 before getting excited about it.
 Worth revisiting if the artifact ever gains per-user tailoring, or if a
 measurement shows the row count is smaller than feared. Note it also
 yields the *canonical* tracklist rather than MusicBrainz's full version
 list, so the versions dropdown would still browse live when opened.
 ## Done when
 - Opening an owned album that has never been opened before renders its
  catalog tracklist with no network call, after one backfill run.
 - An interactive browse issued while the backfill is running is not
  delayed by it.
 - The backfill appears in the jobs indicator, and can be paused and
  cancelled there.
 - A second run after a completed one does approximately nothing.
@@ -1,7 +1,5 @@
 # 012 — What we ask the network for, and what we already had
 > **Completed.** Findings 1, 2 and 4 shipped. Finding 3 — the bound-but-uncalled methods — is now **#86**.
 **Status:** all four findings fixed. Lint (3 configs), Go tests (3
 configs), `tsc` and 752 Vitest tests pass; **not driven against the
 real app**, so the numbers below are read off the code, not measured.
@@ -1,7 +1,5 @@
 # 016 — What Android parity would actually take
 > **Completed.** Sections A, B1, B2 and B4 shipped. B3, writing tags on the device, is now **#87**; the device-found UI faults are #51–#72, sequenced by #73.
 > **Status: all of section A is done.** A1–A3 landed with "let the app
 > reach the user's music"; A4 (MediaSession, transport notification,
 > audio focus) landed with "survive the screen locking". The direction
@@ -1,31 +1,6 @@
-# semantic-release configuration.
+# semantic-release configuration
-#
+# Runs on main branch pushes to auto-determine version from conventional commits.
-# Run by hand from .gitea/workflows/release.yml, which has no push
+# Creates a git tag + GitHub Release draft; a separate workflow builds binaries.
 # trigger: determine the version from the Conventional Commits since the
 # last tag, write the changelog, push the tag, and create the Gitea
 # release.  A release is a shipment rather than a merge, and the commits
 # accumulate until someone says so -- this file needs to know nothing
 # about that, because reading everything since the last tag is what it
 # already did.
 #
 # `branches` is main and only main.  A `prerelease: true` channel is the
 # obvious next edit here and is the one to think twice about: all four
 # publishing workflows trigger on `v*`, which matches `v0.4.0-beta.1`.
 # They carry a prerelease guard now, so the failure is a clean skip
 # rather than a beta in a public tap -- but they are four separate files
 # and this is the line that would turn them on.
 #
 # **There is no `@semantic-release/github` plugin here and there must not
 # be.** Gitea's API is `/api/v1` and is not GitHub's surface. The Gitea
 # community plugin (@saithodev/semantic-release-gitea) was considered and
 # rejected: last published 2022, depends on got@10, and declares no peer
 # dependency on semantic-release at all — i.e. untested against anything
 # since v19, against a core now at v25. `exec` is first-party, current,
 # and the Gitea-shaped part is one curl.
 #
 # The type list below is the one scripts/commit-check.sh enforces the
 # grammar for — keep the two in step, or semantic-release will silently
 # decline to release something the commit hook accepted.
 branches:
  - main
@@ -88,41 +63,19 @@ plugins:
            section: Build
            hidden: true
-  # Render the notes to a file.
+  # Write CHANGELOG.md.
  #
  # **This plugin is here to carry the notes, not to maintain a document.**
  # It is how they reach the Gitea API *without being interpolated into a
  # shell command*: release notes are rendered commit messages — arbitrary
  # text carrying backticks, quotes and `$` — so templating
  # ${nextRelease.notes} into `publishCmd` would be a shell injection with
  # the commit log as its input. scripts/gitea-release.sh reads the top
  # section of this file instead, and the only thing interpolated below is
  # a semver string.
  #
  # The target is a gitignored build artifact rather than CHANGELOG.md,
  # because nothing commits it back — see below.
  - - "@semantic-release/changelog"
-    - changelogFile: .release-notes.md
+    - changelogFile: CHANGELOG.md
      changelogTitle: "# Release notes"
-  # Create the Gitea release, whose body is that section.
+  # Commit the changelog back to the repo.
-  # `publish` runs after `prepare`, so the tag already exists by here.
+  - - "@semantic-release/git"
-  - - "@semantic-release/exec"
+    - assets:
-    - publishCmd: "./scripts/gitea-release.sh ${nextRelease.version}"
+        - CHANGELOG.md
-
+      message: "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
  # **There is deliberately no @semantic-release/git here.**
  #
  # `main` is a protected branch with `enable_push: false` and an empty
  # push whitelist, so a changelog commit-back would be rejected by the
  # pre-receive hook — *after* the tag had already been pushed, leaving a
  # tagged release the run then reported as failed. The alternative was to
  # whitelist the CI user, which weakens a protection someone set on
  # purpose and lets a bot push to main without passing the checks every
  # human PR has to.
  #
  # So the release page is the changelog. Tags are not protected, so the
  # tag push semantic-release does itself is unaffected. CHANGELOG.md in
  # the repo is a signpost to the releases page and is not written by any
  # of this; a file that claimed to be a changelog and silently stopped
  # updating would be worse than no file at all.
  # Create the GitHub Release (draft, so the build workflow can attach binaries).
  - - "@semantic-release/github"
    - draft: true
      successComment: false
      failComment: false
      releasedLabels: false
@@ -1 +0,0 @@
 CLAUDE.md
@@ -1,26 +1,377 @@
-# Changelog
+## [1.3.0](https://github.com/onion-4-dinner/yellowjacket/compare/v1.2.3...v1.3.0) (2026-03-20)
-The changelog is the releases page:
+### Features
-<https://git.ljones.me/yonlu/yellowjacket/releases>
+* **09-01:** add scan control events and cancelled metrics field ([c695024](https://github.com/onion-4-dinner/yellowjacket/commit/c695024241a7513b8fedb3fbf7ff364d0515b392))
 * **09-01:** add scan control fields and per-scan cancellable context ([cf22e52](https://github.com/onion-4-dinner/yellowjacket/commit/cf22e52a64850a80b9fcc63c21d81313e6bd56ab))
 * **09-02:** add frontend keyboard shortcut service, store, and controller ([40d4815](https://github.com/onion-4-dinner/yellowjacket/commit/40d48151dd798b57eed9f54a572ae4735356d09e))
 * **09-02:** add shortcuts config package with default bindings and Wails persistence ([6285ca9](https://github.com/onion-4-dinner/yellowjacket/commit/6285ca9dc4e6f211197e377d01c485b1ef65c300))
 * **09-03:** add scan control UI with pause/resume/cancel and confirmation dialog ([3914369](https://github.com/onion-4-dinner/yellowjacket/commit/391436927c826f2f17a4523be7829aefc04a6b12))
 * **09-04:** add keyboard shortcuts section to config page with conflict detection ([0451fb3](https://github.com/onion-4-dinner/yellowjacket/commit/0451fb38805ff2c27e43deb152daa892e733d2db))
 * **10-01:** implement migration 6 and pre-migration backup ([1179f56](https://github.com/onion-4-dinner/yellowjacket/commit/1179f56c3680112692e71e8dc7ce946446fa8a8a))
 * **10-01:** update SQL schema files for multi-library fresh installs ([535855b](https://github.com/onion-4-dinner/yellowjacket/commit/535855b383a457dd2be3298b4361313bef22b39d))
 * **10-02:** add migration 6 integration tests and NewTestDBWithLibrary helper ([bc15189](https://github.com/onion-4-dinner/yellowjacket/commit/bc151891b50e59e41da2e00dbfafbecaad11b4ac))
 * **10-02:** add sqlc queries for libraries and update playlist queries for phantom support ([02548dd](https://github.com/onion-4-dinner/yellowjacket/commit/02548dd55e59b28f3d6c8d9614f209140c979250))
 * **11-01:** per-library scan pipeline with queue coordinator ([943db1c](https://github.com/onion-4-dinner/yellowjacket/commit/943db1cf274bdf59daf28ab6c20f78ef5ef53105))
 * **11-02:** update config-page with per-library progress display and queue-aware cancel dialog ([d01591d](https://github.com/onion-4-dinner/yellowjacket/commit/d01591d6cc054a63b832c05a3164a72fdcaba342))
 * **11-02:** update library-manager with per-library progress and Scan All button ([d61f122](https://github.com/onion-4-dinner/yellowjacket/commit/d61f122b567e8ac2b30fa96c637cbebc14493c89))
 * **12-01:** add queue compaction method and wire removal hooks ([5995dfd](https://github.com/onion-4-dinner/yellowjacket/commit/5995dfd01d61cd4d2c0749eeeee2a1f93b739d68))
 * **12-01:** implement library CRUD methods and orphan cleanup pipeline ([bd44f83](https://github.com/onion-4-dinner/yellowjacket/commit/bd44f8306c9129b9420ad81938bcf8105a1cb55a))
 * **12-02:** make config sections collapsible with chevron dropdown ([12c6782](https://github.com/onion-4-dinner/yellowjacket/commit/12c678284c7582bd85cd52722f4d405b0bd0e20f))
 * **12-02:** remove Libraries sidebar nav item and view routing ([e199712](https://github.com/onion-4-dinner/yellowjacket/commit/e199712a56e1cb3c0fc43d3340abb892a6f5fa7b))
 * **12-02:** replace config-page library section with full library management UI ([ffc5d96](https://github.com/onion-4-dinner/yellowjacket/commit/ffc5d9639cf7c916a4f846590ae0d67cf13afe27))
 * **12-02:** selectable library list with checkbox scan targeting ([13a42ae](https://github.com/onion-4-dinner/yellowjacket/commit/13a42aea2287d7ed0ec9ff9856f52c1fa7767338))
 * **12-02:** show scan progress bar inline in library list entry ([df824c6](https://github.com/onion-4-dinner/yellowjacket/commit/df824c6989e92b2aefaa1ddf05b131ee319612d8))
 * **13-01:** add library-filtered Go query methods and FTS search ([5f7de50](https://github.com/onion-4-dinner/yellowjacket/commit/5f7de5060a5bc557b96203267de694ef366ed507))
 * **13-01:** add library-filtered sqlc queries for all browse views ([5cc58ce](https://github.com/onion-4-dinner/yellowjacket/commit/5cc58ce66ab70d8d5a570df5067f79ae2201037e))
 * **13-02:** add library filter dropdown and wire all views to respect active filter ([42b8cf9](https://github.com/onion-4-dinner/yellowjacket/commit/42b8cf9f52133499ffcd7363bd39dd0c1069e091))
 * **15-01:** migrate FTS5 search_index to contentless_delete=1 ([cb5155b](https://github.com/onion-4-dinner/yellowjacket/commit/cb5155b8906357ff77c5c579d57d02cf2eec6abe))
 * **15-02:** create backend/fileutil package with AtomicWrite ([4d64b5d](https://github.com/onion-4-dinner/yellowjacket/commit/4d64b5dcfe43951e8ec63383bbf72c99107c63c4))
 * **16-01:** add selectAll() to SelectionController and dispatch shortcut:select-all event ([f567762](https://github.com/onion-4-dinner/yellowjacket/commit/f5677628ef283b67370630b564f23178e43da3d2))
 * **16-01:** wire shortcut:select-all listener in track-list, queue-panel, and playlist-view ([906ea28](https://github.com/onion-4-dinner/yellowjacket/commit/906ea28751ce9f96fdeeb9410ab5f6518f09fcb9))
 * **16-02:** add go-flac dependencies and implement FLAC tag writer ([3642cbe](https://github.com/onion-4-dinner/yellowjacket/commit/3642cbe0d58f8912a786a4fc5380c40403add94a))
 * **16-03:** implement DB sync module for tag write pipeline ([2966079](https://github.com/onion-4-dinner/yellowjacket/commit/2966079625cd42412411429af02184d015526e9b))
 * **16-03:** WriteTrackTags pipeline with player safety, scan mutex, events, and app wiring ([64322f9](https://github.com/onion-4-dinner/yellowjacket/commit/64322f93538515d5a3e486dc14691b9c9dcf6f66))
 * **17-01:** add TrackMetadataChanged handler and remove selection gate on Track Details ([fc5cf70](https://github.com/onion-4-dinner/yellowjacket/commit/fc5cf70e4c1be3d3f1545c140db5202601a08109))
 * **17-01:** add WriteTrackTagsByPath and ImageFilePicker backend methods ([4235b4a](https://github.com/onion-4-dinner/yellowjacket/commit/4235b4a4d555882ce86628a88dd4e4eeee2c9097))
 * **17-02:** implement save flow, cover art editing, and error handling ([265a9ea](https://github.com/onion-4-dinner/yellowjacket/commit/265a9ea8ceba893f956a03546e9ac4189adc7716))
 * **18-01:** add BatchWriteProgress event constant ([3dba0e1](https://github.com/onion-4-dinner/yellowjacket/commit/3dba0e143c091327d305d39d2fa7a687ec47e172))
 * **18-01:** add BatchWriteTrackTags with progress, cancellation, and partial failure ([f557ffd](https://github.com/onion-4-dinner/yellowjacket/commit/f557ffd652179b7cf8f8ff4a06824f30edf08007))
 * **18-02:** add batch edit mode to track-details component ([6dab32b](https://github.com/onion-4-dinner/yellowjacket/commit/6dab32b36b497d54e8645e969aa79737ad3523ab))
 * **18-02:** wire batch track-details to all 4 view context menus ([656985a](https://github.com/onion-4-dinner/yellowjacket/commit/656985add92663440baebb871f8cd6d5723117fd))
 * **19-01:** implement WAV RIFF parser/writer and writeWavTags ([e6610ff](https://github.com/onion-4-dinner/yellowjacket/commit/e6610ff15e041213b6898ad48ff63b7060b312e7))
 * **20-01:** implement OGG Vorbis tag writer with custom page parser and CRC32 ([5e98c03](https://github.com/onion-4-dinner/yellowjacket/commit/5e98c036342b9e174abdc6d00db21c2e2901f18b))
 * **quick-17:** create playlist-details subpage component ([dc5c7d6](https://github.com/onion-4-dinner/yellowjacket/commit/dc5c7d6ca6cfbfac15546c048f1b33aaf47209c6))
 * **quick-18:** replace track-info with multi-column grid layout in playlist-details ([ce23177](https://github.com/onion-4-dinner/yellowjacket/commit/ce2317722870f932792dc6456a63235ff4611466))
-Every release there is generated from the Conventional Commits it
+### Bug Fixes
 contains, by `.gitea/workflows/release.yml`. Each one carries its notes
 as its body, grouped by change type, with a link to the commit behind
 every line.
-That workflow is **run by hand**, so a release holds everything merged
+* **09-05:** emit VolumeChanged event and persist state in ChangeVolume and MuteToggle ([bb3fd20](https://github.com/onion-4-dinner/yellowjacket/commit/bb3fd204f0895f357a14479b40754f397aae74c4))
-since the last one rather than one PR's worth. It used to fire on every
+* **10-01:** move library_id index to migration 6 to fix existing DB startup ([75b2a34](https://github.com/onion-4-dinner/yellowjacket/commit/75b2a349ebd6fada5cbc92bfae9854cc2cd53c63))
-push to `main`, which made a version per merged PR (issue #115).
+* **12-02:** claim orphaned tracks when adding library with matching path ([f60b6b5](https://github.com/onion-4-dinner/yellowjacket/commit/f60b6b525546ef77a3329fe92f03f336b7435a0e))
 * **12-02:** count failed saves as skipped so scan progress bar advances ([b36e472](https://github.com/onion-4-dinner/yellowjacket/commit/b36e472212957ff089f4f5d35f3978a754e23502))
 * **12-02:** delete artist_credit_artist before artist_credit in removal pipeline ([890284d](https://github.com/onion-4-dinner/yellowjacket/commit/890284ddb1d0fb95e423bddf27b40fb0db2d11e5))
 * **12-02:** dismiss inline rename on click outside ([9272b06](https://github.com/onion-4-dinner/yellowjacket/commit/9272b060bf98118e37f19a8c0834034691bfe6a2))
 * **12-02:** downgrade per-file save error to Debug, add warning count to scan summary ([cf18c39](https://github.com/onion-4-dinner/yellowjacket/commit/cf18c39dbd849d60218228cf1d2285ab2071e788))
 * **12-02:** invalidate library store cache on LibraryRemoved event ([b093fbb](https://github.com/onion-4-dinner/yellowjacket/commit/b093fbb10a24054c4ef62b0bd13f28d9bfe6f121))
 * **12-02:** keep Add Library button visible during scan ([649e516](https://github.com/onion-4-dinner/yellowjacket/commit/649e516aa30090665e9f10e89c1ccce378e36b96))
 * **12-02:** move Add Library button inline with scan buttons ([771345d](https://github.com/onion-4-dinner/yellowjacket/commit/771345dd9d3870b3a907e1cce09c7456ab7ccd85))
 * **12-02:** move scan buttons above library list, default to none selected ([ba3f840](https://github.com/onion-4-dinner/yellowjacket/commit/ba3f840a28fe2c6ca40c558305814d29c233d6e0))
 * **12-02:** refresh library track counts after scan completes ([1f872aa](https://github.com/onion-4-dinner/yellowjacket/commit/1f872aa005a9405d9bc1f64a4b1dd2f1f1d4a16c))
 * **12-02:** reorder orphan cleanup to delete FK children before recordings ([1d735c3](https://github.com/onion-4-dinner/yellowjacket/commit/1d735c3a5f5a78996d6ddbe5c787adf040fe2f21))
 * **12-02:** replace removed Scan() import with ScanAllLibraries() ([0559822](https://github.com/onion-4-dinner/yellowjacket/commit/05598224e4d5532d2e2a3a7e5d3b5411240b1024))
 * **12-02:** resolve phantom tracks caused by empty library root after TOML cleanup ([717e249](https://github.com/onion-4-dinner/yellowjacket/commit/717e249c368fd1cc8d5c8f945c352175708691cf))
 * **12-02:** serialize ScanWarning.Err as string instead of error interface ([ac8cbb3](https://github.com/onion-4-dinner/yellowjacket/commit/ac8cbb3296bd561a305627668c211dce7209df25))
 * **12-02:** soft scan claims orphaned library_id=0 tracks on startup ([1ad099a](https://github.com/onion-4-dinner/yellowjacket/commit/1ad099a9d35fc722475e238d3443fd5473566acd))
 * **12-02:** soft scan on launch — only scan libraries with changed file counts ([92c4d23](https://github.com/onion-4-dinner/yellowjacket/commit/92c4d23a9a1e545fab497816ee3dce43a181cded))
 * **12-02:** wait for scan to stop before library removal, surface errors in UI ([cf00498](https://github.com/onion-4-dinner/yellowjacket/commit/cf004986c95732d00208e83467267904ea3f2ef6))
 * **13-02:** auto-resolve phantom playlist tracks after library scan ([93262b9](https://github.com/onion-4-dinner/yellowjacket/commit/93262b9ae0f737d2893839ac585776207b3b44b6))
 * **13-02:** defer virtualizer event delegation until element exists ([f05d2bb](https://github.com/onion-4-dinner/yellowjacket/commit/f05d2bb603f5ea827164466fd0795a6c6e662529))
 * **13-02:** resolve phantom playlist tracks using M3U8 paths after scan ([9f595b7](https://github.com/onion-4-dinner/yellowjacket/commit/9f595b7ac10c2191b5469004901cbbc1331c1abb))
 * **14-01:** downgrade main-panel from contain:strict to layout+style+paint ([4b7d35d](https://github.com/onion-4-dinner/yellowjacket/commit/4b7d35d7ec4c8b14453a8f8250cd154b8c4c2537))
 * **14-perf:** fix scroll jumping and input latency ([3b2e189](https://github.com/onion-4-dinner/yellowjacket/commit/3b2e189e7d0e6d00393d087565190fd307774257))
 * **17-02:** fix cover art replace and remove ([d7c2965](https://github.com/onion-4-dinner/yellowjacket/commit/d7c2965752ae0ac9009d00f2431d5919a24558b7))
 * **17-02:** handle float64 numeric values from Wails JSON deserialization ([900db2e](https://github.com/onion-4-dinner/yellowjacket/commit/900db2e56cca254873a3a5a7a384008feac4211b))
 * **17-02:** refresh cover art URLs after save ([8cd4914](https://github.com/onion-4-dinner/yellowjacket/commit/8cd4914842f61c0c6b49e0216c7816e201a3c94a))
 * **17-02:** refresh track-details dialog data after successful save ([ffcdc41](https://github.com/onion-4-dinner/yellowjacket/commit/ffcdc41b0d4fad8ed428dbaa55f6cdd38c096822))
 * **18-02:** add field labels above title/artist/album inputs in batch edit mode ([9df2d67](https://github.com/onion-4-dinner/yellowjacket/commit/9df2d6764a0b0566dda33cff675debea4a61dea8))
 * **18-02:** add field labels to all track-details states (single/batch, read/edit) ([d430ad8](https://github.com/onion-4-dinner/yellowjacket/commit/d430ad884bfd38bea93389d8be730ff00388a7be))
 * **19-01:** add album_artist TPE2 mapping to applyTextChanges ([8f4c4a0](https://github.com/onion-4-dinner/yellowjacket/commit/8f4c4a0c2b14eeeaeccb972a40addb11f3d65437))
 * preserve scroll position in cached grid views ([54df917](https://github.com/onion-4-dinner/yellowjacket/commit/54df917ffdd69c4f7ffaeccf2d161261ca80d84e))
 * **queue-panel:** set flow layout _itemSize to match actual track item height ([288d9de](https://github.com/onion-4-dinner/yellowjacket/commit/288d9deae22d437fcd7857b368827db7b62c24f6))
 * **queue-panel:** suppress virtualizer scroll corrections during scrollbar drag ([0bd8cef](https://github.com/onion-4-dinner/yellowjacket/commit/0bd8cefa00dcae2f8bd9579de2aefd58e0a9e6c9))
 * **quick-19:** multi-root path resolution for playlist M3U8 tracks ([9144ded](https://github.com/onion-4-dinner/yellowjacket/commit/9144dedc2742925dc252d491763b4f2929238d0e))
 * **S21/T01:** fix all lint warnings and upgrade wsl to wsl_v5 ([f16157a](https://github.com/onion-4-dinner/yellowjacket/commit/f16157a2134cbeb1787ff851d4875d77f2f3f86b))
-**This file is not generated and is not a copy of that.** `main` is a
+### Performance
 protected branch, so nothing pushes a changelog commit back to it — and a
 file that claimed to be a changelog while silently never updating would
 be worse than no file at all. `make release-dry` prints what a release
 run would cut right now, and the workflow's own `dry_run` input answers
 the same question from CI.
-History before `v0.0.1` is in `git log`. The versions before it were cut
+* **12-02:** increase scan batch size from 50 to 300 ([21ea71e](https://github.com/onion-4-dinner/yellowjacket/commit/21ea71e2575d76258bd81d89ab8ac883aa3bed36))
-by hand and are not on the releases page; the entries this file used to
+* **12-02:** skip FTS5 rebuild during library removal ([30f4461](https://github.com/onion-4-dinner/yellowjacket/commit/30f4461e6957e20d3dc607fa0886a75b5c21b3cf))
-hold were generated against a GitHub remote this project no longer has,
+* **14-01:** add CSS containment to app shell layout boundaries ([efa06f7](https://github.com/onion-4-dinner/yellowjacket/commit/efa06f7edf1e4acdc3d8865cad264403257ae40d))
-and every link in them was dead.
+* **14-01:** add GPU promotion and containment to all scroll containers ([ac8a52e](https://github.com/onion-4-dinner/yellowjacket/commit/ac8a52e110f9f8ebdc3433b60594370352126a18))
 * **14-02:** replace innerHTML navigation with view caching system ([ad91043](https://github.com/onion-4-dinner/yellowjacket/commit/ad9104374a628342e0ea30cf409ff43de2c2f86e))
 * **14-03:** add notification batching to queue store and granular change tracking to library store ([d0c05dc](https://github.com/onion-4-dinner/yellowjacket/commit/d0c05dc1d43a4fe12cc07f3cff25375b08a74ba0))
 * **14-03:** eliminate per-item closure allocation in scroll render paths ([2f7ed70](https://github.com/onion-4-dinner/yellowjacket/commit/2f7ed7030425ed0ebb7a1a186917a79a7b26b850))
 * **14-04:** RAF-throttle scroll position saves and add overflow-anchor to queue panel ([6ca0b3c](https://github.com/onion-4-dinner/yellowjacket/commit/6ca0b3c5a84769af064ebe45a6eaac014d1a270a))
 * auto-detect NVIDIA+Wayland for DMABuf workaround ([915591a](https://github.com/onion-4-dinner/yellowjacket/commit/915591aea962beb60da2e96ac0f57307f646f675))
 * inline SVGs, memoize grid slices, batch store notifications ([a4eac39](https://github.com/onion-4-dinner/yellowjacket/commit/a4eac394cebefd29d0ebcb4b1e331444dcb8fbaf))
 * reduce software rendering overhead for NVIDIA+Wayland ([199c910](https://github.com/onion-4-dinner/yellowjacket/commit/199c91013fd806f6aefce49357df8a32b46faaa0))
 ### Refactoring
 * **quick-17:** simplify playlist-view to navigate instead of expand ([955cd68](https://github.com/onion-4-dinner/yellowjacket/commit/955cd68be2dbf7a9071ef1c93084d687b59b6bd7))
 ## [1.2.2](https://github.com/onion-4-dinner/yellowjacket/compare/v1.2.1...v1.2.2) (2026-03-06)
 ### Bug Fixes
 * recover from go-mp3 seek panic on startup ([#86](https://github.com/onion-4-dinner/yellowjacket/issues/86)) ([2f9d9f8](https://github.com/onion-4-dinner/yellowjacket/commit/2f9d9f8508b90b6188fe894c282c5b8e330e8046))
 ## [1.2.1](https://github.com/onion-4-dinner/yellowjacket/compare/v1.2.0...v1.2.1) (2026-03-06)
 ### Bug Fixes
 * **deps:** pin go-webview2 to v1.0.21 for Wails v2 compat ([25f0fe8](https://github.com/onion-4-dinner/yellowjacket/commit/25f0fe81560eeff36a0b2beb52ce1bdf13d5e122))
 ## [1.2.0](https://github.com/onion-4-dinner/yellowjacket/compare/v1.1.3...v1.2.0) (2026-03-06)
 ### Features
 * **02-02:** add ScanWarning type and reclassify scan errors as warnings ([e6866de](https://github.com/onion-4-dinner/yellowjacket/commit/e6866ded9dc0ea30ff942cd31b6c5ea3269e9584))
 * **03-01:** create NewTestDB helper for in-memory SQLite test databases ([bae9d70](https://github.com/onion-4-dinner/yellowjacket/commit/bae9d70d23157ef4e79e60dd713d9a02ab63790b))
 * **03-01:** extract shared applyPRAGMAs and add production PRAGMAs to NewDB ([d348815](https://github.com/onion-4-dinner/yellowjacket/commit/d34881530adda7fb75be84737798da46d17bfa8c))
 * **06-01:** create track_metadata VIEW schema and migration 4 ([9c7e5a9](https://github.com/onion-4-dinner/yellowjacket/commit/9c7e5a96344a81bf132de487b4763f1dc3ff6df9))
 * **06-02:** create Go→TypeScript event constant codegen tool ([3e9edd0](https://github.com/onion-4-dinner/yellowjacket/commit/3e9edd05e87395499ac24e456640d1f6d9b97f04))
 * **06-03:** migrate lookupChunk to sqlc-generated LookupTrackMetaByPaths query ([2221a68](https://github.com/onion-4-dinner/yellowjacket/commit/2221a68459850a837c996c6e6d2bc95d41b20fb3))
 * **08-01:** define design token CSS custom properties for icon sizes and type scale ([1444a66](https://github.com/onion-4-dinner/yellowjacket/commit/1444a66bb201ce5fdf16552a32bcd281089c64ed))
 * **08-04:** apply design tokens to cover-grid, track-list, queue-panel, and detail components ([1303422](https://github.com/onion-4-dinner/yellowjacket/commit/1303422e69c27d528363900b3ca5287a48cc9f8e))
 * **08-04:** convert sidebar em-based spacing to px and apply icon/type tokens ([aed90d7](https://github.com/onion-4-dinner/yellowjacket/commit/aed90d7b1710d0c5cece2e4956c0a6ce77b9a999))
 * add scan progress bar with phase indicator ([a28b4d1](https://github.com/onion-4-dinner/yellowjacket/commit/a28b4d1e0673658824750d4c702359321dc9a78e))
 * **quick-001:** add multi-file picker and batch import support ([c34e4ad](https://github.com/onion-4-dinner/yellowjacket/commit/c34e4ad029c119bff8f70a07ccc6bca58b11ea3c))
 * **quick-001:** regenerate bindings and update frontend for multi-import ([2a542bf](https://github.com/onion-4-dinner/yellowjacket/commit/2a542bf3bcdc7772edb1aceb41f488774494f656))
 * **quick-002:** add CountPlaylistsByName SQL query and regenerate sqlc ([04b2088](https://github.com/onion-4-dinner/yellowjacket/commit/04b2088b28b84a4d4df25b23d97112c5a955dff1))
 * **quick-002:** add uniquePlaylistName helper and wire into ImportPlaylist ([8ba8bbe](https://github.com/onion-4-dinner/yellowjacket/commit/8ba8bbe7bed2ecff97613ebaa42a49a662050353))
 * **quick-006:** remove list icon from playlists, add favorites icon to default ([3c19766](https://github.com/onion-4-dinner/yellowjacket/commit/3c19766fd0885d4171cf9929db6d69a3d5c1a3ff))
 * **quick-11:** add configurable log level via YJ_LOG_LEVEL env var ([55b4902](https://github.com/onion-4-dinner/yellowjacket/commit/55b4902fac7b7f2c04ad5efac398ecedc5fedc2f))
 * **quick-11:** add make dev-debug target for verbose logging ([c45bca4](https://github.com/onion-4-dinner/yellowjacket/commit/c45bca411ba1d4f32deea6027acf91237173dd15))
 * **quick-12:** add favorite icon to album dropdown track rows ([12a0bbc](https://github.com/onion-4-dinner/yellowjacket/commit/12a0bbc89c19128485d597a61bd16bd0786450ad))
 * **quick-15:** add BufferedStreamer with goroutine read-ahead ([85b23ac](https://github.com/onion-4-dinner/yellowjacket/commit/85b23acb24a048d2f7b85808e477bb991ae124e6))
 * **quick-15:** insert BufferedStreamer into player pipeline and increase speaker buffer ([8a0b16a](https://github.com/onion-4-dinner/yellowjacket/commit/8a0b16a4ec08a95bfd3834c8216e21dce854432d))
 * **quick-3:** add playlist-level multi-select state and selection handling ([e13151f](https://github.com/onion-4-dinner/yellowjacket/commit/e13151ffa5dc86e41ce242421679d65a740c3af0))
 * **quick-3:** wire playlist context menu for batch delete of selected playlists ([c92ced2](https://github.com/onion-4-dinner/yellowjacket/commit/c92ced2c74e72bfc123c880c047462dc969cde34))
 * **quick-4:** add 'Set as Default Playlist' context menu option ([9971b63](https://github.com/onion-4-dinner/yellowjacket/commit/9971b635b81fe3f8621c80a6664eccb3e1fc4bb8))
 * **quick-5:** add CreatedAt/UpdatedAt to playlist Summary struct ([bdaff47](https://github.com/onion-4-dinner/yellowjacket/commit/bdaff478e802ee5c0745327c52dd9b190fcfef7d))
 * **quick-5:** add sort dropdown UI and client-side sorting to playlist view ([5c07485](https://github.com/onion-4-dinner/yellowjacket/commit/5c074855351f1363cc7918837a78bbd3c0b7ebf5))
 * **quick-7:** add PinDefault config field with backend getter/setter ([6e123bd](https://github.com/onion-4-dinner/yellowjacket/commit/6e123bd47f55e6d565f20bf7f19950e65f80787f))
 * **quick-7:** wire frontend pin-default-playlist feature end-to-end ([e6378e1](https://github.com/onion-4-dinner/yellowjacket/commit/e6378e1f0d3b0f2a7604b8ef6097dba9050cdd16))
 * **quick-8:** add FindDuplicateTracksInPlaylist backend method ([83de934](https://github.com/onion-4-dinner/yellowjacket/commit/83de934c39ca7d850a8b5925c90e6d0b3fe0a487))
 * **quick-8:** create duplicate-tracks-dialog component ([9f3ba2b](https://github.com/onion-4-dinner/yellowjacket/commit/9f3ba2b9d474fa30dcb4934b01d4650e0d0d3cba))
 * **quick-8:** wire duplicate detection into playlist-picker and playlist-view ([917a79a](https://github.com/onion-4-dinner/yellowjacket/commit/917a79a8d6e30dddd2170323bb26692386794872))
 ### Bug Fixes
 * **01-01:** add mutex protection to Queue, Library, and Playlist SetContext methods ([daaa6b7](https://github.com/onion-4-dinner/yellowjacket/commit/daaa6b7f9779385979fe9dddae4e7bb388b3e5fb))
 * **01-01:** collapse Player.SetContext double-lock into single acquisition ([3abaeba](https://github.com/onion-4-dinner/yellowjacket/commit/3abaeba3afb0f4d0edb81e26ca55b31bf59990ac))
 * **02-01:** eliminate package-level startupErr and fix config file permissions ([2a86408](https://github.com/onion-4-dinner/yellowjacket/commit/2a864082017e489ffa086c136f1002277a77a7c4))
 * **02-01:** log MPRIS callback errors instead of discarding them ([0860b2f](https://github.com/onion-4-dinner/yellowjacket/commit/0860b2fd4b2250da1eeb80c21f14fdf341697501))
 * **08-02:** revert repeat() inside lit-virtualizer, restore .renderItem + .keyFunction ([72ef719](https://github.com/onion-4-dinner/yellowjacket/commit/72ef719ba70eeca0fa4bae47df092706f6fbaeed))
 * drop+recreate contentless FTS5 index instead of DELETE ([8e9a616](https://github.com/onion-4-dinner/yellowjacket/commit/8e9a61603779eacbee7013b9bc760b315baf782a))
 * **frontend:** reposition search indicator into toolbar and fix album cover art lookup ([a29137b](https://github.com/onion-4-dinner/yellowjacket/commit/a29137b2ba4c6b33ce9a5f868cbd6013e0e3b116))
 * include full track metadata in GetAudioFilesByReleaseGroup query ([97f256d](https://github.com/onion-4-dinner/yellowjacket/commit/97f256d67f463d752f7adc5b400c4bf34eae1df1))
 * **quick-10:** add migration 5 and fix entity cache for composite album key ([d43ba7b](https://github.com/onion-4-dinner/yellowjacket/commit/d43ba7bd0c7ace2a9ed71990a19498f8e9f90751))
 * **quick-10:** update release_groups schema and queries for composite uniqueness ([999ab96](https://github.com/onion-4-dinner/yellowjacket/commit/999ab967beb9107a3f30ba287acbffad22f0b0de))
 * **quick-13:** resolve lint issues in main source files ([e1a95e6](https://github.com/onion-4-dinner/yellowjacket/commit/e1a95e65a9f0f436b2e2d92befa9c881b6e8e430))
 * **quick-14:** add roll-back-on-failure to queue index advancement ([2820de2](https://github.com/onion-4-dinner/yellowjacket/commit/2820de2510560fcd6d1015c18542d5ac30468247))
 * **quick-9:** set fixed height on queue track items for stable virtualizer scroll ([ebde5e5](https://github.com/onion-4-dinner/yellowjacket/commit/ebde5e5a8bc4da8f40bef8f171c7ed86c213a336))
 ### Performance
 * **07-01:** add incremental persistence helpers for queue mutations ([cdd17db](https://github.com/onion-4-dinner/yellowjacket/commit/cdd17db27509908514c21517631306655a2b3bd7))
 * **07-01:** eliminate redundant lookups in SetQueue Phase 2 ([ced58fe](https://github.com/onion-4-dinner/yellowjacket/commit/ced58fe6a93d6f220137562b8ff09ffc33c69266))
 * **07-02:** defer eagerFetch to after DOM ready for instant app shell ([cd98ad6](https://github.com/onion-4-dinner/yellowjacket/commit/cd98ad6dc8c2e4e6e0f01a48099b0c0511bf5a98))
 * **08-01:** add queueMicrotask coalescing to library store and debounce search input ([3bf66ed](https://github.com/onion-4-dinner/yellowjacket/commit/3bf66ed125ed55bfbde95b0bc973710c2f2243b8))
 * **08-02:** migrate cover-grid, artists-view, and genres-view virtualizers to repeat() directive ([1c3514d](https://github.com/onion-4-dinner/yellowjacket/commit/1c3514da1d0491b9758d7a6f9f72d59ef78fc8ed))
 * **08-02:** migrate track-list and queue-panel virtualizers to repeat() directive ([d2d7d8c](https://github.com/onion-4-dinner/yellowjacket/commit/d2d7d8c6ce22923772cae4858b02804d15f74bb7))
 * **08-03:** optimize column rendering and apply classMap to queue-panel renderTrackItem ([62f41c2](https://github.com/onion-4-dinner/yellowjacket/commit/62f41c24910632b270f9f5765e20e48db4b95ec9))
 * **08-03:** replace class string construction with classMap directive in renderTrackRow ([ad21027](https://github.com/onion-4-dinner/yellowjacket/commit/ad210278fc20729dc76390e6bba9bff050549046))
 ### Refactoring
 * **06-01:** consolidate search queries to use track_metadata VIEW ([9159b40](https://github.com/onion-4-dinner/yellowjacket/commit/9159b409dcd2afaa7dcc97bf5b0694edf85f06a4))
 * **quick-14:** make playOrLoadCurrentTrack and playCurrentTrack return bool ([6eeddda](https://github.com/onion-4-dinner/yellowjacket/commit/6eeddda97669258cc5b7ba175a3c98d598a2871f))
 ## [1.1.3](https://github.com/onion-4-dinner/yellowjacket/compare/v1.1.2...v1.1.3) (2026-02-21)
 ### Bug Fixes
 * add typescript as explicit devDependency and auto-install frontend deps in setup ([#70](https://github.com/onion-4-dinner/yellowjacket/issues/70)) ([7316587](https://github.com/onion-4-dinner/yellowjacket/commit/73165877fa79656ab9bc6f60bd8e9e52d6be206c))
 * use local tsc binary in pre-commit hook to avoid PATH issues ([#71](https://github.com/onion-4-dinner/yellowjacket/issues/71)) ([6079e55](https://github.com/onion-4-dinner/yellowjacket/commit/6079e558ff913d38c7f1c4aeb52cc09474c4ed20))
 ## [1.1.2](https://github.com/onion-4-dinner/yellowjacket/compare/v1.1.1...v1.1.2) (2026-02-15)
 ### Bug Fixes
 * r2 upload ([#69](https://github.com/onion-4-dinner/yellowjacket/issues/69)) ([0252466](https://github.com/onion-4-dinner/yellowjacket/commit/0252466f615b4e2fd9694790c6d311a9eac1ccf2))
 ## [1.1.1](https://github.com/onion-4-dinner/yellowjacket/compare/v1.1.0...v1.1.1) (2026-02-15)
 ### Bug Fixes
 * **ci:** remove build-check job from CI workflow ([#66](https://github.com/onion-4-dinner/yellowjacket/issues/66)) ([42d3f45](https://github.com/onion-4-dinner/yellowjacket/commit/42d3f45d85afa694e9545997af3ff4ac814ad021))
 ## [1.1.0](https://github.com/onion-4-dinner/yellowjacket/compare/v1.0.3...v1.1.0) (2026-02-15)
 ### Features
 * **ci:** upload release artifacts to Cloudflare R2 ([#65](https://github.com/onion-4-dinner/yellowjacket/issues/65)) ([8985084](https://github.com/onion-4-dinner/yellowjacket/commit/89850848cbf7783e5c85348ff18f7cd11d60231a))
 ## [1.0.3](https://github.com/onion-4-dinner/yellowjacket/compare/v1.0.2...v1.0.3) (2026-02-15)
 ### ⚠ BREAKING CHANGES
 * **deps:** update module github.com/evilmartians/lefthook to v2 (#61)
 * **deps:** update actions/checkout action to v6 (#45)
 * **deps:** update dependency vite to v7 (#53)
 ### Bug Fixes
 * resolve all lint errors and make linting a required CI check ([#62](https://github.com/onion-4-dinner/yellowjacket/issues/62)) ([30b2480](https://github.com/onion-4-dinner/yellowjacket/commit/30b2480df49f57878b0e8c923da6ad8d6fe99416))
 * virtual list and cover grid ([#63](https://github.com/onion-4-dinner/yellowjacket/issues/63)) ([7579a76](https://github.com/onion-4-dinner/yellowjacket/commit/7579a768be84225ed46db4e7a90781f3e30e2953))
 ### Miscellaneous
 * **deps:** update actions/checkout action to v6 ([#45](https://github.com/onion-4-dinner/yellowjacket/issues/45)) ([2d6e221](https://github.com/onion-4-dinner/yellowjacket/commit/2d6e22105d2daed1dc5b586c0442e2941949a165))
 * **deps:** update dependency vite to v7 ([#53](https://github.com/onion-4-dinner/yellowjacket/issues/53)) ([f0006c4](https://github.com/onion-4-dinner/yellowjacket/commit/f0006c4c4335b60b58cccdd29de4792965e39694))
 * **deps:** update module github.com/evilmartians/lefthook to v2 ([#61](https://github.com/onion-4-dinner/yellowjacket/issues/61)) ([e32b217](https://github.com/onion-4-dinner/yellowjacket/commit/e32b2179129ae7f26037697a125710ff7587566d))
 ## [1.0.2](https://github.com/onion-4-dinner/yellowjacket/compare/v1.0.1...v1.0.2) (2026-02-14)
 ### ⚠ BREAKING CHANGES
 * **deps:** update actions/setup-node action to v6 (#48)
 * **deps:** update dependency stylelint-config-standard to v40 (#52)
 * **deps:** update dependency node to v24 (#51)
 * **deps:** update dependency vite-plugin-static-copy to v3 (#54)
 * **deps:** update golangci/golangci-lint-action action to v9 (#55)
 * **deps:** update amannn/action-semantic-pull-request action to v6 (#50)
 * **deps:** update actions/upload-artifact action to v6 (#49)
 * **deps:** update actions/setup-go action to v6 (#47)
 * **deps:** update actions/download-artifact action to v7 (#46)
 ### Bug Fixes
 * **ci:** use allowedPostUpgradeCommands for Renovate post-upgrade tasks ([#60](https://github.com/onion-4-dinner/yellowjacket/issues/60)) ([0aef483](https://github.com/onion-4-dinner/yellowjacket/commit/0aef483b3cccd0616fd5be2d06d0856b46851d09))
 ### Miscellaneous
 * **deps:** update actions/download-artifact action to v7 ([#46](https://github.com/onion-4-dinner/yellowjacket/issues/46)) ([1910f99](https://github.com/onion-4-dinner/yellowjacket/commit/1910f99cf64e9bdc5ce91e89cab254ecca15d030))
 * **deps:** update actions/setup-go action to v6 ([#47](https://github.com/onion-4-dinner/yellowjacket/issues/47)) ([8911fb2](https://github.com/onion-4-dinner/yellowjacket/commit/8911fb2400047cf2f3dfa719edc1d1bf474cdaa5))
 * **deps:** update actions/setup-node action to v6 ([#48](https://github.com/onion-4-dinner/yellowjacket/issues/48)) ([d7382fd](https://github.com/onion-4-dinner/yellowjacket/commit/d7382fd8444b6618dbfe991f5f97231528a07f13))
 * **deps:** update actions/upload-artifact action to v6 ([#49](https://github.com/onion-4-dinner/yellowjacket/issues/49)) ([a2c644b](https://github.com/onion-4-dinner/yellowjacket/commit/a2c644b00eed83acc0ed38a2eb8c73868b7b79af))
 * **deps:** update amannn/action-semantic-pull-request action to v6 ([#50](https://github.com/onion-4-dinner/yellowjacket/issues/50)) ([643ba27](https://github.com/onion-4-dinner/yellowjacket/commit/643ba27f066164aeb47e8d9aaf20fe98b9b69d30))
 * **deps:** update dependency node to v24 ([#51](https://github.com/onion-4-dinner/yellowjacket/issues/51)) ([e7d3971](https://github.com/onion-4-dinner/yellowjacket/commit/e7d39711078ce86b0c029f0d03ff81162c5dc28a))
 * **deps:** update dependency stylelint-config-standard to v40 ([#52](https://github.com/onion-4-dinner/yellowjacket/issues/52)) ([422aabc](https://github.com/onion-4-dinner/yellowjacket/commit/422aabcc07e9700ff189302b363e13d87c69163a))
 * **deps:** update dependency vite-plugin-static-copy to v3 ([#54](https://github.com/onion-4-dinner/yellowjacket/issues/54)) ([77fa643](https://github.com/onion-4-dinner/yellowjacket/commit/77fa6435a5298f58ef83607d99c59b876132c66c))
 * **deps:** update golangci/golangci-lint-action action to v9 ([#55](https://github.com/onion-4-dinner/yellowjacket/issues/55)) ([aedb7d1](https://github.com/onion-4-dinner/yellowjacket/commit/aedb7d1e6d204c56c468dd26b340752fd6bfeaeb))
 ## [1.0.1](https://github.com/onion-4-dinner/yellowjacket/compare/v1.0.0...v1.0.1) (2026-02-14)
 ### Bug Fixes
 * resolve Renovate repo detection and pre-push hook hang ([#36](https://github.com/onion-4-dinner/yellowjacket/issues/36)) ([b205889](https://github.com/onion-4-dinner/yellowjacket/commit/b205889128f01e9eb75b607cf7c4034887cda3f4))
 ## 1.0.0 (2026-02-14)
 ### Features
 * **ci:** add semantic-release pipeline, cross-platform builds, and lefthook git hooks ([caf3e84](https://github.com/onion-4-dinner/yellowjacket/commit/caf3e843af7da37e05da36da5c41b6dc3c53ded1))
 ### Bug Fixes
 * allow library to initialize without config and fix lefthook lint flag ([5a958db](https://github.com/onion-4-dinner/yellowjacket/commit/5a958db16284a74e19c43259757b163b347cda7d))
 * **ci:** configure git credentials explicitly for semantic-release PAT ([24f21af](https://github.com/onion-4-dinner/yellowjacket/commit/24f21af8350227e77fc1fef9243c238e6417aca0))
 * **ci:** fix golangci-lint version, skip player test in CI, remove standalone frontend build ([7317e09](https://github.com/onion-4-dinner/yellowjacket/commit/7317e093a7f92651ab65b2f83381d02105bdc0df))
 * **ci:** resolve CI failures for Go checks, codegen, and frontend type-checking ([d4f9361](https://github.com/onion-4-dinner/yellowjacket/commit/d4f936143ac75fbf3247cdbe2113bd89b0795d83))
 * **ci:** use PAT for semantic-release to trigger build workflow ([68d41c0](https://github.com/onion-4-dinner/yellowjacket/commit/68d41c0ff22fede57acab7a2bfed42df7814bb90))
 * rename downloaded artifacts to platform-specific names for release ([e3bda0e](https://github.com/onion-4-dinner/yellowjacket/commit/e3bda0e2fc7700fad382cabe00aeb46f91fbb0a0))
 * resolve frontend build failures in CI ([330a53c](https://github.com/onion-4-dinner/yellowjacket/commit/330a53c9f4b1292840ad0f75479b76b3d429c954))
 * trigger build workflow from release event instead of tag push ([47772f7](https://github.com/onion-4-dinner/yellowjacket/commit/47772f73cc04093c55414bf20ebe2ef442418d19))
 * use path.Join for embed.FS paths to fix Windows build ([672fe24](https://github.com/onion-4-dinner/yellowjacket/commit/672fe24ee99debf4a394fff7eec55f17b0e44476))
 ## 1.0.0 (2026-02-14)
 ### Features
 * **ci:** add semantic-release pipeline, cross-platform builds, and lefthook git hooks ([caf3e84](https://github.com/onion-4-dinner/yellowjacket/commit/caf3e843af7da37e05da36da5c41b6dc3c53ded1))
 ### Bug Fixes
 * allow library to initialize without config and fix lefthook lint flag ([5a958db](https://github.com/onion-4-dinner/yellowjacket/commit/5a958db16284a74e19c43259757b163b347cda7d))
 * **ci:** configure git credentials explicitly for semantic-release PAT ([24f21af](https://github.com/onion-4-dinner/yellowjacket/commit/24f21af8350227e77fc1fef9243c238e6417aca0))
 * **ci:** fix golangci-lint version, skip player test in CI, remove standalone frontend build ([7317e09](https://github.com/onion-4-dinner/yellowjacket/commit/7317e093a7f92651ab65b2f83381d02105bdc0df))
 * **ci:** resolve CI failures for Go checks, codegen, and frontend type-checking ([d4f9361](https://github.com/onion-4-dinner/yellowjacket/commit/d4f936143ac75fbf3247cdbe2113bd89b0795d83))
 * **ci:** use PAT for semantic-release to trigger build workflow ([68d41c0](https://github.com/onion-4-dinner/yellowjacket/commit/68d41c0ff22fede57acab7a2bfed42df7814bb90))
 * resolve frontend build failures in CI ([330a53c](https://github.com/onion-4-dinner/yellowjacket/commit/330a53c9f4b1292840ad0f75479b76b3d429c954))
 * trigger build workflow from release event instead of tag push ([47772f7](https://github.com/onion-4-dinner/yellowjacket/commit/47772f73cc04093c55414bf20ebe2ef442418d19))
 * use path.Join for embed.FS paths to fix Windows build ([672fe24](https://github.com/onion-4-dinner/yellowjacket/commit/672fe24ee99debf4a394fff7eec55f17b0e44476))
 ## [1.0.3](https://github.com/onion-4-dinner/yellowjacket/compare/v1.0.2...v1.0.3) (2026-02-14)
 ### Bug Fixes
 * use path.Join for embed.FS paths to fix Windows build ([672fe24](https://github.com/onion-4-dinner/yellowjacket/commit/672fe24ee99debf4a394fff7eec55f17b0e44476))
 ## [1.0.2](https://github.com/onion-4-dinner/yellowjacket/compare/v1.0.1...v1.0.2) (2026-02-14)
 ### Bug Fixes
 * resolve frontend build failures in CI ([330a53c](https://github.com/onion-4-dinner/yellowjacket/commit/330a53c9f4b1292840ad0f75479b76b3d429c954))
 ## [1.0.1](https://github.com/onion-4-dinner/yellowjacket/compare/v1.0.0...v1.0.1) (2026-02-14)
 ### Bug Fixes
 * allow library to initialize without config and fix lefthook lint flag ([5a958db](https://github.com/onion-4-dinner/yellowjacket/commit/5a958db16284a74e19c43259757b163b347cda7d))
 ## 1.0.0 (2026-02-14)
 ### Features
 * **ci:** add semantic-release pipeline, cross-platform builds, and lefthook git hooks ([caf3e84](https://github.com/onion-4-dinner/yellowjacket/commit/caf3e843af7da37e05da36da5c41b6dc3c53ded1))
 ### Bug Fixes
 * **ci:** configure git credentials explicitly for semantic-release PAT ([24f21af](https://github.com/onion-4-dinner/yellowjacket/commit/24f21af8350227e77fc1fef9243c238e6417aca0))
 * **ci:** fix golangci-lint version, skip player test in CI, remove standalone frontend build ([7317e09](https://github.com/onion-4-dinner/yellowjacket/commit/7317e093a7f92651ab65b2f83381d02105bdc0df))
 * **ci:** resolve CI failures for Go checks, codegen, and frontend type-checking ([d4f9361](https://github.com/onion-4-dinner/yellowjacket/commit/d4f936143ac75fbf3247cdbe2113bd89b0795d83))
 * **ci:** use PAT for semantic-release to trigger build workflow ([68d41c0](https://github.com/onion-4-dinner/yellowjacket/commit/68d41c0ff22fede57acab7a2bfed42df7814bb90))
 ## [1.0.2](https://github.com/onion-4-dinner/yellowjacket/compare/v1.0.1...v1.0.2) (2026-02-14)
 ### Bug Fixes
 * **ci:** fix golangci-lint version, skip player test in CI, remove standalone frontend build ([7317e09](https://github.com/onion-4-dinner/yellowjacket/commit/7317e093a7f92651ab65b2f83381d02105bdc0df))
 ## [1.0.1](https://github.com/onion-4-dinner/yellowjacket/compare/v1.0.0...v1.0.1) (2026-02-14)
 ### Bug Fixes
 * **ci:** resolve CI failures for Go checks, codegen, and frontend type-checking ([d4f9361](https://github.com/onion-4-dinner/yellowjacket/commit/d4f936143ac75fbf3247cdbe2113bd89b0795d83))
 ## 1.0.0 (2026-02-14)
 ### Features
 * **ci:** add semantic-release pipeline, cross-platform builds, and lefthook git hooks ([caf3e84](https://github.com/onion-4-dinner/yellowjacket/commit/caf3e843af7da37e05da36da5c41b6dc3c53ded1))
 ### Bug Fixes
 * **ci:** configure git credentials explicitly for semantic-release PAT ([24f21af](https://github.com/onion-4-dinner/yellowjacket/commit/24f21af8350227e77fc1fef9243c238e6417aca0))
 * **ci:** use PAT for semantic-release to trigger build workflow ([68d41c0](https://github.com/onion-4-dinner/yellowjacket/commit/68d41c0ff22fede57acab7a2bfed42df7814bb90))
 ## 1.0.0 (2026-02-14)
 ### Features
 * **ci:** add semantic-release pipeline, cross-platform builds, and lefthook git hooks ([caf3e84](https://github.com/onion-4-dinner/yellowjacket/commit/caf3e843af7da37e05da36da5c41b6dc3c53ded1))
 ### Bug Fixes
 * **ci:** configure git credentials explicitly for semantic-release PAT ([24f21af](https://github.com/onion-4-dinner/yellowjacket/commit/24f21af8350227e77fc1fef9243c238e6417aca0))
 * **ci:** use PAT for semantic-release to trigger build workflow ([68d41c0](https://github.com/onion-4-dinner/yellowjacket/commit/68d41c0ff22fede57acab7a2bfed42df7814bb90))
 ## 1.0.0 (2026-02-14)
 ### Features
 * **ci:** add semantic-release pipeline, cross-platform builds, and lefthook git hooks ([caf3e84](https://github.com/onion-4-dinner/yellowjacket/commit/caf3e843af7da37e05da36da5c41b6dc3c53ded1))
 ### Bug Fixes
 * **ci:** use PAT for semantic-release to trigger build workflow ([68d41c0](https://github.com/onion-4-dinner/yellowjacket/commit/68d41c0ff22fede57acab7a2bfed42df7814bb90))
 ## 1.0.0 (2026-02-14)
 ### Features
 * **ci:** add semantic-release pipeline, cross-platform builds, and lefthook git hooks ([caf3e84](https://github.com/onion-4-dinner/yellowjacket/commit/caf3e843af7da37e05da36da5c41b6dc3c53ded1))
@@ -179,12 +179,10 @@ bindings-check: ## Fail if the generated bindings are stale
 css-check: ## Fail if a css`` literal was ended early by a backtick in a comment
 	@cd frontend && node scripts/check-css-literals.mjs
-# .pi/ and CLAUDE.md document commands, and a doc that documents a
+# .pi/ documents commands, and a skill that documents a command wrongly
-# command wrongly is worse than no doc: an agent runs it confidently.
+# is worse than no skill: an agent runs it confidently.  Every command
-# Every command in them is a make target on purpose, so this is
+# in there is a make target on purpose, so this is checkable.
-# checkable.  It also asserts AGENTS.md is a symlink to CLAUDE.md, so the
+skill-check: ## Fail if .pi/ documents a make target that does not exist
 # two harnesses cannot drift onto two descriptions of one project.
 skill-check: ## Fail if the agent docs name a missing make target, or AGENTS.md is not a symlink
 	@./scripts/skill-check.sh
 # Conventional Commits, which CLAUDE.md claimed CI enforced for a long
@@ -192,30 +190,6 @@ skill-check: ## Fail if the agent docs name a missing make target, or AGENTS.md
 commit-check: ## Fail if a commit subject is not a Conventional Commit
 	@./scripts/commit-check.sh $(if $(RANGE),--range $(RANGE))
 # What running the release workflow now would ship, without shipping it.
 # Reads the same .releaserc.yml CI does, so "why did that not cut a
 # version" is answerable locally instead of by pushing and watching.
 # Needs no credentials: --dry-run neither tags nor publishes.
 #
 # release.yml is dispatch-only, so this answers the question that
 # actually gets asked now -- what has accumulated since the last tag --
 # rather than what one merge would have done.  The workflow's own
 # `dry_run` input is the same answer from the runner, against whatever
 # main points at rather than the working tree.
 #
 # The pins must stay identical to release.yml's, which is where the note
 # on holding the conventionalcommits preset at 9 lives -- at 10 the
 # release notes come out empty with everything green.
 release-dry: ## Print the version a release run would cut right now
 	@npx --yes \
 		-p semantic-release@25 \
 		-p @semantic-release/commit-analyzer@13 \
 		-p @semantic-release/release-notes-generator@14 \
 		-p @semantic-release/changelog@7 \
 		-p @semantic-release/exec@7 \
 		-p conventional-changelog-conventionalcommits@9 \
 		semantic-release --dry-run --no-ci
 # v3 generates TypeScript into frontend/bindings/, nested by Go import
 # path, rather than v2's frontend/wailsjs/.  The `@go` alias absorbs the
 # constant prefix, so a call site imports '@go/library/library.js'.
@@ -231,7 +205,7 @@ bindings: ## Regenerate frontend/bindings from the bound Go services
 	sandbox-seed sandbox-seed-bulk sandbox-seeds e2e e2e-setup e2e-report \
 	perf perf-compare \
 	ui-test ui-watch ui-visual ui-visual-update ui-setup \
-	bindings bindings-check skill-check commit-check release-dry
+	bindings bindings-check skill-check commit-check
 # Base directory for fresh-install sandboxes. Deliberately NOT $TMPDIR:
 # on most Linux distros /tmp is tmpfs (RAM-backed) and only a few GB, so
@@ -106,8 +106,5 @@ make dev          # run with hot-reload
 make build-prod   # produce a release binary
 ```
-More detail for contributors lives in [`CLAUDE.md`](./CLAUDE.md) — the
+More detail for contributors lives in
-architecture, the conventions and the reasons behind them. What is
+[`docs/dev/overview.md`](./docs/dev/overview.md) and [`CLAUDE.md`](./CLAUDE.md).
 being worked on is [the issue
 tracker](https://git.ljones.me/yonlu/yellowjacket/issues); #73 is the
 roadmap.
@@ -8,7 +8,6 @@ import (
 	"log/slog"
 	"yellowjacket/backend/database/sql/sqlcgen"
 	"yellowjacket/backend/tagtotals"
 )
 // TagChanges mirrors tagwriter.TagChanges — redefined here so the
@@ -29,8 +28,6 @@ const (
 	FieldYear        = "year"
 	FieldTrackNumber = "track_number"
 	FieldDiscNumber  = "disc_number"
 	FieldTotalTracks = "total_tracks"
 	FieldTotalDiscs  = "total_discs"
 	FieldCoverArt    = "cover_art"
 )
@@ -421,32 +418,5 @@ func buildChanges(
 		changes[FieldDiscNumber] = track.DiscNumber
 	}
 	// The totals are what says "2 of 10" rather than a bare tick, and
 	// dropping them here is what made autotagging an album *erase* the
 	// evidence: the release becomes MBID-matched while the field
 	// GetAlbumCompleteness reads stays absent.
 	//
 	// They are written unconditionally where the candidate has a
 	// tracklist, not only when they differ from the local value, because
 	// the common case is a file that declares no total at all -- which
 	// compares equal to nothing and would be skipped by a diff guard.
 	if tracks, discs := tagtotals.For(
 		candidatePositions(cand), track.DiscNumber,
 	); tracks > 0 {
 		changes[FieldTotalTracks] = tracks
 		changes[FieldTotalDiscs] = discs
 	}
 	return changes
 }
 // candidatePositions is the candidate's tracklist as bare positions.
 func candidatePositions(cand Candidate) []tagtotals.Position {
 	out := make([]tagtotals.Position, 0, len(cand.Tracks))
 	for _, t := range cand.Tracks {
 		out = append(out, tagtotals.Position{Disc: t.DiscNumber, Track: t.Position})
 	}
 	return out
 }
@@ -1,90 +0,0 @@
 package autotag
 import "testing"
 // Autotagging an album used to *erase* the evidence that says "2 of 10":
 // the release became MBID-matched while the totals the files declared
 // went unwritten, so the album page showed a plain tick.  These pin the
 // two halves of the fix that are easy to get wrong silently.
 func TestBuildChanges_Totals(t *testing.T) {
 	t.Parallel()
 	twoDiscs := Candidate{
 		Tracks: []CandidateTrack{
 			{DiscNumber: 1, Position: 1},
 			{DiscNumber: 1, Position: 2},
 			{DiscNumber: 2, Position: 1},
 			{DiscNumber: 2, Position: 2},
 			{DiscNumber: 2, Position: 3},
 		},
 	}
 	tests := []struct {
 		name       string
 		cand       Candidate
 		local      LocalTrack
 		track      CandidateTrack
 		wantTracks any
 		wantDiscs  any
 	}{
 		{
 			// The common case, and the one a diff guard would skip: the
 			// file declares no total at all, so the total "has not
 			// changed" and would never be written.
 			name: "a file with no total gets one",
 			cand: Candidate{Tracks: []CandidateTrack{
 				{Position: 1}, {Position: 2}, {Position: 3},
 			}},
 			local:      LocalTrack{TrackNumber: 1},
 			track:      CandidateTrack{Position: 1},
 			wantTracks: 3,
 			wantDiscs:  1,
 		},
 		{
 			// 5 here would be the release's track count.  Summed once
 			// per disc by GetAlbumCompleteness that claims a ten-track
 			// expectation for a five-track album, which no library can
 			// ever satisfy.
 			name:       "a multi-disc release totals the track's own disc",
 			cand:       twoDiscs,
 			local:      LocalTrack{},
 			track:      CandidateTrack{DiscNumber: 2, Position: 1},
 			wantTracks: 3,
 			wantDiscs:  2,
 		},
 		{
 			name:       "the other disc gets its own total",
 			cand:       twoDiscs,
 			local:      LocalTrack{},
 			track:      CandidateTrack{DiscNumber: 1, Position: 1},
 			wantTracks: 2,
 			wantDiscs:  2,
 		},
 		{
 			// A candidate with no tracklist knows nothing, and writing
 			// a zero would claim it did.
 			name:       "a candidate with no tracklist writes no total",
 			cand:       Candidate{},
 			local:      LocalTrack{},
 			track:      CandidateTrack{Position: 1},
 			wantTracks: nil,
 			wantDiscs:  nil,
 		},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 			changes := buildChanges(tc.local, tc.cand, tc.track)
 			if got := changes[FieldTotalTracks]; got != tc.wantTracks {
 				t.Errorf("%s: got %v, want %v", FieldTotalTracks, got, tc.wantTracks)
 			}
 			if got := changes[FieldTotalDiscs]; got != tc.wantDiscs {
 				t.Errorf("%s: got %v, want %v", FieldTotalDiscs, got, tc.wantDiscs)
 			}
 		})
 	}
 }
@@ -17,34 +17,6 @@ const (
 	RecommendationStrong Recommendation = "strong"
 )
 // ConfidentTier is the tier at which this package considers a match
 // good enough to act on without being asked to look.
 //
 // It exists as a name rather than as `== RecommendationStrong` at
 // each call site because two features read it and they must not
 // disagree about what "high confidence" means: the album page tells
 // the user unprompted that the autotagger has a match (#28), and
 // strict auto-accept will rewrite the files without asking (#90).
 // A page that says "we are sure" about something the auto-accept
 // pass would decline is the app contradicting itself.
 //
 // What the two do *not* share is everything else. Surfacing a match
 // is a suggestion with a confirm dialog behind it; auto-accept is an
 // irreversible on-disk rewrite, and #90 gates it on further
 // conditions this tier cannot express — exact track count, every
 // title matching, lengths within a couple of seconds, no cover
 // replacement, no MBID conflict. So this is the floor both stand on,
 // not the whole of either test.
 const ConfidentTier = RecommendationStrong
 // Confident reports whether a tier clears ConfidentTier.
 //
 // A comparison rather than an equality, so adding a tier above
 // "strong" later does not silently stop qualifying.
 func Confident(r Recommendation) bool {
 	return recommendationRank(r) >= recommendationRank(ConfidentTier)
 }
 const (
 	// Absolute score tiers.
 	strongScoreThresh = 0.90
@@ -168,34 +168,3 @@ func TestRecommend_LocalCandidatesWithoutRGMBIDCompareByTitle(t *testing.T) {
 		t.Errorf("different-title rival: Recommend = %q, want medium", got)
 	}
 }
 // The tier both features stand on is one name, checked here rather
 // than assumed at two call sites.
 //
 // #28 renders "we have a match for this album" on the album page and
 // #90 will rewrite files without asking; a page that claims confidence
 // the auto-accept pass would decline is the app contradicting itself.
 // What they do not share is everything else — auto-accept adds gates
 // this tier cannot express — so this pins the floor, not the whole of
 // either test.
 func TestConfidentIsTheOneSharedFloor(t *testing.T) {
 	t.Parallel()
 	if ConfidentTier != RecommendationStrong {
 		t.Errorf("ConfidentTier = %q, want strong", ConfidentTier)
 	}
 	for _, tc := range []struct {
 		rec  Recommendation
 		want bool
 	}{
 		{RecommendationNone, false},
 		{RecommendationLow, false},
 		{RecommendationMedium, false},
 		{RecommendationStrong, true},
 	} {
 		if got := Confident(tc.rec); got != tc.want {
 			t.Errorf("Confident(%q) = %v, want %v", tc.rec, got, tc.want)
 		}
 	}
 }
@@ -1,145 +0,0 @@
 package autotagservice
 import (
 	"database/sql"
 	"fmt"
 	"yellowjacket/backend/autotag"
 )
 // AlbumMatchView is "the autotagger already has a confident match for
 // the album you are looking at".
 //
 // It is deliberately not a score. The album page renders a suggestion,
 // and a suggestion has to be actionable: which release, what it is
 // called, and whether acting on it here would do the whole album or
 // only part of it.
 type AlbumMatchView struct {
 	// GroupKey is the tagging group the actions operate on.
 	GroupKey string `json:"groupKey"`
 	// Recommendation is the tier, as a string, for a caller that
 	// wants to render the strength rather than trust the filter.
 	Recommendation string `json:"recommendation"`
 	// Score is the top candidate's raw score, 0..1.
 	Score float64 `json:"score"`
 	// ReleaseMBID is the release Apply would write.
 	ReleaseMBID string `json:"releaseMbid"`
 	// Title and ArtistCredit name that release, so the banner can say
 	// what it is offering rather than "a match".
 	Title        string `json:"title"`
 	ArtistCredit string `json:"artistCredit"`
 	// TrackCount is the group's local track count.
 	TrackCount int64 `json:"trackCount"`
 	// GroupCount is how many tagging groups this album spans.
 	//
 	// More than one means a multi-disc album (one group per disc), and
 	// it is the reason this is a field rather than an implementation
 	// detail: applying "the album" from a single button would retag
 	// one disc of three and leave the folder holding a mix of old and
 	// new tags. The caller offers review instead.
 	GroupCount int `json:"groupCount"`
 }
 // MatchForAlbum answers "does the autotagger have something confident
 // to say about this album", for the album detail page.
 //
 // Three things about it are load-bearing.
 //
 // **It costs no MusicBrainz request.** Everything it needs is already
 // on disk: `tagging_items` carries the top score and release from the
 // background prefetch, and `tagging_candidates` durably holds the
 // scored list. The rate limiters here are shared with every page the
 // user can open, so a lookup that fires on page load must not join
 // that queue — which also means this returns nothing for a folder
 // nobody has scored yet, rather than scoring it now. That is the
 // right trade: the prefetch will get to it, and a page that silently
 // spends a minute of somebody's MusicBrainz budget to draw a banner
 // is worse than a page that says nothing.
 //
 // **The tier is computed, not read.** `tagging_items.score` is the raw
 // number and `Recommend` is what turns it into a claim — capping it
 // for an ambiguous runner-up, an incomplete alignment or a folder too
 // small to corroborate itself. Filtering on the raw score would
 // promise confidence the scorer had explicitly withheld.
 //
 // **Nothing is said about an album the user has already answered
 // for.** Only a `pending` group qualifies: `confirmed` covers both a
 // finished apply and an explicit "leave as is", and `skipped` is the
 // user saying not now. Re-offering either is nagging, and "leave as
 // is" would be actively wrong to argue with.
 func (s *Service) MatchForAlbum(albumID int64) (*AlbumMatchView, error) {
 	if albumID <= 0 {
 		return nil, nil //nolint:nilnil // "no album" is not an error.
 	}
 	rows, err := s.db.Queries.GetTaggingItemsForAlbum(
 		s.ctx, sql.NullInt64{Int64: albumID, Valid: true},
 	)
 	if err != nil {
 		return nil, fmt.Errorf("tagging items for album: %w", err)
 	}
 	pending := rows[:0:0]
 	for _, row := range rows {
 		if row.Status == "pending" {
 			pending = append(pending, row)
 		}
 	}
 	if len(pending) == 0 {
 		return nil, nil //nolint:nilnil // nothing to say is not an error.
 	}
 	// Rows arrive best-score-first, so the first pending one is the
 	// group worth describing. On a multi-disc album that is one disc
 	// of several and GroupCount says so.
 	best := pending[0]
 	cands := s.lookupCachedCandidates(best.GroupKey)
 	if len(cands) == 0 {
 		return nil, nil //nolint:nilnil // not scored yet; see the doc comment.
 	}
 	locals, err := s.scorer.LocalTracksForGroup(s.ctx, best.GroupKey)
 	if err != nil {
 		return nil, fmt.Errorf("local tracks for group: %w", err)
 	}
 	group := autotag.Group{
 		AlbumName:   best.AlbumName,
 		AlbumArtist: best.AlbumArtist,
 		Tracks:      locals,
 		Synthetic:   best.Synthetic != 0,
 	}
 	rec := autotag.Recommend(group, cands)
 	if !autotag.Confident(rec) {
 		return nil, nil //nolint:nilnil // not confident enough to interrupt.
 	}
 	top := cands[0]
 	// The release the banner names must be the release Apply would
 	// write. Apply with an empty MBID takes the top cached candidate,
 	// which is what this reads — but it is passed explicitly anyway,
 	// so a rescore between the page rendering and the user clicking
 	// cannot swap the album out from under a button they have already
 	// read.
 	return &AlbumMatchView{
 		GroupKey:       best.GroupKey,
 		Recommendation: string(rec),
 		Score:          top.Score,
 		ReleaseMBID:    top.ReleaseMBID,
 		Title:          top.Title,
 		ArtistCredit:   top.ArtistCredit,
 		TrackCount:     best.TrackCount,
 		GroupCount:     len(pending),
 	}, nil
 }
@@ -1,320 +0,0 @@
 package autotagservice
 import (
 	"encoding/json"
 	"testing"
 	"yellowjacket/backend/autotag"
 	"yellowjacket/backend/database"
 )
 // seedAlbumGroup writes one album's files, its tagging item and the
 // durable candidate blob the prefetch would have left behind.
 //
 // The candidate list is what a real one looks like in the two ways
 // that decide the tier: a per-track alignment for every local track,
 // and a runner-up far enough away not to count as ambiguity.
 func seedAlbumGroup(
 	t *testing.T,
 	db *database.DB,
 	groupKey string,
 	tracks int,
 	status string,
 	score float64,
 ) int64 {
 	t.Helper()
 	for i := 1; i <= tracks; i++ {
 		database.InsertTestTrack(t, db, database.TestTrack{
 			FilePath:    filePathFor(groupKey, i),
 			Title:       titleFor(i),
 			Artist:      "Tideline",
 			Album:       "Glass Harbour",
 			AlbumArtist: "Tideline",
 			TrackNumber: int64(i),
 			LengthMs:    200000,
 			LibraryID:   0,
 			GroupKey:    groupKey,
 		})
 	}
 	if _, err := db.ExecContext(`
 		INSERT INTO tagging_items
 		    (group_key, library_id, track_count, album_name, album_artist,
 		     disc_number, status, score, best_match_release_mbid)
 		VALUES (?, 0, ?, 'Glass Harbour', 'Tideline', 0, ?, ?, 'rel-1')
 	`, groupKey, tracks, status, score); err != nil {
 		t.Fatalf("insert tagging item: %v", err)
 	}
 	var albumID int64
 	if err := db.QueryRowWriter(
 		`SELECT album_id FROM audio_files WHERE group_key = ? LIMIT 1`, groupKey,
 	).Scan(&albumID); err != nil {
 		t.Fatalf("read album id: %v", err)
 	}
 	return albumID
 }
 func filePathFor(groupKey string, n int) string {
 	return "/music/" + groupKey + "/0" + string(rune('0'+n)) + ".mp3"
 }
 func titleFor(n int) string {
 	return "Track " + string(rune('0'+n))
 }
 // storeCandidates writes the durable blob GetCandidates would have
 // cached, with `top` as the winning score.
 func storeCandidates(
 	t *testing.T, db *database.DB, groupKey string, tracks int, top float64,
 ) {
 	t.Helper()
 	aligns := make([]autotag.TrackAlignment, 0, tracks)
 	for i := range tracks {
 		aligns = append(aligns, autotag.TrackAlignment{
 			Status:     autotag.AlignmentMatched,
 			LocalIndex: i,
 		})
 	}
 	cands := []autotag.Candidate{
 		{
 			ReleaseMBID:      "rel-1",
 			ReleaseGroupMBID: "rg-1",
 			Title:            "Glass Harbour",
 			ArtistCredit:     "Tideline",
 			TrackCount:       tracks,
 			Alignments:       aligns,
 			Score:            top,
 		},
 		{
 			ReleaseMBID:      "rel-2",
 			ReleaseGroupMBID: "rg-2",
 			Title:            "Something Else",
 			ArtistCredit:     "Another Band",
 			TrackCount:       tracks,
 			Score:            0.40,
 		},
 	}
 	blob, err := json.Marshal(cands)
 	if err != nil {
 		t.Fatalf("marshal candidates: %v", err)
 	}
 	if _, err := db.ExecContext(
 		`INSERT INTO tagging_candidates (group_key, candidates) VALUES (?, ?)`,
 		groupKey, string(blob),
 	); err != nil {
 		t.Fatalf("insert candidates: %v", err)
 	}
 }
 // A confident match is what the album page exists to surface.
 func TestMatchForAlbumSurfacesAConfidentMatch(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	svc := newTestService(t, db)
 	albumID := seedAlbumGroup(t, db, "grp-1", 8, "pending", 0.95)
 	storeCandidates(t, db, "grp-1", 8, 0.95)
 	got, err := svc.MatchForAlbum(albumID)
 	if err != nil {
 		t.Fatalf("MatchForAlbum: %v", err)
 	}
 	if got == nil {
 		t.Fatal("no match returned for a strong candidate")
 	}
 	if got.Recommendation != string(autotag.RecommendationStrong) {
 		t.Errorf("recommendation = %q, want strong", got.Recommendation)
 	}
 	// The release named is the release Apply would write — the page
 	// must not offer one album and tag another.
 	if got.ReleaseMBID != "rel-1" || got.Title != "Glass Harbour" {
 		t.Errorf("named %q/%q, want rel-1/Glass Harbour", got.ReleaseMBID, got.Title)
 	}
 	if got.GroupCount != 1 {
 		t.Errorf("groupCount = %d, want 1", got.GroupCount)
 	}
 }
 // The tier is computed from the candidates, not read off the raw
 // score — a high number the scorer would have capped must not reach
 // the page as confidence it withheld.
 func TestMatchForAlbumDoesNotTrustTheStoredScore(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	svc := newTestService(t, db)
 	// Two tracks: below the evidence floor, so `Recommend` caps this
 	// at medium however well it scores.
 	albumID := seedAlbumGroup(t, db, "grp-2", 2, "pending", 0.99)
 	storeCandidates(t, db, "grp-2", 2, 0.99)
 	got, err := svc.MatchForAlbum(albumID)
 	if err != nil {
 		t.Fatalf("MatchForAlbum: %v", err)
 	}
 	if got != nil {
 		t.Errorf("surfaced %+v for a two-track folder, want nothing", got)
 	}
 }
 // A weak match is not worth interrupting for.
 func TestMatchForAlbumStaysQuietBelowTheTier(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	svc := newTestService(t, db)
 	albumID := seedAlbumGroup(t, db, "grp-3", 8, "pending", 0.60)
 	storeCandidates(t, db, "grp-3", 8, 0.60)
 	got, err := svc.MatchForAlbum(albumID)
 	if err != nil {
 		t.Fatalf("MatchForAlbum: %v", err)
 	}
 	if got != nil {
 		t.Errorf("surfaced %+v for a 0.60 match, want nothing", got)
 	}
 }
 // An album the user has already answered for is not re-offered.
 //
 // `confirmed` covers both a finished apply and an explicit "leave as
 // is", and arguing with the second would be actively wrong.
 func TestMatchForAlbumRespectsAnAnswerAlreadyGiven(t *testing.T) {
 	t.Parallel()
 	for _, status := range []string{"confirmed", "skipped", "matched"} {
 		t.Run(status, func(t *testing.T) {
 			t.Parallel()
 			db := database.NewTestDB(t)
 			svc := newTestService(t, db)
 			albumID := seedAlbumGroup(t, db, "grp-"+status, 8, status, 0.95)
 			storeCandidates(t, db, "grp-"+status, 8, 0.95)
 			got, err := svc.MatchForAlbum(albumID)
 			if err != nil {
 				t.Fatalf("MatchForAlbum: %v", err)
 			}
 			if got != nil {
 				t.Errorf("surfaced %+v for a %s group, want nothing", got, status)
 			}
 		})
 	}
 }
 // A folder nobody has scored yet says nothing, rather than scoring it
 // now: the MusicBrainz limiter is shared with every page the user can
 // open, and this runs on page load.
 func TestMatchForAlbumMakesNoNetworkCallForAnUnscoredFolder(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	svc := newTestService(t, db)
 	// No storeCandidates: the prefetch has not reached this folder.
 	albumID := seedAlbumGroup(t, db, "grp-4", 8, "pending", 0.95)
 	got, err := svc.MatchForAlbum(albumID)
 	if err != nil {
 		t.Fatalf("MatchForAlbum: %v", err)
 	}
 	if got != nil {
 		t.Errorf("surfaced %+v with no cached candidates, want nothing", got)
 	}
 }
 // A multi-disc album is several groups, and the count is what stops
 // the page offering one button that would retag one disc of two.
 func TestMatchForAlbumCountsEveryGroupOfTheAlbum(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	svc := newTestService(t, db)
 	albumID := seedAlbumGroup(t, db, "grp-d1", 8, "pending", 0.95)
 	storeCandidates(t, db, "grp-d1", 8, 0.95)
 	// Disc two: same album row, its own folder and tagging group.
 	for i := 1; i <= 6; i++ {
 		database.InsertTestTrack(t, db, database.TestTrack{
 			FilePath:    filePathFor("grp-d2", i),
 			Title:       titleFor(i),
 			Artist:      "Tideline",
 			Album:       "Glass Harbour",
 			AlbumArtist: "Tideline",
 			TrackNumber: int64(i),
 			DiscNumber:  2,
 			LengthMs:    200000,
 			LibraryID:   0,
 			GroupKey:    "grp-d2",
 		})
 	}
 	if _, err := db.ExecContext(`
 		INSERT INTO tagging_items
 		    (group_key, library_id, track_count, album_name, album_artist,
 		     disc_number, status, score)
 		VALUES ('grp-d2', 0, 6, 'Glass Harbour', 'Tideline', 2, 'pending', 0.93)
 	`); err != nil {
 		t.Fatalf("insert disc two: %v", err)
 	}
 	storeCandidates(t, db, "grp-d2", 6, 0.93)
 	got, err := svc.MatchForAlbum(albumID)
 	if err != nil {
 		t.Fatalf("MatchForAlbum: %v", err)
 	}
 	if got == nil {
 		t.Fatal("no match returned")
 	}
 	if got.GroupCount != 2 {
 		t.Errorf("groupCount = %d, want 2", got.GroupCount)
 	}
 	// Best-first: the 0.95 disc is the one described.
 	if got.GroupKey != "grp-d1" {
 		t.Errorf("described %q, want the higher-scoring grp-d1", got.GroupKey)
 	}
 }
 // An album with no local files at all — a pure catalog page — is not
 // a question this can answer.
 func TestMatchForAlbumSaysNothingWithoutAnAlbum(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	svc := newTestService(t, db)
 	for _, id := range []int64{0, -1, 4242} {
 		got, err := svc.MatchForAlbum(id)
 		if err != nil {
 			t.Fatalf("MatchForAlbum(%d): %v", id, err)
 		}
 		if got != nil {
 			t.Errorf("MatchForAlbum(%d) = %+v, want nil", id, got)
 		}
 	}
 }
@@ -1,38 +0,0 @@
 package autotagservice
 import (
 	"testing"
 	"yellowjacket/backend/autotag"
 	"yellowjacket/backend/tagwriter"
 )
 // twAdapter passes the diff map through unchanged, so autotag's field
 // constants and tagwriter's are the same keys written down twice --
 // deliberately, to keep autotag out of the write pipeline's import
 // graph.  A key that drifts does not fail to compile and does not fail
 // to write: the writer simply finds no entry under the name it looks
 // for, and the field is silently dropped.  That is what this pins, and
 // this package is the one place that imports both.
 func TestAutotagAndTagwriterAgreeOnFieldNames(t *testing.T) {
 	t.Parallel()
 	pairs := map[string][2]string{
 		"title":        {autotag.FieldTitle, tagwriter.FieldTitle},
 		"artist":       {autotag.FieldArtist, tagwriter.FieldArtist},
 		"album":        {autotag.FieldAlbum, tagwriter.FieldAlbum},
 		"album artist": {autotag.FieldAlbumArtist, tagwriter.FieldAlbumArtist},
 		"year":         {autotag.FieldYear, tagwriter.FieldYear},
 		"track number": {autotag.FieldTrackNumber, tagwriter.FieldTrackNumber},
 		"disc number":  {autotag.FieldDiscNumber, tagwriter.FieldDiscNumber},
 		"total tracks": {autotag.FieldTotalTracks, tagwriter.FieldTotalTracks},
 		"total discs":  {autotag.FieldTotalDiscs, tagwriter.FieldTotalDiscs},
 		"cover art":    {autotag.FieldCoverArt, tagwriter.FieldCoverArt},
 	}
 	for name, pair := range pairs {
 		if pair[0] != pair[1] {
 			t.Errorf("%s: autotag says %q, tagwriter says %q", name, pair[0], pair[1])
 		}
 	}
 }
@@ -411,10 +411,9 @@ func (c *Config) SetDownloadPreferences(prefs download.AutoDownloadPrefs) error
 		formats = append(formats, string(f))
 	}
-	c.Downloads.MinKbps = prefs.MinKbps
+	c.Downloads.MinFileSizeMB = prefs.MinSizeMB
 	c.Downloads.MaxKbps = prefs.MaxKbps
 	c.Downloads.PreferredKbps = prefs.PreferredKbps
 	c.Downloads.MaxFileSizeMB = prefs.MaxSizeMB
 	c.Downloads.PreferredFileSizeMB = prefs.PreferredSizeMB
 	c.Downloads.AllowedFormats = formats
 	if err := c.Save(); err != nil {
@@ -544,7 +543,7 @@ func (c *Config) SetDefaultPage(page string) error {
 		c.General.ApplyDefaults()
 	}
-	c.General.DefaultPage = View(page)
+	c.General.DefaultPage = DefaultPage(page)
 	if err := c.General.Validate(); err != nil {
 		return fmt.Errorf(
@@ -666,124 +665,6 @@ func (c *Config) SetAllowMeteredCatalogDownload(allow bool) error {
 	return nil
 }
 // GetPopupVolume reports whether the bottom bar's volume control is a
 // click-to-open popup rather than an inline slider (#42).
 func (c *Config) GetPopupVolume() bool {
 	if c.General == nil {
 		return false
 	}
 	return c.General.PopupVolume
 }
 // SetPopupVolume saves the volume control's presentation.
 //
 // Nothing to validate: both values are legal at every width, and the
 // frontend additionally stands the inline slider down below the phone
 // breakpoint whatever this says, because that is about room rather than
 // about preference.
 func (c *Config) SetPopupVolume(popup bool) error {
 	if c.General == nil {
 		c.General = &GeneralConfig{}
 		c.General.ApplyDefaults()
 	}
 	c.General.PopupVolume = popup
 	if err := c.Save(); err != nil {
 		return fmt.Errorf(
 			"could not save config: %w", err,
 		)
 	}
 	events.Emit(
 		c.ctx,
 		events.GeneralConfigChanged,
 		map[string]any{
 			"PopupVolume": popup,
 		},
 	)
 	c.logger.Info("volume control presentation updated", "popup", popup)
 	return nil
 }
 // GetViewVisibility reports which primary views the sidebar should
 // show, answered for every known view rather than only the ones the
 // config mentions -- so the frontend filters on a value and never has
 // to hold a second copy of the defaults.
 func (c *Config) GetViewVisibility() map[string]bool {
 	if c.General == nil {
 		general := &GeneralConfig{}
 		general.ApplyDefaults()
 		return general.ResolvedViewVisibility()
 	}
 	return c.General.ResolvedViewVisibility()
 }
 // SetViewVisible shows or hides one primary view.
 //
 // Two refusals, both about a state the user cannot get out of from the
 // UI they would be left with: Settings is never hideable, and the
 // launch page is never hideable while it is the launch page (change it
 // first). Hiding a view does not make it unreachable -- `navigate`
 // still resolves it, which detail views depend on -- it only takes the
 // nav item away.
 func (c *Config) SetViewVisible(view string, visible bool) error {
 	spec, known := LookupView(view)
 	if !known {
 		return fmt.Errorf("%w: %q", errUnknownView, view)
 	}
 	if c.General == nil {
 		c.General = &GeneralConfig{}
 		c.General.ApplyDefaults()
 	}
 	if !visible {
 		if !spec.Hideable {
 			return fmt.Errorf("%w: %q", errViewNotHideable, view)
 		}
 		if spec.ID == c.General.DefaultPage {
 			return fmt.Errorf("%w: %q", errViewIsLaunchPage, view)
 		}
 	}
 	if c.General.ViewVisibility == nil {
 		c.General.ViewVisibility = make(map[string]bool, len(Views))
 	}
 	c.General.ViewVisibility[view] = visible
 	if err := c.General.Validate(); err != nil {
 		return fmt.Errorf("invalid view visibility: %w", err)
 	}
 	if err := c.Save(); err != nil {
 		return fmt.Errorf("could not save config: %w", err)
 	}
 	events.Emit(
 		c.ctx,
 		events.GeneralConfigChanged,
 		map[string]any{
 			"ViewVisibility": c.General.ResolvedViewVisibility(),
 		},
 	)
 	c.logger.Info(
 		"view visibility updated",
 		"view", view,
 		"visible", visible,
 	)
 	return nil
 }
 // GetTrackListColumns returns the configured track-list columns.
 func (c *Config) GetTrackListColumns() []tracklist.Column {
 	if c.TrackList == nil {
@@ -188,43 +188,3 @@ func TestEmit_FavoritesChangeCarriesFullConfig(t *testing.T) {
 		}
 	}
 }
 // TestEmit_PopupVolumeRoundTripsAndDefaultsToInline pins both halves of
 // #42's storage decision.
 //
 // The **default** is the load-bearing one: inline is what a fresh
 // install and an existing `config.toml` with no such key must both
 // produce, which is why the field names the popup rather than the
 // inline slider. A flag spelled the other way round would default to
 // false, hand every existing install the popup this issue exists to
 // stop being the only option, and need a migration to say otherwise.
 func TestEmit_PopupVolumeRoundTripsAndDefaultsToInline(t *testing.T) {
 	t.Parallel()
 	conf, rec := setupRecordedConfig(t)
 	if conf.GetPopupVolume() {
 		t.Error("a config with no PopupVolume key wants the popup, want inline")
 	}
 	if err := conf.SetPopupVolume(true); err != nil {
 		t.Fatalf("SetPopupVolume: %v", err)
 	}
 	if !conf.GetPopupVolume() {
 		t.Error("GetPopupVolume = false after setting it true")
 	}
 	data := payloadMap(t, rec, events.GeneralConfigChanged)
 	if data["PopupVolume"] != true {
 		t.Errorf("PopupVolume = %v, want true", data["PopupVolume"])
 	}
 	if err := conf.SetPopupVolume(false); err != nil {
 		t.Fatalf("SetPopupVolume(false): %v", err)
 	}
 	if conf.GetPopupVolume() {
 		t.Error("GetPopupVolume = true after setting it false")
 	}
 }
@@ -5,14 +5,28 @@ import (
 	"fmt"
 )
-// DefaultDefaultPage is the launch page for a fresh install.
+// DefaultPage identifies which view the app opens to on launch.
-const DefaultDefaultPage = ViewHome
+type DefaultPage string
-var (
+// Valid DefaultPage values, matching the frontend's top-level route ids.
-	errUnknownDefaultPage = errors.New("unknown default page")
+const (
-	errViewCannotLaunch   = errors.New("view cannot be the launch page")
+	DefaultPageHome      DefaultPage = "home"
 	DefaultPageTracks    DefaultPage = "tracks"
 	DefaultPageAlbums    DefaultPage = "albums"
 	DefaultPageArtists   DefaultPage = "artists"
 	DefaultPageGenres    DefaultPage = "genres"
 	DefaultPagePlaylists DefaultPage = "playlists"
 	DefaultPageExplore   DefaultPage = "explore"
 	DefaultPageDownloads DefaultPage = "downloads"
 	DefaultPageAutotag   DefaultPage = "autotag"
 	DefaultPageJobs      DefaultPage = "jobs"
 )
 // DefaultDefaultPage is the launch page for a fresh install.
 const DefaultDefaultPage = DefaultPageHome
 var errUnknownDefaultPage = errors.New("unknown default page")
 // QueueFallback identifies what plays, if anything, once the queue
 // runs out with nothing left to auto-advance to.
 type QueueFallback string
@@ -32,52 +46,18 @@ var errUnknownQueueFallback = errors.New("unknown queue fallback")
 // GeneralConfig holds general application preferences that don't
 // belong to a more specific subsystem.
 type GeneralConfig struct {
-	DefaultPage   View          `toml:"DefaultPage"`
+	DefaultPage   DefaultPage   `toml:"DefaultPage"`
 	QueueFallback QueueFallback `toml:"QueueFallback"`
 	// ViewVisibility says which sidebar destinations are shown, keyed by
 	// view id.
 	//
 	// **An absent key means that view's own default** (`Views`), and that
 	// is the whole reason this is a map rather than a `HiddenViews
 	// []string` or a struct of booleans. A list's zero value is "hide
 	// nothing", which cannot express Autotag being off by default without
 	// a migration; a struct field for a view that later stops existing is
 	// stored garbage somebody has to deprecate. Here a view added later
 	// gets its own default rather than being invisible or forcibly
 	// visible, an unknown key is dropped on load, and no install needs
 	// migrating in either direction. Same polarity rule as
 	// AllowMeteredCatalogDownload: the zero value is the intended answer.
 	ViewVisibility map[string]bool `toml:"ViewVisibility"`
 	// AllowMeteredCatalogDownload permits the ~0.6 GB Explore catalog to
 	// be fetched on a connection the platform calls cellular. It defaults
 	// to false, which is the whole point: the zero value is the safe one,
 	// so an existing config with no such key refuses by default rather
 	// than needing a migration to become careful.
 	AllowMeteredCatalogDownload bool `toml:"AllowMeteredCatalogDownload"`
 	// PopupVolume draws the bottom bar's volume as a click-to-open popup
 	// instead of a slider that is always there (#42).
 	//
 	// The polarity is the rule this file already states twice: **the
 	// zero value is the intended answer**. Inline is the new default, so
 	// the flag has to name the *other* choice — an `InlineVolume bool`
 	// would default to false and give every existing install the popup
 	// this issue exists to stop being the only option, and would need a
 	// migration to say otherwise.
 	PopupVolume bool `toml:"PopupVolume"`
 }
 // ApplyDefaults fills zero-value fields with sensible defaults.
 //
 // A launch page naming a *retired* view is treated as a zero value
 // rather than as an error, because the alternative is an app that will
 // not start for anyone who had that page selected when it was removed.
 // An unknown-but-not-retired name still fails Validate: that is a typo,
 // and telling someone about it is the useful answer.
 func (c *GeneralConfig) ApplyDefaults() {
 	if _, retired := RetiredViews[c.DefaultPage]; retired {
 		c.DefaultPage = ""
 	}
 	if c.DefaultPage == "" {
 		c.DefaultPage = DefaultDefaultPage
 	}
@@ -91,17 +71,15 @@ func (c *GeneralConfig) ApplyDefaults() {
 func (c *GeneralConfig) Validate() error {
 	c.ApplyDefaults()
-	spec, known := LookupView(string(c.DefaultPage))
+	switch c.DefaultPage {
-	if !known {
+	case DefaultPageHome, DefaultPageTracks, DefaultPageAlbums, DefaultPageArtists,
 		DefaultPageGenres, DefaultPagePlaylists, DefaultPageExplore, DefaultPageDownloads,
 		DefaultPageAutotag, DefaultPageJobs:
 		// Valid.
 	default:
 		return fmt.Errorf("%w: %q", errUnknownDefaultPage, c.DefaultPage)
 	}
 	if !spec.CanLaunch {
 		return fmt.Errorf("%w: %q", errViewCannotLaunch, c.DefaultPage)
 	}
 	c.normalizeViewVisibility()
 	switch c.QueueFallback {
 	case QueueFallbackStop, QueueFallbackFavorites, QueueFallbackDynamicMix:
 		// Valid.
@@ -111,51 +89,3 @@ func (c *GeneralConfig) Validate() error {
 	return nil
 }
 // normalizeViewVisibility drops what the stored map may not say, and
 // repairs the one invariant the shell depends on.
 //
 // Three things are dropped or forced, and all three are reachable only
 // from a hand-edited config or from a version that knew different
 // views: an unknown id (a view removed since, e.g. when #27 folds Jobs
 // into Settings) says nothing to anybody; a view that is not Hideable
 // cannot be false; and **the launch page is always visible**, because
 // otherwise an install lands on a page with no nav item pointing at it.
 //
 // That last one is a *repair* here and an *error* at the setter
 // (SetViewVisible), deliberately. On load there is nobody to tell and
 // the honest reading of "my launch page is Autotag" is that this user
 // wants Autotag, so it is un-hidden rather than the launch page being
 // silently reset to something they did not choose. At the setter the
 // user is right there and can act, so it refuses and says why.
 func (c *GeneralConfig) normalizeViewVisibility() {
 	for id := range c.ViewVisibility {
 		spec, known := LookupView(id)
 		if !known || !spec.Hideable {
 			delete(c.ViewVisibility, id)
 		}
 	}
 	if visible, ok := c.ViewVisibility[string(c.DefaultPage)]; ok && !visible {
 		c.ViewVisibility[string(c.DefaultPage)] = true
 	}
 }
 // ResolvedViewVisibility answers for every known view, so no caller has
 // to know the defaults -- the frontend included, which is why the
 // binding returns this rather than the stored map.
 func (c *GeneralConfig) ResolvedViewVisibility() map[string]bool {
 	resolved := make(map[string]bool, len(Views))
 	for _, v := range Views {
 		visible := v.VisibleByDefault
 		if stored, ok := c.ViewVisibility[string(v.ID)]; ok && v.Hideable {
 			visible = stored
 		}
 		resolved[string(v.ID)] = visible
 	}
 	return resolved
 }
@@ -1,103 +0,0 @@
 package config
 import "errors"
 var (
 	errUnknownView      = errors.New("unknown view")
 	errViewNotHideable  = errors.New("view cannot be hidden")
 	errViewIsLaunchPage = errors.New("view is the launch page")
 )
 // View identifies one of the shell's primary destinations -- the
 // things the sidebar lists and `index.ts` knows as `VIEW_TAGS`.
 type View string
 // The primary views, in no particular order: the sidebar owns the order
 // it draws them in, because that is presentation.
 const (
 	ViewHome      View = "home"
 	ViewPlaylists View = "playlists"
 	ViewArtists   View = "artists"
 	ViewGenres    View = "genres"
 	ViewAlbums    View = "albums"
 	ViewTracks    View = "tracks"
 	ViewExplore   View = "explore"
 	ViewDownloads View = "downloads"
 	ViewAutotag   View = "autotag"
 	ViewSettings  View = "settings"
 )
 // RetiredViews are destinations that used to exist and no longer do.
 //
 // A *visibility* entry for a removed view needs no such list: it is a
 // key in a map, and an unknown key is dropped on load. A `DefaultPage`
 // is a **value**, and an unknown one fails validation -- which on the
 // load path means the app refuses to start rather than a setting being
 // ignored. So the one shape that cannot be retired for free is named
 // here and reset to the default instead.
 //
 // `jobs` was folded into Settings by #27: library scans under
 // Libraries, index work under Search Index, downloads under the
 // download clients, and the autotag apply into the Autotag view.
 var RetiredViews = map[View]struct{}{
 	"jobs": {},
 }
 // ViewSpec is what the backend knows about a destination. The label and
 // the icon are deliberately absent: those are presentation, they live
 // beside the rest of the app's icon vocabulary in
 // `frontend/src/utils/icon-language.ts`, and a Go copy of them would be
 // a second thing to keep in step for nothing.
 type ViewSpec struct {
 	// ID is the view name the frontend navigates by.
 	ID View
 	// VisibleByDefault is what an install gets when the config says
 	// nothing about this view -- which is every install until somebody
 	// changes it, and every view added after this one shipped.
 	VisibleByDefault bool
 	// Hideable is false for Settings alone. It is a property of the
 	// view rather than a check in the setter because `config.toml` is
 	// hand-editable, and an app that can be locked out of its own
 	// Settings by a typo is a support problem nobody can debug
 	// remotely.
 	Hideable bool
 	// CanLaunch reports whether the view may be the launch page.
 	// Settings is the only one that may not, which is the shape the
 	// DefaultPage enum already had.
 	CanLaunch bool
 }
 // Views is the one list of primary destinations, in the order Settings
 // offers them.
 //
 // It is the single source for three things that used to be written down
 // separately: which views exist, which of them may be the launch page
 // (`DefaultPage`'s validation reads it), and what an unconfigured
 // install shows.
 //
 // Autotag is the one view hidden by default: it rewrites tags on disk,
 // which is not what most libraries want on day one, and #25 asks for it
 // to be turned on deliberately.
 var Views = []ViewSpec{
 	{ID: ViewHome, VisibleByDefault: true, Hideable: true, CanLaunch: true},
 	{ID: ViewPlaylists, VisibleByDefault: true, Hideable: true, CanLaunch: true},
 	{ID: ViewArtists, VisibleByDefault: true, Hideable: true, CanLaunch: true},
 	{ID: ViewGenres, VisibleByDefault: true, Hideable: true, CanLaunch: true},
 	{ID: ViewAlbums, VisibleByDefault: true, Hideable: true, CanLaunch: true},
 	{ID: ViewTracks, VisibleByDefault: true, Hideable: true, CanLaunch: true},
 	{ID: ViewExplore, VisibleByDefault: true, Hideable: true, CanLaunch: true},
 	{ID: ViewDownloads, VisibleByDefault: true, Hideable: true, CanLaunch: true},
 	{ID: ViewAutotag, VisibleByDefault: false, Hideable: true, CanLaunch: true},
 	{ID: ViewSettings, VisibleByDefault: true, Hideable: false, CanLaunch: false},
 }
 // LookupView returns the spec for a view id.
 func LookupView(id string) (ViewSpec, bool) {
 	for _, v := range Views {
 		if string(v.ID) == id {
 			return v, true
 		}
 	}
 	return ViewSpec{}, false
 }
@@ -1,307 +0,0 @@
 package config
 import (
 	"errors"
 	"log/slog"
 	"path/filepath"
 	"testing"
 )
 // newViewTestConfig builds a Config backed by a temp file, which is all
 // SetViewVisible needs: it saves and emits, and the emit is a no-op
 // without a running app.
 func newViewTestConfig(t *testing.T) *Config {
 	t.Helper()
 	c := &Config{
 		logger:   slog.Default(),
 		filePath: filepath.Join(t.TempDir(), "config.toml"),
 	}
 	// Load a file that is not there: that is what marks the config
 	// loaded, without which Save refuses on the *second* write.
 	if err := c.Load(); err != nil {
 		t.Fatalf("Load() error: %v", err)
 	}
 	return c
 }
 // A view the config says nothing about takes its own default, which is
 // what makes this need no migration in either direction: an existing
 // install gets Autotag hidden without a key, and a view added later
 // gets its own answer rather than the list's.
 func TestViewVisibilityDefaults(t *testing.T) {
 	t.Parallel()
 	general := &GeneralConfig{}
 	general.ApplyDefaults()
 	resolved := general.ResolvedViewVisibility()
 	if len(resolved) != len(Views) {
 		t.Fatalf("resolved %d views, want %d", len(resolved), len(Views))
 	}
 	if resolved[string(ViewAutotag)] {
 		t.Error("autotag should be hidden by default")
 	}
 	for _, v := range Views {
 		if v.ID == ViewAutotag {
 			continue
 		}
 		if !resolved[string(v.ID)] {
 			t.Errorf("%s should be visible by default", v.ID)
 		}
 	}
 }
 // A stored answer wins over the default, in both directions -- turning
 // Autotag on is the whole user-facing point.
 func TestViewVisibilityStoredWins(t *testing.T) {
 	t.Parallel()
 	general := &GeneralConfig{
 		ViewVisibility: map[string]bool{
 			string(ViewAutotag): true,
 			string(ViewExplore): false,
 		},
 	}
 	general.ApplyDefaults()
 	resolved := general.ResolvedViewVisibility()
 	if !resolved[string(ViewAutotag)] {
 		t.Error("autotag was switched on and should be visible")
 	}
 	if resolved[string(ViewExplore)] {
 		t.Error("explore was switched off and should be hidden")
 	}
 }
 // A key for a view that no longer exists is discarded rather than
 // migrated. This is the property the #25-before-#27 ordering rests on:
 // when Jobs folds into Settings, `jobs = true` in somebody's config is
 // a key nothing asks about, not a cleanup task.
 func TestValidateDropsUnknownAndUnhideableViews(t *testing.T) {
 	t.Parallel()
 	general := &GeneralConfig{
 		ViewVisibility: map[string]bool{
 			"a-view-that-was-removed": true,
 			string(ViewSettings):      false,
 			string(ViewAutotag):       true,
 		},
 	}
 	if err := general.Validate(); err != nil {
 		t.Fatalf("Validate() error: %v", err)
 	}
 	if _, ok := general.ViewVisibility["a-view-that-was-removed"]; ok {
 		t.Error("an unknown view id should be dropped on load")
 	}
 	if _, ok := general.ViewVisibility[string(ViewSettings)]; ok {
 		t.Error("settings is not hideable and should not be stored")
 	}
 	if !general.ResolvedViewVisibility()[string(ViewSettings)] {
 		t.Error("settings must resolve visible whatever the file said")
 	}
 }
 // On load there is nobody to tell, so a launch page hidden by a
 // hand-edited file is un-hidden rather than the launch page being
 // reset to something the user did not choose.
 func TestValidateRevealsAHiddenLaunchPage(t *testing.T) {
 	t.Parallel()
 	general := &GeneralConfig{
 		DefaultPage: ViewAutotag,
 		ViewVisibility: map[string]bool{
 			string(ViewAutotag): false,
 		},
 	}
 	if err := general.Validate(); err != nil {
 		t.Fatalf("Validate() error: %v", err)
 	}
 	if !general.ResolvedViewVisibility()[string(ViewAutotag)] {
 		t.Error("the launch page must be visible")
 	}
 }
 // A launch page naming a view that no longer exists resets to the
 // default instead of failing validation, which on the load path would
 // mean the app refusing to start for whoever had it selected.
 //
 // This is the one shape #25's storage decision does *not* make free: a
 // visibility entry is a key and an unknown key is dropped, but a launch
 // page is a value.
 func TestARetiredLaunchPageFallsBackToTheDefault(t *testing.T) {
 	t.Parallel()
 	general := &GeneralConfig{DefaultPage: "jobs"}
 	if err := general.Validate(); err != nil {
 		t.Fatalf("Validate() error: %v", err)
 	}
 	if general.DefaultPage != DefaultDefaultPage {
 		t.Errorf("DefaultPage = %q, want %q", general.DefaultPage, DefaultDefaultPage)
 	}
 }
 // A name that is merely wrong is still an error: that is a typo, and
 // saying so is more useful than ignoring it.
 func TestAnUnknownLaunchPageIsStillAnError(t *testing.T) {
 	t.Parallel()
 	general := &GeneralConfig{DefaultPage: "nonsense"}
 	if err := general.Validate(); !errors.Is(err, errUnknownDefaultPage) {
 		t.Fatalf("Validate() error = %v, want errUnknownDefaultPage", err)
 	}
 }
 // A retired view is not a view, so nothing offers it and nothing
 // resolves it -- the visibility map included.
 func TestARetiredViewIsGone(t *testing.T) {
 	t.Parallel()
 	for id := range RetiredViews {
 		if _, ok := LookupView(string(id)); ok {
 			t.Errorf("%s is retired but still in Views", id)
 		}
 		general := &GeneralConfig{}
 		general.ApplyDefaults()
 		if _, ok := general.ResolvedViewVisibility()[string(id)]; ok {
 			t.Errorf("%s is retired but still resolves a visibility", id)
 		}
 	}
 }
 // Settings may not be the launch page, which is the shape the old
 // DefaultPage enum had and is now read off the same table.
 func TestValidateRejectsAnUnlaunchablePage(t *testing.T) {
 	t.Parallel()
 	general := &GeneralConfig{DefaultPage: ViewSettings}
 	err := general.Validate()
 	if !errors.Is(err, errViewCannotLaunch) {
 		t.Fatalf("Validate() error = %v, want errViewCannotLaunch", err)
 	}
 }
 // At the setter the user is present and can act, so the two states
 // they could not get out of are refused rather than repaired.
 func TestSetViewVisibleRefusals(t *testing.T) {
 	t.Parallel()
 	tests := []struct {
 		name    string
 		view    string
 		visible bool
 		want    error
 	}{
 		{"settings is never hideable", string(ViewSettings), false, errViewNotHideable},
 		{"the launch page is not hideable", string(ViewHome), false, errViewIsLaunchPage},
 		{"an unknown view is not a setting", "nonsense", false, errUnknownView},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 			c := newViewTestConfig(t)
 			err := c.SetViewVisible(tt.view, tt.visible)
 			if !errors.Is(err, tt.want) {
 				t.Fatalf("SetViewVisible() error = %v, want %v", err, tt.want)
 			}
 		})
 	}
 }
 // Showing a view is never refused, including Settings and the launch
 // page -- there is no state to be stuck in.
 func TestSetViewVisibleShowsAnything(t *testing.T) {
 	t.Parallel()
 	c := newViewTestConfig(t)
 	for _, v := range Views {
 		if err := c.SetViewVisible(string(v.ID), true); err != nil {
 			t.Fatalf("SetViewVisible(%q, true) error: %v", v.ID, err)
 		}
 	}
 	if !c.GetViewVisibility()[string(ViewAutotag)] {
 		t.Error("autotag was switched on and should be visible")
 	}
 }
 // The stored map survives a save/load round trip, which is what a
 // map-valued TOML key is worth checking for.
 func TestViewVisibilityRoundTrips(t *testing.T) {
 	t.Parallel()
 	path := filepath.Join(t.TempDir(), "config.toml")
 	original := &Config{logger: slog.Default(), filePath: path}
 	if err := original.Load(); err != nil {
 		t.Fatalf("Load() error: %v", err)
 	}
 	if err := original.SetViewVisible(string(ViewAutotag), true); err != nil {
 		t.Fatalf("SetViewVisible() error: %v", err)
 	}
 	if err := original.SetViewVisible(string(ViewExplore), false); err != nil {
 		t.Fatalf("SetViewVisible() error: %v", err)
 	}
 	loaded := &Config{logger: slog.Default(), filePath: path}
 	if err := loaded.Load(); err != nil {
 		t.Fatalf("Load() error: %v", err)
 	}
 	resolved := loaded.GetViewVisibility()
 	if !resolved[string(ViewAutotag)] {
 		t.Error("autotag should have loaded as visible")
 	}
 	if resolved[string(ViewExplore)] {
 		t.Error("explore should have loaded as hidden")
 	}
 }
 // Every view the shell can launch into is a view the sidebar can show,
 // or an install could land on a page with no nav item and no setting
 // pointing at it.
 func TestEveryLaunchableViewIsAView(t *testing.T) {
 	t.Parallel()
 	for _, v := range Views {
 		if !v.CanLaunch {
 			continue
 		}
 		if !v.Hideable {
 			continue
 		}
 		if _, ok := LookupView(string(v.ID)); !ok {
 			t.Errorf("%s is launchable but not a known view", v.ID)
 		}
 	}
 }
@@ -13,31 +13,13 @@ const (
 	// enforces this at runtime; it is also the floor below which a
 	// reported size is treated as bogus and not persisted.
 	//
-	// **Both reasons this comment used to give have expired**, and the
+	// 800x600 is where the shell was measured to still work, rather
-	// value is right for a third one.  It said the floor was 800x600
+	// than a round number: below ~780 the header's subtitle wraps and
-	// because "below ~780 the header's subtitle wraps and pushes the
+	// pushes the title out of the 4em top bar, and below ~600 tall the
-	// title out of the 4em top bar" and "below ~600 tall the eleven
+	// eleven sidebar items no longer fit at once.  The previous
-	// sidebar items no longer fit at once".  Neither mechanism can
+	// 512x384 was aspirational — at 700x480 the sidebar overflowed
-	// happen now: the subtitle is display:none from 899px down
+	// behind the player bar with no scroll and Settings and Jobs could
-	// (index.css), and the sidebar host is overflow-y:auto — measured
+	// not be reached at all.
 	// at 600x460, its scrollHeight is 434 against a 332px client and
 	// Settings is reachable after scrolling.  A floor defended by two
 	// mechanisms that no longer exist is a number nobody can argue
 	// with, which is worse than either answer.
 	//
 	// It stays 800x600 because that is where the *desktop* chrome
 	// stops being comfortable — the Compact band of plan 018's size
 	// matrix (#24) — and not because the app breaks below it.  It does
 	// not: under 600px wide the phone layout takes over (bottom-nav,
 	// no sidebar) and the shell fits 320px exactly, which is what
 	// makes this a comfort floor rather than a correctness one, and
 	// why a very small window reflows instead of becoming a
 	// mini-player (#12 is a second always-on-top window, not a mode of
 	// this one).
 	//
 	// The previous 512x384 was aspirational — at 700x480 the sidebar
 	// overflowed behind the player bar with no scroll and Settings and
 	// Jobs could not be reached at all.
 	MinWidth = 800
 	// MinHeight is the smallest allowed window height in pixels.
 	MinHeight = 600
@@ -135,49 +135,3 @@ SELECT
    ) AS INTEGER) AS known
 FROM audio_files a
 WHERE a.album_id = sqlc.arg(album_id);
 -- name: GetAlbumsCompleteness :many
 -- The same question as GetAlbumCompleteness, asked of a screenful of
 -- albums at once.
 --
 -- A card grid cannot afford one query per card, and the answer it wants
 -- is the one thing a badge cannot guess: an album held 9 tracks of 12
 -- must show the count, never a bare tick.  So this is one query for the
 -- whole grid, asked only of the cards that have a local album id.
 --
 -- It is two grouping levels rather than the single-album form's
 -- correlated subqueries, because a correlated subquery in the FROM
 -- clause is not something SQLite will reliably do -- and because the
 -- slice may only be spelled once, or sqlc expands it twice with
 -- independently numbered placeholders.
 --
 -- The per-disc level is where the meaning is, and it is the same
 -- meaning as the single-album query.  `owned` counts DISTINCT track
 -- numbers within a disc (this app detects duplicates, and counting two
 -- files of track 3 twice would report a short album as complete), with
 -- a file that declares no track number falling back to its own id
 -- because three untagged files are three tracks and not one.
 -- `expected` takes each disc's declared total and sums over discs,
 -- since a total is declared per disc and a release total written on
 -- every file of a two-disc album would double its expectation.  A disc
 -- whose files declared nothing contributes a NULL that SUM ignores,
 -- and `known` is what says the album is therefore unanswerable.
 WITH per_disc AS (
    SELECT
        album_id AS album_id,
        COUNT(DISTINCT COALESCE(CAST(track_number AS TEXT), 'f' || id))
            AS owned_on_disc,
        MAX(total_tracks) AS disc_total,
        SUM(CASE WHEN total_tracks IS NULL THEN 1 ELSE 0 END)
            AS discs_without_a_total
    FROM audio_files
    WHERE album_id IN (sqlc.slice('album_ids'))
    GROUP BY album_id, COALESCE(disc_number, 1)
 )
 SELECT
    CAST(album_id AS INTEGER) AS album_id,
    CAST(SUM(owned_on_disc) AS INTEGER) AS owned,
    CAST(COALESCE(SUM(disc_total), 0) AS INTEGER) AS expected,
    CAST(SUM(discs_without_a_total) = 0 AS INTEGER) AS known
 FROM per_disc
 GROUP BY album_id;
@@ -342,35 +342,3 @@ WHERE ti.status = 'pending'
  )
 ORDER BY ti.group_key
 LIMIT 1;
 -- name: GetTaggingItemsForAlbum :many
 -- Every tagging group holding a file of this album.
 --
 -- The join is `audio_files.group_key`, not a key derived from the
 -- album's folder path: a group carved out of a mixed-bag folder by
 -- SplitMixedFolder is keyed on its tags rather than on a directory,
 -- so a path-derived key finds nothing for exactly the messiest
 -- libraries this is meant to help.
 --
 -- Usually one row. A multi-disc album is one group per disc, which
 -- the caller has to know about rather than average over -- applying
 -- to "the album" would silently retag one disc of three.
 SELECT
  ti.group_key,
  ti.status,
  ti.score,
  ti.best_match_release_mbid,
  ti.track_count,
  ti.album_name,
  ti.album_artist,
  ti.synthetic
 FROM tagging_items ti
 WHERE ti.group_key IN (
    SELECT DISTINCT af.group_key
    FROM audio_files af
    WHERE af.album_id = sqlc.arg(album_id) AND af.group_key != ''
  )
  AND ti.cleared_at IS NULL
 -- Best first, with an unscored group last rather than first: NULL
 -- sorts low in SQLite and DESC would put it at the top.
 ORDER BY ti.score IS NULL, ti.score DESC, ti.group_key;
@@ -8,7 +8,6 @@ package sqlcgen
 import (
 	"context"
 	"database/sql"
 	"strings"
 )
 const deleteAlbum = `-- name: DeleteAlbum :exec
@@ -235,98 +234,6 @@ func (q *Queries) GetAlbumsByArtistName(ctx context.Context, arg GetAlbumsByArti
 	return items, nil
 }
 const getAlbumsCompleteness = `-- name: GetAlbumsCompleteness :many
 WITH per_disc AS (
    SELECT
        album_id AS album_id,
        COUNT(DISTINCT COALESCE(CAST(track_number AS TEXT), 'f' || id))
            AS owned_on_disc,
        MAX(total_tracks) AS disc_total,
        SUM(CASE WHEN total_tracks IS NULL THEN 1 ELSE 0 END)
            AS discs_without_a_total
    FROM audio_files
    WHERE album_id IN (/*SLICE:album_ids*/?)
    GROUP BY album_id, COALESCE(disc_number, 1)
 )
 SELECT
    CAST(album_id AS INTEGER) AS album_id,
    CAST(SUM(owned_on_disc) AS INTEGER) AS owned,
    CAST(COALESCE(SUM(disc_total), 0) AS INTEGER) AS expected,
    CAST(SUM(discs_without_a_total) = 0 AS INTEGER) AS known
 FROM per_disc
 GROUP BY album_id
 `
 type GetAlbumsCompletenessRow struct {
 	AlbumID  int64
 	Owned    int64
 	Expected int64
 	Known    int64
 }
 // The same question as GetAlbumCompleteness, asked of a screenful of
 // albums at once.
 //
 // A card grid cannot afford one query per card, and the answer it wants
 // is the one thing a badge cannot guess: an album held 9 tracks of 12
 // must show the count, never a bare tick.  So this is one query for the
 // whole grid, asked only of the cards that have a local album id.
 //
 // It is two grouping levels rather than the single-album form's
 // correlated subqueries, because a correlated subquery in the FROM
 // clause is not something SQLite will reliably do -- and because the
 // slice may only be spelled once, or sqlc expands it twice with
 // independently numbered placeholders.
 //
 // The per-disc level is where the meaning is, and it is the same
 // meaning as the single-album query.  `owned` counts DISTINCT track
 // numbers within a disc (this app detects duplicates, and counting two
 // files of track 3 twice would report a short album as complete), with
 // a file that declares no track number falling back to its own id
 // because three untagged files are three tracks and not one.
 // `expected` takes each disc's declared total and sums over discs,
 // since a total is declared per disc and a release total written on
 // every file of a two-disc album would double its expectation.  A disc
 // whose files declared nothing contributes a NULL that SUM ignores,
 // and `known` is what says the album is therefore unanswerable.
 func (q *Queries) GetAlbumsCompleteness(ctx context.Context, albumIds []sql.NullInt64) ([]GetAlbumsCompletenessRow, error) {
 	query := getAlbumsCompleteness
 	var queryParams []interface{}
 	if len(albumIds) > 0 {
 		for _, v := range albumIds {
 			queryParams = append(queryParams, v)
 		}
 		query = strings.Replace(query, "/*SLICE:album_ids*/?", strings.Repeat(",?", len(albumIds))[1:], 1)
 	} else {
 		query = strings.Replace(query, "/*SLICE:album_ids*/?", "NULL", 1)
 	}
 	rows, err := q.db.QueryContext(ctx, query, queryParams...)
 	if err != nil {
 		return nil, err
 	}
 	defer rows.Close()
 	var items []GetAlbumsCompletenessRow
 	for rows.Next() {
 		var i GetAlbumsCompletenessRow
 		if err := rows.Scan(
 			&i.AlbumID,
 			&i.Owned,
 			&i.Expected,
 			&i.Known,
 		); err != nil {
 			return nil, err
 		}
 		items = append(items, i)
 	}
 	if err := rows.Close(); err != nil {
 		return nil, err
 	}
 	if err := rows.Err(); err != nil {
 		return nil, err
 	}
 	return items, nil
 }
 const getAlbumsWithPendingReleaseMBID = `-- name: GetAlbumsWithPendingReleaseMBID :many
 SELECT id, pending_release_mbid FROM albums
 WHERE pending_release_mbid IS NOT NULL AND pending_release_mbid != ''
@@ -231,82 +231,6 @@ func (q *Queries) GetTaggingItem(ctx context.Context, groupKey string) (TaggingI
 	return i, err
 }
 const getTaggingItemsForAlbum = `-- name: GetTaggingItemsForAlbum :many
 SELECT
  ti.group_key,
  ti.status,
  ti.score,
  ti.best_match_release_mbid,
  ti.track_count,
  ti.album_name,
  ti.album_artist,
  ti.synthetic
 FROM tagging_items ti
 WHERE ti.group_key IN (
    SELECT DISTINCT af.group_key
    FROM audio_files af
    WHERE af.album_id = ?1 AND af.group_key != ''
  )
  AND ti.cleared_at IS NULL
 ORDER BY ti.score IS NULL, ti.score DESC, ti.group_key
 `
 type GetTaggingItemsForAlbumRow struct {
 	GroupKey             string
 	Status               string
 	Score                sql.NullFloat64
 	BestMatchReleaseMbid sql.NullString
 	TrackCount           int64
 	AlbumName            string
 	AlbumArtist          string
 	Synthetic            int64
 }
 // Every tagging group holding a file of this album.
 //
 // The join is `audio_files.group_key`, not a key derived from the
 // album's folder path: a group carved out of a mixed-bag folder by
 // SplitMixedFolder is keyed on its tags rather than on a directory,
 // so a path-derived key finds nothing for exactly the messiest
 // libraries this is meant to help.
 //
 // Usually one row. A multi-disc album is one group per disc, which
 // the caller has to know about rather than average over -- applying
 // to "the album" would silently retag one disc of three.
 // Best first, with an unscored group last rather than first: NULL
 // sorts low in SQLite and DESC would put it at the top.
 func (q *Queries) GetTaggingItemsForAlbum(ctx context.Context, albumID sql.NullInt64) ([]GetTaggingItemsForAlbumRow, error) {
 	rows, err := q.db.QueryContext(ctx, getTaggingItemsForAlbum, albumID)
 	if err != nil {
 		return nil, err
 	}
 	defer rows.Close()
 	var items []GetTaggingItemsForAlbumRow
 	for rows.Next() {
 		var i GetTaggingItemsForAlbumRow
 		if err := rows.Scan(
 			&i.GroupKey,
 			&i.Status,
 			&i.Score,
 			&i.BestMatchReleaseMbid,
 			&i.TrackCount,
 			&i.AlbumName,
 			&i.AlbumArtist,
 			&i.Synthetic,
 		); err != nil {
 			return nil, err
 		}
 		items = append(items, i)
 	}
 	if err := rows.Close(); err != nil {
 		return nil, err
 	}
 	if err := rows.Err(); err != nil {
 		return nil, err
 	}
 	return items, nil
 }
 const listAudioFilesInTaggingGroup = `-- name: ListAudioFilesInTaggingGroup :many
 SELECT
  af.id,
@@ -34,29 +34,13 @@ type UserConfig struct {
 	// in one burst that every provider sees as a flood.
 	WantedBatch int `toml:"WantedBatch"`
-	// MinKbps, MaxKbps and PreferredKbps bound and nudge what auto-pick
+	// MinFileSizeMB, MaxFileSizeMB and PreferredFileSizeMB bound and
-	// (interactive or via the request list) may grab without asking.
+	// nudge what auto-pick (interactive or via the request list) may
-	// Zero on any of them is permissive: see AutoDownloadPrefs.
+	// grab without asking.  Zero on any of them is permissive: see
-	//
+	// AutoDownloadPrefs.
-	// They replaced MinFileSizeMB / MaxFileSizeMB /
+	MinFileSizeMB       int `toml:"MinFileSizeMB"`
-	// PreferredFileSizeMB, which were megabytes and so said nothing
+	MaxFileSizeMB       int `toml:"MaxFileSizeMB"`
-	// without knowing how long the release was.  The old keys are
+	PreferredFileSizeMB int `toml:"PreferredFileSizeMB"`
 	// deliberately *not* read back: a number that meant "300 MB" cannot
 	// be reinterpreted as a bitrate without knowing the album it was
 	// aimed at, so migrating it would be inventing an intent the user
 	// never expressed.  An existing config falls back to no window,
 	// which is the permissive default and matches a fresh install —
 	// and MaxFileSizeMB is the one that does carry over, because a
 	// ceiling on total bytes still means exactly what it did.
 	MinKbps       int `toml:"MinKbps"`
 	MaxKbps       int `toml:"MaxKbps"`
 	PreferredKbps int `toml:"PreferredKbps"`
 	// MaxFileSizeMB is a hard ceiling on a candidate's total size, kept
 	// in megabytes on purpose — it is a question about disk space, not
 	// about quality, and it has to apply to a candidate whose bitrate
 	// cannot be worked out at all.
 	MaxFileSizeMB int `toml:"MaxFileSizeMB"`
 	// AllowedFormats restricts auto-pick to these formats.  Empty means
 	// no restriction.  Values are Format strings ("flac", "mp3", ...).
@@ -72,11 +56,10 @@ func (c *UserConfig) AutoDownloadPrefs() AutoDownloadPrefs {
 	}
 	return AutoDownloadPrefs{
-		MinKbps:        c.MinKbps,
+		MinSizeMB:       c.MinFileSizeMB,
-		MaxKbps:        c.MaxKbps,
+		MaxSizeMB:       c.MaxFileSizeMB,
-		PreferredKbps:  c.PreferredKbps,
+		PreferredSizeMB: c.PreferredFileSizeMB,
-		MaxSizeMB:      c.MaxFileSizeMB,
+		AllowedFormats:  formats,
 		AllowedFormats: formats,
 	}
 }
@@ -12,7 +12,6 @@ import (
 	"strconv"
 	"strings"
 	"yellowjacket/backend/tagtotals"
 	"yellowjacket/backend/tagwriter"
 )
@@ -276,25 +275,6 @@ func (i *Importer) tagFile(p plannedFile, dl Download) error {
 		changes[tagwriter.FieldDiscNumber] = p.Track.DiscNumber
 	}
 	// An imported file should arrive knowing how much of the album it
 	// is one of, or the album reads as "in your library" from its first
 	// imported track onward.
 	//
 	// A *track* download is the case this must not touch: a
 	// RecordingMBID anchor resolves Expected to exactly that one track,
 	// so totalling it would write "1 of 1" onto a track off a
 	// twelve-track album -- a confident lie, and one that outranks the
 	// catalog's own total, which is the fallback that would otherwise
 	// have answered correctly.
 	if dl.RecordingMBID == "" {
 		if tracks, discs := tagtotals.For(
 			expectedPositions(dl.Expected), p.Track.DiscNumber,
 		); tracks > 0 {
 			changes[tagwriter.FieldTotalTracks] = tracks
 			changes[tagwriter.FieldTotalDiscs] = discs
 		}
 	}
 	if err := i.tags.WriteUntrackedFileTags(p.Source, changes); err != nil {
 		return fmt.Errorf("write tags: %w", err)
 	}
@@ -302,18 +282,6 @@ func (i *Importer) tagFile(p plannedFile, dl Download) error {
 	return nil
 }
 // expectedPositions is the download's resolved tracklist as bare
 // positions.
 func expectedPositions(expected []ExpectedTrack) []tagtotals.Position {
 	out := make([]tagtotals.Position, 0, len(expected))
 	for _, t := range expected {
 		out = append(out, tagtotals.Position{Disc: t.DiscNumber, Track: t.Position})
 	}
 	return out
 }
 // destinationFor computes a file's library path from the template.
 func (i *Importer) destinationFor(
 	p plannedFile,
@@ -446,77 +446,3 @@ func keysOf(m map[string]tagwriter.TagChanges) []string {
 	return out
 }
 // An imported album should arrive knowing its own size, or the album
 // page reads "in your library" from its first imported track onward --
 // which is the badge complaint this exists to answer.
 func TestImportWritesTheAlbumTotals(t *testing.T) {
 	t.Parallel()
 	f := newImportFixture(t,
 		"01 - Airbag.flac",
 		"02 - Paranoid Android.flac",
 		"03 - Subterranean Homesick Alien.flac",
 		"04 - Exit Music (For a Film).flac",
 	)
 	if _, err := f.importer.Import(
 		context.Background(),
 		fourTrackDownload(),
 		Result{Dir: f.dir, Files: f.files},
 		ImportOptions{LibraryRoot: f.root, WriteTags: true},
 	); err != nil {
 		t.Fatalf("Import: %v", err)
 	}
 	changes := f.tags.writes["01 - Airbag.flac"]
 	if changes == nil {
 		t.Fatal("no tag write recorded for the first track")
 	}
 	if got := changes[tagwriter.FieldTotalTracks]; got != 4 {
 		t.Errorf("%s: got %v, want 4", tagwriter.FieldTotalTracks, got)
 	}
 	if got := changes[tagwriter.FieldTotalDiscs]; got != 1 {
 		t.Errorf("%s: got %v, want 1", tagwriter.FieldTotalDiscs, got)
 	}
 }
 // A RecordingMBID anchor resolves Expected to exactly the one track it
 // asked for, so totalling it would tag a track off a twelve-track album
 // as "1 of 1" -- worse than saying nothing, because a declared total
 // outranks the catalog total that would have answered correctly.
 func TestImportWritesNoTotalsForATrackDownload(t *testing.T) {
 	t.Parallel()
 	f := newImportFixture(t, "01 - Airbag.flac")
 	dl := Download{
 		ID:            "dl-track",
 		LibraryID:     1,
 		RecordingMBID: "mbid-recording",
 		Artist:        "Radiohead",
 		Album:         "OK Computer",
 		Expected:      []ExpectedTrack{{Position: 1, Title: "Airbag"}},
 	}
 	if _, err := f.importer.Import(
 		context.Background(),
 		dl,
 		Result{Dir: f.dir, Files: f.files},
 		ImportOptions{LibraryRoot: f.root, WriteTags: true},
 	); err != nil {
 		t.Fatalf("Import: %v", err)
 	}
 	changes := f.tags.writes["01 - Airbag.flac"]
 	if changes == nil {
 		t.Fatal("no tag write recorded")
 	}
 	if _, ok := changes[tagwriter.FieldTotalTracks]; ok {
 		t.Errorf("%s written for a single-track download: %v",
 			tagwriter.FieldTotalTracks, changes[tagwriter.FieldTotalTracks])
 	}
 }
@@ -236,12 +236,6 @@ func (m *Manager) AutoPickable(dl Download, ranked []Candidate) bool {
 	return AutoPickable(dl, ranked, m.preferences())
 }
 // AutoPickVeto wraps the package function the same way, and is what the
 // request list quotes back to the user.
 func (m *Manager) AutoPickVeto(dl Download, ranked []Candidate) string {
 	return AutoPickVeto(dl, ranked, m.preferences())
 }
 // Reload rebuilds every provider from stored config.  Called at startup
 // and after any provider settings change.
 //
@@ -618,8 +612,16 @@ func (m *Manager) Attempt(
 		return false, "", err
 	}
-	if veto := m.AutoPickVeto(dl, ranked); veto != "" {
+	if !m.AutoPickable(dl, ranked) {
-		return false, veto, nil
+		best := ranked[0]
 		return false, fmt.Sprintf(
 			"best of %d found is not a confident enough match "+
 				"(match %.0f%%, quality %.0f%%)",
 			len(ranked),
 			best.Match.Overall*100, //nolint:mnd // percent
 			best.Quality.Overall*100,
 		), nil
 	}
 	if err := m.store.CreateDownload(ctx, dl); err != nil {
@@ -218,17 +218,8 @@ func TestManagerEndToEndAutoPick(t *testing.T) {
 	}, "staging was never released, or the library was never rescanned")
 }
-// Two equally good copies are not an ambiguity — they are a spare.
+// An ambiguous result set must park for the user rather than guess.
-//
+func TestManagerWaitsWhenAmbiguous(t *testing.T) {
 // This asserted the opposite for as long as auto-pick required 0.08 of
 // daylight over the runner-up, and that rule was wrong in exactly the
 // case it fired hardest: a popular album turns up several *correct*
 // copies, all matching the tracklist, differing only in format and
 // seeders. There is no question there about what to fetch, only about
 // which copy, and the ranking already answers that — closest to the
 // preferred bitrate first. A candidate does not have to be better than
 // the field, only good enough on its own terms.
 func TestManagerAutoPicksAmongEquallyGoodCopies(t *testing.T) {
 	t.Parallel()
 	f := newManagerFixture(t)
@@ -246,41 +237,11 @@ func TestManagerAutoPicksAmongEquallyGoodCopies(t *testing.T) {
 		t.Fatalf("Start: %v", err)
 	}
-	if veto := f.manager.AutoPickVeto(dl, ranked); veto != "" {
+	if f.manager.AutoPickable(dl, ranked) {
-		t.Fatalf("two equally good copies must auto-pick, got veto: %s", veto)
+		t.Fatal("two equivalent candidates must not auto-pick")
 	}
 	waitForDownloadState(t, f.store, dl.ID, StateComplete)
 	// Exactly one of them was fetched, not both.
 	if grabs := a.GrabCalls + b.GrabCalls; grabs != 1 {
 		t.Errorf("grabs = %d, want exactly 1", grabs)
 	}
 }
 // The user can still pick explicitly when auto-pick is not what
 // happened — a candidate the ranking did not choose is still grabbable.
 func TestManagerPickIsExplicit(t *testing.T) {
 	t.Parallel()
 	f := newManagerFixture(t)
 	a := fakeWithAlbum(1, "source-a", ".flac")
 	b := fakeWithAlbum(2, "source-b", ".flac")
 	f.manager.installProvider(Config{ID: 1, Priority: 50}, a)
 	f.manager.installProvider(Config{ID: 2, Priority: 50}, b)
 	// No tracklist: never auto-picks, so the result set parks for the
 	// user and Pick is the only way anything is fetched.
 	dl := fourTrackDownload()
 	dl.Expected = nil
 	ranked, err := f.manager.Start(context.Background(), dl)
 	if err != nil {
 		t.Fatalf("Start: %v", err)
 	}
 	// Nothing was grabbed while waiting for the user.
 	if a.GrabCalls != 0 || b.GrabCalls != 0 {
 		t.Errorf(
 			"grabs happened without a pick: a=%d b=%d",
@@ -297,6 +258,7 @@ func TestManagerPickIsExplicit(t *testing.T) {
 		t.Errorf("stored request id = %s, want %s", stored.ID, dl.ID)
 	}
 	// The user picks the second one explicitly.
 	if err := f.manager.Pick(
 		context.Background(), dl.ID, ranked[1].ID,
 	); err != nil {
@@ -1,7 +1,6 @@
 package download
 import (
 	"fmt"
 	"math"
 	"sort"
 	"strings"
@@ -35,103 +34,39 @@ const (
 	weightArtistFit    = 0.12
 )
-// Quality sub-weights.  Each set sums to 1.0.
+// Quality sub-weights.  They sum to 1.0 along with weightSizeFit below.
 //
 // There are two of them because a stated preference changes what the
 // other numbers are *for*.  `formatRank` and `bitrateScore` are the
 // app guessing at how good a copy is — FLAC over MP3, 320 over 128 —
 // and that guess exists precisely because the user has not said.  Once
 // they have, the guess should not outvote them: with the old single set
 // a preference of 320 kbps moved a candidate's score by at most 0.05
 // against the 0.42 riding on format, so asking for 320 and being handed
 // a FLAC every time was the *designed* behaviour.  That is the same
 // fault the megabyte window had — a preference the user can express and
 // the ranking can ignore.
 const (
-	weightFormat     = 0.42
+	weightFormat   = 0.42
-	weightBitrate    = 0.23
+	weightBitrate  = 0.23
-	weightHealth     = 0.20
+	weightHealth   = 0.20
-	weightPriority   = 0.10
+	weightPriority = 0.10
-	weightBitrateFit = 0.05
+	weightSizeFit  = 0.05
 )
 // Quality sub-weights when the user has named a preferred bitrate.
 // The weight comes off format and bitrate — the two proxies the
 // preference replaces — and health and priority are untouched, since
 // neither is a stand-in for anything the user just said.
 const (
 	statedWeightFormat     = 0.20
 	statedWeightBitrate    = 0.10
 	statedWeightHealth     = 0.20
 	statedWeightPriority   = 0.10
 	statedWeightBitrateFit = 0.40
 )
 // qualityWeights picks the set, in the order scoreQuality applies them.
 func qualityWeights(p AutoDownloadPrefs) (
 	format, bitrate, health, priority, fit float64,
 ) {
 	if p.PreferredKbps > 0 {
 		return statedWeightFormat,
 			statedWeightBitrate,
 			statedWeightHealth,
 			statedWeightPriority,
 			statedWeightBitrateFit
 	}
 	return weightFormat,
 		weightBitrate,
 		weightHealth,
 		weightPriority,
 		weightBitrateFit
 }
 // unanchoredCap bounds the match score of a free-text request.  Without
 // an MBID there is no tracklist to be right about, so a confident-
 // looking score would be a lie — and auto-pick keys off this.
 const unanchoredCap = 0.65
 // AutoDownloadPrefs gates and scores what AutoPickable may choose
-// without asking.  Zero values are permissive: no bitrate window, no
+// without asking.  Zero values are permissive: no size window and no
-// size ceiling and no format restriction.
+// format restriction.
 //
 // **The window is a rate, not a size.**  It used to be three numbers in
 // megabytes, which cannot mean anything on their own: 300 MB is a
 // generous FLAC single and a suspiciously small boxset, and the user
 // setting the number has no idea which release the pipeline will
 // eventually apply it to.  A bitrate is the same statement normalised
 // by how long the music is, so one number holds across a 9-minute EP
 // and a 3-hour opera — and it is the unit the thing being described is
 // actually measured in.  The runtime is known for every request
 // auto-pick can act on (`Download.Expected` carries per-track lengths,
 // and an anchored request is the only kind that reaches here), so this
 // costs no extra lookup.
 type AutoDownloadPrefs struct {
-	// MinKbps and MaxKbps bound the average bitrate auto-pick will
+	// MinSizeMB and MaxSizeMB bound what auto-pick will grab.  Zero
-	// grab.  Zero means no bound on that side.  A candidate outside the
+	// means no bound on that side.  A candidate outside the window is
-	// window is filtered out of auto-pick entirely, not merely scored
+	// filtered out of auto-pick entirely, not merely scored down — a
-	// down — a 96 kbps rip of the right album is not a worse copy the
+	// tiny "sampler" torrent or a boxset ten times the expected size is
-	// user might accept, it is one they said not to take unattended.
+	// usually the wrong thing entirely, not a worse copy of the right
-	//
+	// thing.
-	// For reference: 320 is the top of MP3, ~500–1000 is FLAC depending
+	MinSizeMB int `json:"minSizeMb"`
 	// on the material, and anything under ~128 is a transcode.
 	MinKbps int `json:"minKbps"`
 	MaxKbps int `json:"maxKbps"`
 	// PreferredKbps nudges the score toward a target rate within the
 	// window, and breaks the tie when several candidates are equally
 	// good matches.  Zero disables the nudge; bitrateFit then returns a
 	// neutral value that does not affect ranking.
 	PreferredKbps int `json:"preferredKbps"`
 	// MaxSizeMB is a hard ceiling on the whole candidate, and it is
 	// deliberately still a size.  It answers a different question from
 	// the window above — not "is this the quality I want" but "is this
 	// going to fill the disk" — and it has to hold even for a candidate
 	// whose bitrate cannot be worked out, which is exactly the shape a
 	// mislabelled boxset arrives in.  Zero means no ceiling.
 	MaxSizeMB int `json:"maxSizeMb"`
 	// PreferredSizeMB nudges the score toward a target size within the
 	// min/max window (a lossless rip and a heavily-padded lossless rip
 	// can both pass the window).  Zero disables the nudge; sizeFit then
 	// returns a neutral value that does not affect ranking.
 	PreferredSizeMB int `json:"preferredSizeMb"`
 	// AllowedFormats restricts auto-pick to candidates whose audio
 	// files are all in one of these formats.  Empty means no
 	// restriction.
@@ -139,31 +74,17 @@ type AutoDownloadPrefs struct {
 }
 // eligible reports whether a candidate may be auto-picked under these
-// preferences: inside the bitrate window and the size ceiling (when
+// preferences: within the size window (when set) and, when a format
-// set) and, when a format list is given, every audio file in an
+// list is given, every audio file in an allowed format.
-// allowed format.
+func (p AutoDownloadPrefs) eligible(c Candidate) bool {
 //
 // `runtimeMillis` is how long the requested release is, and 0 means
 // nobody knows.  An unknown runtime **passes** the bitrate window
 // rather than failing it: the window is a statement about quality, and
 // refusing everything the moment a tracklist is missing a length would
 // turn a gap in MusicBrainz into a silent embargo.  The size ceiling
 // still applies, which is why it exists separately.
 func (p AutoDownloadPrefs) eligible(c Candidate, runtimeMillis int64) bool {
 	const bytesPerMB = 1 << 20
-	if p.MaxSizeMB > 0 && c.TotalSize > int64(p.MaxSizeMB)*bytesPerMB {
+	if p.MinSizeMB > 0 && c.TotalSize < int64(p.MinSizeMB)*bytesPerMB {
 		return false
 	}
-	if kbps := candidateKbps(c, runtimeMillis); kbps > 0 {
+	if p.MaxSizeMB > 0 && c.TotalSize > int64(p.MaxSizeMB)*bytesPerMB {
-		if p.MinKbps > 0 && kbps < float64(p.MinKbps) {
+		return false
 			return false
 		}
 		if p.MaxKbps > 0 && kbps > float64(p.MaxKbps) {
 			return false
 		}
 	}
 	if len(p.AllowedFormats) == 0 {
@@ -186,14 +107,11 @@ func (p AutoDownloadPrefs) eligible(c Candidate, runtimeMillis int64) bool {
 // filter returns only the candidates these preferences allow to be
 // auto-picked, in the same (already ranked) order.
-func (p AutoDownloadPrefs) filter(
+func (p AutoDownloadPrefs) filter(ranked []Candidate) []Candidate {
 	ranked []Candidate,
 	runtimeMillis int64,
 ) []Candidate {
 	out := make([]Candidate, 0, len(ranked))
 	for _, c := range ranked {
-		if p.eligible(c, runtimeMillis) {
+		if p.eligible(c) {
 			out = append(out, c)
 		}
 	}
@@ -201,116 +119,32 @@ func (p AutoDownloadPrefs) filter(
 	return out
 }
-// bitrateFit scores how close a candidate's average bitrate is to
+// sizeFit scores how close totalSize is to PreferredSizeMB, 0..1,
-// PreferredKbps, falling off linearly as it doubles or halves away
+// falling off linearly as the size doubles or halves away from it.
-// from it.
+// Returns a neutral 0.5 when no preference is set, so the absence of a
-//
+// preference does not bias ranking.
-// The range is **0.5 to 1.0, not 0 to 1**, and the floor is the point.
+func (p AutoDownloadPrefs) sizeFit(totalSize int64) float64 {
 // This carries 0.40 of the quality score once a preference is set, so a
 // span down to zero would let a preference of 320 kbps push a perfectly
 // good FLAC under `minQuality` and out of auto-pick altogether —
 // turning "I like 320" into "never take anything else", silently.  A
 // preference may promote the copy that matches it; it may not
 // disqualify the others.  That is what `MinKbps`/`MaxKbps` are for, and
 // they say so out loud.
 //
 // Returns the neutral floor when no preference is set or the rate
 // cannot be worked out, so neither an absent preference nor an absent
 // runtime biases ranking.
 func (p AutoDownloadPrefs) bitrateFit(
 	c Candidate,
 	runtimeMillis int64,
 ) float64 {
 	const (
-		neutral = 0.5
+		bytesPerMB = 1 << 20
-		span    = 0.5
+		neutral    = 0.5
 	)
-	if p.PreferredKbps <= 0 {
+	if p.PreferredSizeMB <= 0 || totalSize <= 0 {
 		return neutral
 	}
-	kbps := candidateKbps(c, runtimeMillis)
+	preferred := float64(p.PreferredSizeMB) * bytesPerMB
-	if kbps <= 0 {
+	ratio := float64(totalSize) / preferred
 		return neutral
 	}
 	ratio := kbps / float64(p.PreferredKbps)
 	if ratio < 1 {
 		ratio = 1 / ratio
 	}
 	// ratio is now >= 1: 1.0 is an exact match, 2.0 is double or half
-	// the preferred rate, where the closeness term reaches 0.
+	// the preferred size.  Falls to 0 at 2x away and beyond.
-	return neutral + span*clamp01(1-(ratio-1))
+	fit := 1 - (ratio - 1)
 }
-// candidateKbps is a candidate's average audio bitrate, or 0 when it
+	return clamp01(fit)
 // cannot be worked out.
 //
 // Two sources, in this order, and the order matters:
 //
 //   - **Derived from bytes over runtime**, which is the honest one. It
 //     covers lossless (where a stated bitrate rarely exists), it cannot
 //     be lied to by a filename, and it is what the user's window means.
 //     Only the *audio* files count: cover scans and a log file are not
 //     part of the bitrate, and a folder with 30 MB of artwork would
 //     otherwise read as a better rip than the same music without it.
 //   - **The mean stated bitrate**, when the runtime is unknown. Weaker
 //     — a provider that parses it from an MP3 header states it and one
 //     that guesses from the filename also "states" it — but a number
 //     from the file itself beats no number at all.
 func candidateKbps(c Candidate, runtimeMillis int64) float64 {
 	const bitsPerByte = 8
 	audio := c.AudioFiles()
 	if len(audio) == 0 {
 		return 0
 	}
 	if runtimeMillis > 0 {
 		var bytes int64
 		for _, f := range audio {
 			bytes += f.Size
 		}
 		if bytes > 0 {
 			// bytes×8 bits over seconds, expressed in kbps: the two
 			// factors of 1000 (millis→seconds, bits→kilobits) cancel.
 			return float64(bytes) * bitsPerByte /
 				float64(runtimeMillis)
 		}
 	}
 	var (
 		sum   int
 		count int
 	)
 	for _, f := range audio {
 		if f.Bitrate > 0 {
 			sum += f.Bitrate
 			count++
 		}
 	}
 	if count == 0 {
 		return 0
 	}
 	return float64(sum) / float64(count)
 }
 // runtimeMillis is how long the requested release is, summed over its
 // expected tracklist.  Zero when the tracklist is absent or carries no
 // lengths, which is what every caller here treats as "unknown".
 func (d Download) runtimeMillis() int64 {
 	var total int64
 	for _, t := range d.Expected {
 		total += t.LengthMillis
 	}
 	return total
 }
 // Score fills a candidate's Match, Quality and Score fields.
@@ -326,9 +160,7 @@ func Score(dl Download, c Candidate, priority int, prefs AutoDownloadPrefs) Cand
 	c.Files = mergeMatched(c.Files, matched)
 	c.Match = scoreMatch(dl, c, audio, titleFit)
-	c.Quality = scoreQuality(
+	c.Quality = scoreQuality(c, audio, priority, prefs)
 		c, audio, priority, prefs, dl.runtimeMillis(),
 	)
 	c.Score = weightMatch*c.Match.Overall + weightQuality*c.Quality.Overall
@@ -447,12 +279,11 @@ func scoreQuality(
 	audio []CandidateFile,
 	priority int,
 	prefs AutoDownloadPrefs,
 	runtimeMillis int64,
 ) QualityScore {
 	q := QualityScore{
-		Health:     clamp01(c.Health),
+		Health:   clamp01(c.Health),
-		Priority:   clamp01(float64(priority) / 100.0),
+		Priority: clamp01(float64(priority) / 100.0),
-		BitrateFit: prefs.bitrateFit(c, runtimeMillis),
+		SizeFit:  prefs.sizeFit(c.TotalSize),
 	}
 	if len(audio) == 0 {
@@ -479,13 +310,11 @@ func scoreQuality(
 	q.FormatRank = worst
 	q.Bitrate = bitrateScore(audio)
-	wFormat, wBitrate, wHealth, wPriority, wFit := qualityWeights(prefs)
+	q.Overall = weightFormat*q.FormatRank +
-
+		weightBitrate*q.Bitrate +
-	q.Overall = wFormat*q.FormatRank +
+		weightHealth*q.Health +
-		wBitrate*q.Bitrate +
+		weightPriority*q.Priority +
-		wHealth*q.Health +
+		weightSizeFit*q.SizeFit
 		wPriority*q.Priority +
 		wFit*q.BitrateFit
 	if q.Mixed {
 		q.Overall *= 0.9
@@ -615,19 +444,6 @@ func Rank(
 			return out[i].Match.Overall > out[j].Match.Overall
 		}
 		// Closest to the preferred bitrate wins the tie.
 		//
 		// This is what decides which copy is taken now that auto-pick
 		// no longer requires the winner to be clear of the field: when
 		// several candidates are equally good matches of equal overall
 		// quality, the one the user said they wanted the shape of is
 		// the answer, ahead of provider priority.  With no preference
 		// set every BitrateFit is the same neutral value and this
 		// falls through, exactly as before.
 		if out[i].Quality.BitrateFit != out[j].Quality.BitrateFit {
 			return out[i].Quality.BitrateFit > out[j].Quality.BitrateFit
 		}
 		if out[i].Quality.Priority != out[j].Quality.Priority {
 			return out[i].Quality.Priority > out[j].Quality.Priority
 		}
@@ -638,58 +454,19 @@ func Rank(
 	return out
 }
-// Auto-pick gates.  Named rather than inlined because AutoPickVeto
+// AutoPickable reports whether a ranked list has a clear enough winner
-// reports which of them refused, and a number in a sentence the user
+// to grab without asking.  It demands an anchored request, a high match,
-// reads should be the same number the decision used.
+// decent quality, and daylight between first and second place — if two
-const (
+// candidates are close, the choice is the user's.
 	minMatch   = 0.85
 	minQuality = 0.5
 )
 // AutoPickable reports whether a ranked list has a candidate worth
 // grabbing without asking: an anchored request with a tracklist behind
 // it, and a candidate that clears the match and quality bars inside the
 // user's guardrails.
 //
 // **It does not require the winner to be better than the runner-up.**
 // It used to demand 0.08 of daylight on the combined score, which meant
 // the check fired hardest in the case it was never written for: a
 // popular album turns up five *correct* copies, all matching the
 // tracklist at 95%+ and differing only in format and seeders, their
 // scores land within a point of each other, and auto-pick refused
 // forever on the grounds that the choice was the user's.  It was not.
 // There was no question about *what* to fetch, only about which copy —
 // and abundance is the one condition under which that question matters
 // least.  A candidate does not need to be the best one, only one that
 // meets the criteria; where several do, `Rank` puts the one closest to
 // the preferred bitrate first.
 func AutoPickable(dl Download, ranked []Candidate, prefs AutoDownloadPrefs) bool {
-	return AutoPickVeto(dl, ranked, prefs) == ""
+	const (
-}
+		minMatch   = 0.85
 		minQuality = 0.5
 		minLead    = 0.08
 	)
-// AutoPickVeto returns the reason auto-pick declined, or "" when it
+	if !dl.Anchored() || len(ranked) == 0 {
-// would go ahead.
+		return false
 //
 // It exists because "it rejected all of them" was indistinguishable
 // from "it found nothing good".  The request list's message was built
 // from `ranked[0]` — the best candidate *before* the size and format
 // guardrails, and before the lead check — so a request refused because
 // the user's maximum size excluded every copy, or because three equally
 // good copies were found, reported "best of 12 found is not a confident
 // enough match (match 96%, quality 88%)".  Numbers that clear both
 // thresholds, beside a refusal, is a message that teaches the user the
 // matcher is broken.  Each gate names itself now.
 func AutoPickVeto(
 	dl Download,
 	ranked []Candidate,
 	prefs AutoDownloadPrefs,
 ) string {
 	if len(ranked) == 0 {
 		return "nothing found"
 	}
 	if !dl.Anchored() {
 		return "the request is free text, so there is no release to be right about"
 	}
 	// An anchor with no tracklist behind it is an anchor in name only:
@@ -697,42 +474,29 @@ func AutoPickVeto(
 	// is exactly the evidence a wrong-album candidate also has.  This
 	// matters most for the request list, where nobody is watching.
 	if len(dl.Expected) == 0 {
-		return "no tracklist for this release is known yet, so a candidate cannot be checked against it"
+		return false
 	}
-	// The guardrails apply before the match and quality checks: a
+	// The guardrails apply before the match/quality/lead checks: a
-	// candidate outside the allowed bitrate, size or format is not a
+	// candidate outside the allowed size or format is not a worse
-	// worse choice, it is not a choice auto-pick may make at all, so it
+	// choice, it is not a choice auto-pick may make at all, so it must
-	// must not count as "the winner" either.
+	// not count as "the winner" nor as "second place" for the lead
-	eligible := prefs.filter(ranked, dl.runtimeMillis())
+	// check below.
 	eligible := prefs.filter(ranked)
 	if len(eligible) == 0 {
-		return fmt.Sprintf(
+		return false
 			"all %d found are outside the auto-download bitrate, size or format limits",
 			len(ranked),
 		)
 	}
 	best := eligible[0]
-
+	if best.Match.Overall < minMatch || best.Quality.Overall < minQuality {
-	if best.Match.Overall < minMatch {
+		return false
 		return fmt.Sprintf(
 			"best of %d found matches this release only %.0f%% (needs %.0f%%)",
 			len(ranked),
 			best.Match.Overall*100, //nolint:mnd // percent
 			minMatch*100,           //nolint:mnd // percent
 		)
 	}
-	if best.Quality.Overall < minQuality {
+	if len(eligible) > 1 && best.Score-eligible[1].Score < minLead {
-		return fmt.Sprintf(
+		return false
 			"best of %d found is the right release but scores %.0f%% on quality (needs %.0f%%)",
 			len(ranked),
 			best.Quality.Overall*100, //nolint:mnd // percent
 			minQuality*100,           //nolint:mnd // percent
 		)
 	}
-	return ""
+	return true
 }
 // mergeMatched copies MatchedTo assignments from the audio-only slice
@@ -1,34 +1,6 @@
 package download
-import (
+import "testing"
 	"strings"
 	"testing"
 )
 // trackMillis is five minutes; okComputer's four of them make a
 // twenty-minute release, which is what turns a candidate's byte count
 // into a bitrate the assertions below can name.
 const trackMillis = 5 * 60 * 1000
 // okComputerRuntime is that release's runtime, for the helpers that
 // need it directly.
 const okComputerRuntime = 4 * trackMillis
 // kbpsCandidate builds an annotated candidate whose audio adds up to
 // the given average bitrate over okComputer's runtime.
 func kbpsCandidate(id, ext string, kbps int) Candidate {
 	// bits = kbps × 1000 × (runtimeMillis / 1000), so the thousands
 	// cancel and the byte count is kbps × runtimeMillis / 8.
 	const bitsPerByte = 8
 	total := int64(kbps) * okComputerRuntime / bitsPerByte
 	c := candidateFor(id, allTitles(), ext, total/int64(len(allTitles())))
 	c.Files = AnnotateFiles(c.Files)
 	c.TotalSize = total
 	return c
 }
 // okComputer is the reference request used across ranking tests.
 func okComputer() Download {
@@ -36,15 +8,11 @@ func okComputer() Download {
 		ReleaseMBID: "mbid-ok-computer",
 		Artist:      "Radiohead",
 		Album:       "OK Computer",
 		// Four five-minute tracks: twenty minutes, so a candidate's
 		// bitrate is a number these tests can state exactly. Without
 		// lengths there is no runtime and the bitrate window has
 		// nothing to divide by.
 		Expected: []ExpectedTrack{
-			{Position: 1, Title: "Airbag", LengthMillis: trackMillis},
+			{Position: 1, Title: "Airbag"},
-			{Position: 2, Title: "Paranoid Android", LengthMillis: trackMillis},
+			{Position: 2, Title: "Paranoid Android"},
-			{Position: 3, Title: "Subterranean Homesick Alien", LengthMillis: trackMillis},
+			{Position: 3, Title: "Subterranean Homesick Alien"},
-			{Position: 4, Title: "Exit Music (For a Film)", LengthMillis: trackMillis},
+			{Position: 4, Title: "Exit Music (For a Film)"},
 		},
 	}
 }
@@ -219,7 +187,7 @@ func TestUnanchoredMatchIsCapped(t *testing.T) {
 	}
 }
-func TestAutoPickableRequiresAnchorAndTracklist(t *testing.T) {
+func TestAutoPickableRequiresAnchorAndLead(t *testing.T) {
 	t.Parallel()
 	dl := okComputer()
@@ -243,18 +211,14 @@ func TestAutoPickableRequiresAnchorAndTracklist(t *testing.T) {
 		}
 	})
-	// Two identical copies are a spare, not an ambiguity. This
+	t.Run("two close candidates are not", func(t *testing.T) {
 	// asserted the opposite while auto-pick required daylight over the
 	// runner-up — a rule that made abundance the thing that stopped a
 	// request being satisfied, which is backwards.
 	t.Run("two equally good candidates still are", func(t *testing.T) {
 		t.Parallel()
 		twin := best
 		twin.ID = "twin"
-		if !AutoPickable(dl, []Candidate{best, twin}, AutoDownloadPrefs{}) {
+		if AutoPickable(dl, []Candidate{best, twin}, AutoDownloadPrefs{}) {
-			t.Error("identical good candidates must auto-pick")
+			t.Error("identical candidates must not auto-pick")
 		}
 	})
@@ -336,11 +300,18 @@ func TestProviderPriorityBreaksTies(t *testing.T) {
 	}
 }
 const mb = 1 << 20
 func TestAutoDownloadPrefsEligible(t *testing.T) {
 	t.Parallel()
-	flacCandidate := kbpsCandidate("c", ".flac", 900)
+	flacCandidate := candidateFor("c", allTitles(), ".flac", 30_000_000)
-	mp3Candidate := kbpsCandidate("c", ".mp3", 128)
+	flacCandidate.Files = AnnotateFiles(flacCandidate.Files)
 	flacCandidate.TotalSize = 300 * mb
 	mp3Candidate := candidateFor("c", allTitles(), ".mp3", 3_000_000)
 	mp3Candidate.Files = AnnotateFiles(mp3Candidate.Files)
 	mp3Candidate.TotalSize = 30 * mb
 	tests := []struct {
 		name  string
@@ -350,25 +321,18 @@ func TestAutoDownloadPrefsEligible(t *testing.T) {
 	}{
 		{"zero value is permissive", AutoDownloadPrefs{}, flacCandidate, true},
 		{
-			"within the bitrate window",
+			"within min/max window",
-			AutoDownloadPrefs{MinKbps: 320, MaxKbps: 1200},
+			AutoDownloadPrefs{MinSizeMB: 100, MaxSizeMB: 500},
 			flacCandidate, true,
 		},
 		{
-			"below the minimum bitrate",
+			"below minimum",
-			AutoDownloadPrefs{MinKbps: 500},
+			AutoDownloadPrefs{MinSizeMB: 400},
 			mp3Candidate, false,
 		},
 		{
 			"above the maximum bitrate",
 			AutoDownloadPrefs{MaxKbps: 500},
 			flacCandidate, false,
 		},
 		{
-			// The ceiling is bytes, not a rate, and it is the guard
+			"above maximum",
-			// that still works when the bitrate cannot be worked out.
+			AutoDownloadPrefs{MaxSizeMB: 200},
 			"above the hard size ceiling",
 			AutoDownloadPrefs{MaxSizeMB: 50},
 			flacCandidate, false,
 		},
 		{
@@ -387,131 +351,57 @@ func TestAutoDownloadPrefsEligible(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-			got := tt.prefs.eligible(tt.c, okComputerRuntime)
+			if got := tt.prefs.eligible(tt.c); got != tt.want {
 			if got != tt.want {
 				t.Errorf("eligible() = %v, want %v", got, tt.want)
 			}
 		})
 	}
 }
 // A release nobody knows the length of cannot be judged on bitrate, and
 // the window must not become a silent embargo because MusicBrainz is
 // missing a track length.  The size ceiling still applies — that is why
 // it is a separate field.
 func TestBitrateWindowPassesAnUnknownRuntime(t *testing.T) {
 	t.Parallel()
 	c := kbpsCandidate("c", ".mp3", 128)
 	prefs := AutoDownloadPrefs{MinKbps: 900}
 	if !prefs.eligible(c, 0) {
 		t.Error("an unknown runtime must pass the bitrate window")
 	}
 	if prefs.eligible(c, okComputerRuntime) {
 		t.Error("a known runtime must still be judged")
 	}
 	ceiling := AutoDownloadPrefs{MaxSizeMB: 1}
 	if ceiling.eligible(c, 0) {
 		t.Error("the size ceiling must apply even with no runtime")
 	}
 }
 // Artwork is not part of the bitrate.  A folder carrying 30 MB of
 // scans would otherwise read as a better rip than the same music
 // without them, which is backwards.
 func TestBitrateIgnoresNonAudioFiles(t *testing.T) {
 	t.Parallel()
 	c := kbpsCandidate("c", ".mp3", 320)
 	bare := candidateKbps(c, okComputerRuntime)
 	c.Files = append(c.Files, CandidateFile{
 		Path: "Radiohead - OK Computer/cover.jpg",
 		Size: 30 << 20,
 	})
 	c.Files = AnnotateFiles(c.Files)
 	if got := candidateKbps(c, okComputerRuntime); got != bare {
 		t.Errorf("bitrate with artwork = %f, want %f", got, bare)
 	}
 }
 // Where no runtime is known, a stated per-file bitrate is better than
 // no answer at all.
 func TestBitrateFallsBackToTheStatedRate(t *testing.T) {
 	t.Parallel()
 	c := candidateFor("c", allTitles(), ".mp3", 3_000_000)
 	for i := range c.Files {
 		c.Files[i].Bitrate = 192
 	}
 	c.Files = AnnotateFiles(c.Files)
 	if got := candidateKbps(c, 0); got != 192 {
 		t.Errorf("stated bitrate = %f, want 192", got)
 	}
 }
 func TestAutoDownloadPrefsFilter(t *testing.T) {
 	t.Parallel()
-	lossy := kbpsCandidate("lossy", ".mp3", 128)
+	small := candidateFor("small", allTitles(), ".flac", 10_000_000)
-	lossless := kbpsCandidate("lossless", ".flac", 900)
+	small.TotalSize = 50 * mb
-	prefs := AutoDownloadPrefs{MinKbps: 500}
+	big := candidateFor("big", allTitles(), ".flac", 30_000_000)
 	big.TotalSize = 500 * mb
-	filtered := prefs.filter(
+	prefs := AutoDownloadPrefs{MinSizeMB: 100, MaxSizeMB: 600}
 		[]Candidate{lossy, lossless}, okComputerRuntime,
 	)
-	if len(filtered) != 1 || filtered[0].ID != "lossless" {
+	filtered := prefs.filter([]Candidate{small, big})
 	if len(filtered) != 1 || filtered[0].ID != "big" {
 		t.Errorf("filter() = %v, want only the in-window candidate", filtered)
 	}
 }
-func TestAutoDownloadPrefsBitrateFit(t *testing.T) {
+func TestAutoDownloadPrefsSizeFit(t *testing.T) {
 	t.Parallel()
 	const neutral = 0.5
 	tests := []struct {
-		name  string
+		name      string
-		prefs AutoDownloadPrefs
+		prefs     AutoDownloadPrefs
-		c     Candidate
+		totalSize int64
-		want  float64
+		want      float64
 	}{
-		{
+		{"no preference is neutral", AutoDownloadPrefs{}, 300 * mb, neutral},
 			"no preference is neutral",
 			AutoDownloadPrefs{},
 			kbpsCandidate("c", ".flac", 900), neutral,
 		},
 		{
 			"exact match scores 1",
-			AutoDownloadPrefs{PreferredKbps: 320},
+			AutoDownloadPrefs{PreferredSizeMB: 300},
-			kbpsCandidate("c", ".mp3", 320), 1.0,
+			300 * mb, 1.0,
 		},
 		{
-			// The floor is neutral, not zero: this term carries 0.40
+			"double the preferred size scores 0",
-			// of the quality score once a preference is set, and a
+			AutoDownloadPrefs{PreferredSizeMB: 300},
-			// span to zero would let "I like 320" quietly disqualify
+			600 * mb, 0.0,
 			// every FLAC from auto-pick.
 			"double the preferred rate falls to the neutral floor",
 			AutoDownloadPrefs{PreferredKbps: 320},
 			kbpsCandidate("c", ".flac", 640), neutral,
 		},
 		{
-			"half the preferred rate falls to the neutral floor",
+			"half the preferred size scores 0",
-			AutoDownloadPrefs{PreferredKbps: 320},
+			AutoDownloadPrefs{PreferredSizeMB: 300},
-			kbpsCandidate("c", ".mp3", 160), neutral,
+			150 * mb, 0.0,
 		},
 		{
 			"an unknowable rate is neutral",
 			AutoDownloadPrefs{PreferredKbps: 320},
 			kbpsCandidate("c", ".mp3", 320), neutral,
 		},
 	}
@@ -519,223 +409,30 @@ func TestAutoDownloadPrefsBitrateFit(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-			// The last case deliberately withholds the runtime.
+			if got := tt.prefs.sizeFit(tt.totalSize); got != tt.want {
-			runtime := int64(okComputerRuntime)
+				t.Errorf("sizeFit(%d) = %f, want %f", tt.totalSize, got, tt.want)
 			if tt.name == "an unknowable rate is neutral" {
 				runtime = 0
 			}
 			if got := tt.prefs.bitrateFit(tt.c, runtime); got != tt.want {
 				t.Errorf("bitrateFit() = %f, want %f", got, tt.want)
 			}
 		})
 	}
 }
 // An otherwise-perfect candidate must not auto-pick when it falls
-// outside the configured guardrails: they apply before the match and
+// outside the configured size guard: the guardrail applies before the
-// quality checks, not as one more input averaged into them.
+// match/quality/lead checks, not as one more input averaged into them.
-func TestAutoPickableRejectsCandidateOutsideTheGuardrails(t *testing.T) {
+func TestAutoPickableRejectsCandidateOutsideSizeGuard(t *testing.T) {
 	t.Parallel()
 	dl := okComputer()
-	best := Score(dl, kbpsCandidate("a", ".flac", 900), 50, AutoDownloadPrefs{})
+	best := Score(dl, candidateFor("a", allTitles(), ".flac", 30_000_000), 50, AutoDownloadPrefs{})
 	best.TotalSize = 500 * mb
 	if !AutoPickable(dl, []Candidate{best}, AutoDownloadPrefs{}) {
 		t.Fatal("expected this candidate to be auto-pickable with no guardrails")
 	}
-	if AutoPickable(dl, []Candidate{best}, AutoDownloadPrefs{MaxKbps: 320}) {
+	tight := AutoDownloadPrefs{MinSizeMB: 10, MaxSizeMB: 100}
 		t.Error("candidate above the bitrate window must not auto-pick")
 	}
-	if AutoPickable(dl, []Candidate{best}, AutoDownloadPrefs{MaxSizeMB: 1}) {
+	if AutoPickable(dl, []Candidate{best}, tight) {
-		t.Error("candidate above the size ceiling must not auto-pick")
+		t.Error("candidate outside the size guard must not auto-pick")
 	}
 }
 // The refusal has to name the gate that refused.
 //
 // Before AutoPickVeto, every one of these came back as the same
 // sentence built from `ranked[0]` — the best candidate before the size
 // and format guardrails — so a request refused because the user's size
 // window excluded every copy reported a match and a quality that both
 // cleared their thresholds.  A refusal quoting numbers that pass is
 // what made the matcher look broken from outside.
 func TestAutoPickVetoNamesTheGate(t *testing.T) {
 	t.Parallel()
 	dl := okComputer()
 	best := Score(
 		dl,
 		candidateFor("a", allTitles(), ".flac", 30_000_000),
 		50,
 		AutoDownloadPrefs{},
 	)
 	// candidateFor sizes the files and leaves TotalSize at 0, which is
 	// what the guardrails read.
 	sized := func(c Candidate, total int64) Candidate {
 		c.TotalSize = total
 		return c
 	}
 	tests := []struct {
 		name    string
 		dl      Download
 		ranked  []Candidate
 		prefs   AutoDownloadPrefs
 		wantSub string
 	}{
 		{
 			name:    "nothing found",
 			dl:      dl,
 			ranked:  nil,
 			wantSub: "nothing found",
 		},
 		{
 			name:    "free text",
 			dl:      Download{Artist: "Radiohead", Album: "OK Computer"},
 			ranked:  []Candidate{best},
 			wantSub: "free text",
 		},
 		{
 			name: "no tracklist behind the anchor",
 			dl: Download{
 				ReleaseMBID: "mbid-ok-computer",
 				Artist:      "Radiohead",
 				Album:       "OK Computer",
 			},
 			ranked:  []Candidate{best},
 			wantSub: "no tracklist",
 		},
 		{
 			// The candidate is 120 MB and the window tops out at 1 MB:
 			// the old message reported its match and quality instead.
 			name:    "outside the size window",
 			dl:      dl,
 			ranked:  []Candidate{sized(best, 120<<20)},
 			prefs:   AutoDownloadPrefs{MaxSizeMB: 1},
 			wantSub: "bitrate, size or format limits",
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 			got := AutoPickVeto(tt.dl, tt.ranked, tt.prefs)
 			if !strings.Contains(got, tt.wantSub) {
 				t.Errorf("veto = %q, want it to mention %q", got, tt.wantSub)
 			}
 		})
 	}
 }
 // A clear winner has no veto at all — the sentence is empty, which is
 // what AutoPickable reads.
 func TestAutoPickVetoIsEmptyForAClearWinner(t *testing.T) {
 	t.Parallel()
 	dl := okComputer()
 	best := Score(
 		dl,
 		candidateFor("a", allTitles(), ".flac", 30_000_000),
 		50,
 		AutoDownloadPrefs{},
 	)
 	weak := Score(
 		dl,
 		candidateFor("b", allTitles()[:2], ".mp3", 1_000_000),
 		50,
 		AutoDownloadPrefs{},
 	)
 	if got := AutoPickVeto(dl, []Candidate{best, weak}, AutoDownloadPrefs{}); got != "" {
 		t.Errorf("veto = %q, want none", got)
 	}
 }
 // With several candidates that all clear the bar, the preferred
 // bitrate decides which one is taken.
 //
 // This is what replaced the daylight requirement.  Auto-pick no longer
 // refuses when the field is close; it takes the copy nearest the shape
 // the user asked for, which is the question they actually answered in
 // Settings.
 func TestPreferredBitrateBreaksTheTie(t *testing.T) {
 	t.Parallel()
 	dl := okComputer()
 	prefs := AutoDownloadPrefs{PreferredKbps: 320}
 	// Same album, same completeness, same health, same provider — the
 	// only difference between them is the rate.
 	lossless := kbpsCandidate("lossless", ".flac", 900)
 	perfect := kbpsCandidate("perfect", ".mp3", 320)
 	ranked := Rank(
 		dl, []Candidate{lossless, perfect}, nil, prefs,
 	)
 	if ranked[0].ID != "perfect" {
 		t.Errorf(
 			"winner = %q (fit %f) over %q (fit %f), want the 320 kbps copy",
 			ranked[0].ID, ranked[0].Quality.BitrateFit,
 			ranked[1].ID, ranked[1].Quality.BitrateFit,
 		)
 	}
 	if AutoPickVeto(dl, ranked, prefs) != "" {
 		t.Error("a close field must still auto-pick")
 	}
 }
 // With no preference set, nothing changes: BitrateFit is the same
 // neutral value for every candidate and the older tie-breaks decide.
 func TestNoPreferredBitrateLeavesRankingAlone(t *testing.T) {
 	t.Parallel()
 	dl := okComputer()
 	lossless := kbpsCandidate("lossless", ".flac", 900)
 	lossy := kbpsCandidate("lossy", ".mp3", 320)
 	ranked := Rank(
 		dl, []Candidate{lossy, lossless}, nil, AutoDownloadPrefs{},
 	)
 	if ranked[0].ID != "lossless" {
 		t.Errorf(
 			"winner = %q, want the lossless copy on format alone",
 			ranked[0].ID,
 		)
 	}
 }
 // A preferred bitrate promotes the copy that matches it and must never
 // disqualify the ones that do not.  It carries 0.40 of the quality
 // score, so a fit spanning down to zero would put a perfectly good FLAC
 // under minQuality and out of auto-pick — turning a preference into a
 // prohibition without saying so.  MinKbps and MaxKbps are how a user
 // says that on purpose.
 func TestAPreferredBitrateNeverDisqualifies(t *testing.T) {
 	t.Parallel()
 	dl := okComputer()
 	far := AutoDownloadPrefs{PreferredKbps: 128}
 	lossless := Score(dl, kbpsCandidate("flac", ".flac", 900), 50, far)
 	if lossless.Quality.Overall < minQuality {
 		t.Errorf(
 			"quality = %f under a far-off preference, want >= %f",
 			lossless.Quality.Overall, minQuality,
 		)
 	}
 	if veto := AutoPickVeto(dl, []Candidate{lossless}, far); veto != "" {
 		t.Errorf("a far-off preference vetoed the candidate: %s", veto)
 	}
 }
@@ -310,35 +310,15 @@ func (r *Reconciler) run(ctx context.Context, force bool) (Summary, error) {
 	summary.Synced = r.syncExternalLists(ctx)
-	// Nothing is searched for when there is nothing to search with, and
+	attempted, started, err := r.attemptDue(ctx, force)
-	// the point is what that *does not* do to the list.
+	if err != nil {
-	//
+		return summary, err
 	// Attempting anyway is not merely wasted work: every request comes
 	// back "no download clients are enabled", which RecordAttempt writes
 	// down as an attempt and schedules a retry for -- so a user who has
 	// deliberately built a wanted list with no client watched their
 	// requests accrue failures and announce "next check in 6 hours"
 	// about a check that cannot happen. Wanting something without a way
 	// to fetch it is a supported thing to do; being told it is being
 	// looked for is a lie.
 	//
 	// Everything above this line still runs: an artist subscription
 	// still expands, and a request the user satisfied by some other
 	// route -- ripped, bought, copied in -- is still retired, because
 	// neither needs a provider.
 	summary.NoProviders = len(r.manager.enabledProviders()) == 0
 	if !summary.NoProviders {
 		attempted, started, err := r.attemptDue(ctx, force)
 		if err != nil {
 			return summary, err
 		}
 		summary.Attempted = attempted
 		summary.Started = started
 	}
 	summary.Attempted = attempted
 	summary.Started = started
 	summary.Waiting = r.countWaiting(ctx)
 	summary.NoProviders = len(r.manager.enabledProviders()) == 0
 	r.logger.Info(
 		"reconciled request list",
@@ -453,15 +453,6 @@ func TestReconcileRespectsBatchSize(t *testing.T) {
 	f := newReconcileFixture(t)
 	ctx := context.Background()
 	// A client that searches and finds nothing. The batch size is about
 	// how many requests one pass *searches for*, which only means
 	// anything when there is something to search with -- a pass with no
 	// provider now attempts nothing at all, deliberately.
 	f.manager.installProvider(
 		Config{ID: 1, Priority: 50},
 		NewFakeProvider(1, "finds-nothing", Caps{CanSearch: true}),
 	)
 	f.reconciler.SetBatch(2)
 	for _, mbid := range []string{"rg-1", "rg-2", "rg-3", "rg-4"} {
@@ -602,72 +593,3 @@ func TestSummaryReportsNoProviders(t *testing.T) {
 		t.Error("summary did not report that no download client is enabled")
 	}
 }
 // ...and it does not search, which is the part the user sees.
 //
 // Attempting with no provider fails every request with "no download
 // clients are enabled", and RecordAttempt writes that down as an
 // attempt and schedules a retry -- so a wanted list built deliberately
 // without a client accrued failures and announced "next check in 6
 // hours" about a check that cannot happen. Wanting something with no
 // way to fetch it is supported; being told it is being looked for is
 // a lie.
 func TestNoProvidersMeansNoAttempt(t *testing.T) {
 	t.Parallel()
 	f := newReconcileFixture(t)
 	ctx := context.Background()
 	id, err := f.store.AddRequest(ctx, Request{
 		MBID:      "rg-1",
 		Entity:    EntityReleaseGroup,
 		LibraryID: 1,
 		Title:     "OK Computer",
 	})
 	if err != nil {
 		t.Fatalf("AddRequest: %v", err)
 	}
 	f.catalog.tracklists["rg-1"] = fourTrackDownload().Expected
 	summary, err := f.reconciler.RunNow(ctx)
 	if err != nil {
 		t.Fatalf("RunNow: %v", err)
 	}
 	if summary.Attempted != 0 {
 		t.Errorf("attempted %d requests with no client to search with, want 0",
 			summary.Attempted)
 	}
 	// The list still knows what is on it: "nothing happened" has to be
 	// reportable as "nothing was searched for, of the one thing you
 	// want" rather than as silence.
 	if summary.Waiting != 1 {
 		t.Errorf("summary reported %d waiting, want 1", summary.Waiting)
 	}
 	req, err := f.store.GetRequest(ctx, id)
 	if err != nil {
 		t.Fatalf("GetRequest: %v", err)
 	}
 	if req.Attempts != 0 {
 		t.Errorf("attempts = %d, want 0: a pass that could not search did not",
 			req.Attempts)
 	}
 	if req.LastError != "" {
 		t.Errorf("lastError = %q, want empty: the request did not fail, it "+
 			"was never tried", req.LastError)
 	}
 	// A new request is due immediately (next_try_at is set to now on
 	// insert), so the fault is not the presence of a time -- it is a
 	// time pushed into the future by a failed attempt, which is what the
 	// UI renders as "next check in 6 hours".
 	if req.NextTryAt.After(time.Now().Add(time.Minute)) {
 		t.Errorf("next try scheduled for %v: a check that cannot happen was "+
 			"put on the clock", req.NextTryAt)
 	}
 }
@@ -20,41 +20,6 @@ func newServiceFixture(t *testing.T) serviceFixture {
 	mf := newManagerFixture(t)
 	svc := NewService(slogDiscard(), mf.manager, mf.store, NewMemSecretStore())
 	// Every test here is about the durable Request that `StartDownload`
 	// leaves behind, and none of them is about the download itself -- but
 	// their fixture is an anchored four-track request with a healthy
 	// provider, which is exactly what `AutoPickable` says yes to. So
 	// `Manager.Start` was firing `go m.grab(...)`, detached and with
 	// `context.WithoutCancel`, and the test then raced it.
 	//
 	// It lost, twice, in CI (`check` on c03c0b8, and nowhere locally):
 	//
 	//	service_test.go:66: state = "satisfied", want wanted
 	//	testing.go:1369: TempDir RemoveAll cleanup: ... directory not empty
 	//
 	// The first is the request reaching its *next* state before the
 	// assertion read it; the second is that same goroutine still writing
 	// into `t.TempDir()` after the test returned. One cause, two shapes.
 	//
 	// Putting the candidate outside the auto-pick guardrails stops the
 	// grab from ever starting, which is better than waiting for it: there
 	// is no goroutine to be slow, so the tests state what they mean
 	// ("the request exists, in this state") without a timing assumption
 	// underneath. A test that does want the download has `managerFixture`
 	// and sets its own preferences.
 	//
 	// The guard is a *format* the fake never produces, and it used to be
 	// `MaxSizeMB: 1`, which never fired: the size gates read
 	// `Candidate.TotalSize`, which real providers fill and the fake
 	// leaves at zero, and zero is under every ceiling. So the grab went
 	// ahead anyway and the second failure shape above — the TempDir
 	// cleanup race — kept happening, reproducibly, roughly one run in
 	// fifteen. A guard has to be keyed on something the fixture
 	// actually sets.
 	mf.manager.SetPreferences(AutoDownloadPrefs{
 		AllowedFormats: []Format{FormatWMA},
 	})
 	return serviceFixture{managerFixture: mf, svc: svc}
 }
@@ -193,11 +158,6 @@ func TestManualDownloadSatisfiesRequestOnSuccess(t *testing.T) {
 	f := newServiceFixture(t)
 	ctx := context.Background()
 	// This is the one test here that is *about* the download, so it
 	// undoes the fixture's guard rather than relying on it — which is
 	// what it was doing implicitly while the guard did not work.
 	f.manager.SetPreferences(AutoDownloadPrefs{})
 	provider := fakeWithAlbum(1, "source", ".flac")
 	f.manager.installProvider(Config{ID: 1, Priority: 50}, provider)
@@ -302,12 +302,7 @@ type QualityScore struct {
 	Bitrate    float64 `json:"bitrate"`
 	Health     float64 `json:"health"`   // seeders, free slots
 	Priority   float64 `json:"priority"` // user's per-provider preference
-	// BitrateFit is closeness to the preferred *rate*, which is what
+	SizeFit    float64 `json:"sizeFit"`  // closeness to the preferred download size
 	// the auto-download window is expressed in.  It replaced a
 	// `SizeFit` measured in megabytes: a size means nothing without
 	// knowing how long the music is, so the same number described a
 	// generous single and a suspiciously small boxset.
 	BitrateFit float64 `json:"bitrateFit"`
 	// Mixed marks a candidate whose files are not all the same format,
 	// which usually means a hand-assembled folder rather than a rip.
@@ -46,42 +46,23 @@ func TestCacheMiss(t *testing.T) {
 	}
 }
 // TestCacheTTLExpiry checks both halves of the TTL contract, and uses two
 // entries to do it.
 //
 // **No assertion here may depend on an upper bound of elapsed wall-clock
 // time**, which is what the single-entry version of this test did: it set
 // a 1s TTL and immediately asserted a *hit*, so on a loaded runner — one
 // goroutine descheduled for over a second while the rest of the suite
 // runs — the entry was correctly gone and the test failed with "expected
 // cache hit immediately after set".  It did exactly that in CI while
 // passing five times out of five locally.
 //
 // Sleeping *past* a TTL is always safe, so the expiry half keeps a short
 // one; the presence half gets a TTL nothing can outrun.
 func TestCacheTTLExpiry(t *testing.T) {
 	c := newTestCache(t)
 	data := []byte(`{"ephemeral":true}`)
-	c.Set("ttl-live-key", data, time.Hour, "", "")
+	c.Set("ttl-test-key", data, 1*time.Second, "", "")
 	c.Set("ttl-expiring-key", data, 1*time.Second, "", "")
-	if _, ok := c.Get("ttl-live-key"); !ok {
+	// Verify it's there immediately.
-		t.Fatal("expected a cache hit on an entry with an hour to live")
+	if _, ok := c.Get("ttl-test-key"); !ok {
 		t.Fatal("expected cache hit immediately after set")
 	}
-	// Wait for the short one to expire.
+	// Wait for expiry.
 	time.Sleep(2 * time.Second)
-	if _, ok := c.Get("ttl-expiring-key"); ok {
+	if _, ok := c.Get("ttl-test-key"); ok {
 		t.Error("expected cache miss after TTL expiry, got hit")
 	}
 	// And the long-lived entry is still there, which is what says the
 	// sweep above expired an entry rather than the cache.
 	if _, ok := c.Get("ttl-live-key"); !ok {
 		t.Error("the hour-long entry expired too")
 	}
 }
 func TestCacheMBID(t *testing.T) {
@@ -25,26 +25,8 @@ const (
 	// where cached cover art thumbnails are stored.
 	thumbnailDir = CoverArtCacheDirName
-	// thumbnailTimeout is the HTTP timeout for fetching a thumbnail,
+	// thumbnailTimeout is the HTTP timeout for fetching a thumbnail.
-	// and it has to cover a redirect the Cover Art Archive does not
+	thumbnailTimeout = 10 * time.Second
 	// serve itself.
 	//
 	// `coverartarchive.org` answers `front-250` with a 307 to an
 	// Internet Archive storage node (`dn######.us.archive.org`), and
 	// those nodes are routinely slow: measured against the twelve
 	// albums on Explore's own shelves, a successful fetch took 14–16 s
 	// and a failing one 13–17 s. At 10 s *every* cover on the page
 	// timed out — 24 cards, 5 of which had art, all of those from the
 	// disk cache — which reads as "Explore has no album art" rather
 	// than as a slow upstream, because a timeout writes nothing and
 	// says nothing.
 	//
 	// 30 s is chosen to clear that measured range with room, not to be
 	// generous: the fetch is off the critical path (each one is its own
 	// goroutine behind an 8/s limiter, and the frontend renders a
 	// placeholder until it lands), so the cost of waiting is nothing
 	// and the cost of giving up early is a blank page.
 	thumbnailTimeout = 30 * time.Second
 	// thumbnailMaxSize is the maximum image size to cache (2 MB).
 	thumbnailMaxSize = 2 * 1024 * 1024
@@ -115,20 +97,6 @@ func (p *CoverArtProxy) GetThumbnail(
 		return ""
 	}
 	// A 404 is an answer, and it is already on disk.
 	//
 	// `writeCache(mbid, nil)` has recorded "the archive has no art for
 	// this" as an empty file since this was written, and nothing has
 	// ever read it back: `readCache` returns "" for an empty file,
 	// which is indistinguishable from a miss, so every art-less release
 	// group was re-fetched from the network on every render that asked
 	// about it. On Explore's shelves a third of the cards are art-less,
 	// so that was a third of the page spending a live CAA request to be
 	// told again what the last one said.
 	if p.knownMissing(releaseGroupMBID) {
 		return ""
 	}
 	// Source 3: fetch from Cover Art Archive (slow, cached to disk).
 	url := CoverArtGroupURL(releaseGroupMBID)
 	data, cacheable, err := p.fetch(url)
@@ -209,9 +177,8 @@ func (p *CoverArtProxy) GetCandidateThumbnail(
 		}
 	}
-	// Network fetch on release group — unless a previous one was told
+	// Network fetch on release group.
-	// there is none. See `knownMissing`.
+	if releaseGroupMBID != "" {
 	if releaseGroupMBID != "" && !p.knownMissing(releaseGroupMBID) {
 		url := CoverArtGroupURL(releaseGroupMBID)
 		data, cacheable, err := p.fetch(url)
@@ -227,7 +194,7 @@ func (p *CoverArtProxy) GetCandidateThumbnail(
 	}
 	// Network fetch on release (fallback).
-	if releaseMBID != "" && !p.knownMissing(releaseMBID) {
+	if releaseMBID != "" {
 		url := CoverArtURL(releaseMBID)
 		data, cacheable, err := p.fetch(url)
@@ -318,17 +285,6 @@ func (p *CoverArtProxy) cachePath(mbid string) string {
 	return filepath.Join(p.cacheDir, mbid+".jpg")
 }
 // knownMissing reports whether a previous fetch was told the archive
 // has no art for this MBID — the empty file `writeCache(mbid, nil)`
 // leaves behind. It is deliberately separate from `readCache`, which
 // answers "what are the bytes" and cannot express the difference
 // between no answer and an answer of none.
 func (p *CoverArtProxy) knownMissing(mbid string) bool {
 	info, err := os.Stat(p.cachePath(mbid))
 	return err == nil && info.Size() == 0
 }
 func (p *CoverArtProxy) readCache(mbid string) string {
 	path := p.cachePath(mbid)
@@ -2212,7 +2212,6 @@ func (e *Service) gatherTopCandidates(
 				ArtistType: a.Type,
 				Country:    a.Country,
 				InLibrary:  a.InLibrary,
 				LocalID:    a.LocalID,
 			},
 			category:     "artist",
 			qualityScore: quality,
@@ -2244,7 +2243,6 @@ func (e *Service) gatherTopCandidates(
 				ArtistType: a.Type,
 				Country:    a.Country,
 				InLibrary:  a.InLibrary,
 				LocalID:    a.LocalID,
 			},
 			category:     "artist",
 			qualityScore: quality,
@@ -2277,7 +2275,6 @@ func (e *Service) gatherTopCandidates(
 				PrimaryType:  rg.PrimaryType,
 				Year:         year,
 				InLibrary:    rg.InLibrary,
 				LocalID:      rg.LocalID,
 			},
 			category:     "release_group",
 			qualityScore: quality,
@@ -2323,7 +2320,6 @@ func (e *Service) gatherTopCandidates(
 				PrimaryType:  rg.PrimaryType,
 				Year:         year,
 				InLibrary:    rg.InLibrary,
 				LocalID:      rg.LocalID,
 			},
 			category:     "release_group",
 			qualityScore: quality,
@@ -2351,7 +2347,6 @@ func (e *Service) gatherTopCandidates(
 				CAAReleaseMBID: r.CAAReleaseMBID,
 				ReleaseName:    r.ReleaseName,
 				InLibrary:      r.InLibrary,
 				LocalID:        r.LocalID,
 			},
 			category:     "recording",
 			qualityScore: quality,
@@ -2408,7 +2403,6 @@ func (e *Service) gatherTopCandidates(
 				CAAReleaseMBID: r.CAAReleaseMBID,
 				ReleaseName:    r.ReleaseName,
 				InLibrary:      r.InLibrary,
 				LocalID:        r.LocalID,
 			},
 			category:     "recording",
 			qualityScore: quality,
@@ -2431,7 +2425,6 @@ func (e *Service) gatherTopCandidates(
 					ArtistType: m.ArtistType,
 					Country:    m.Country,
 					InLibrary:  m.InLibrary || m.LocalArtistID > 0,
 					LocalID:    m.LocalArtistID,
 				},
 				category:     "artist",
 				qualityScore: quality,
@@ -2452,7 +2445,6 @@ func (e *Service) gatherTopCandidates(
 					PrimaryType:  m.PrimaryType,
 					Year:         year,
 					InLibrary:    m.InLibrary || m.LocalReleaseGroupID > 0,
 					LocalID:      m.LocalReleaseGroupID,
 				},
 				category:     "release_group",
 				qualityScore: quality,
@@ -2467,7 +2459,6 @@ func (e *Service) gatherTopCandidates(
 					ArtistMBID:   m.ArtistMBID,
 					Length:       m.Duration,
 					InLibrary:    m.InLibrary || m.LocalRecordingID > 0,
 					LocalID:      m.LocalRecordingID,
 				},
 				category:     "recording",
 				qualityScore: quality,
@@ -82,100 +82,6 @@ func TestPruneStaleLocalCrossReferences(t *testing.T) {
 	}
 }
 // TestPruneClearsInLibraryWithNoLocalID covers the fixed point: a row
 // carrying in_library with a NULL local_*_id.  The upsert's conflict
 // clause is `in_library = MAX(in_library, excluded.in_library)`, so it
 // can only ever raise the flag, and this pass used to be gated on the id
 // being present — which meant nothing in the app could clear such a row,
 // ever.  It is asserted for all three entity types because the gate was
 // written once and used three times, so a fix applied to one is a fix
 // that looks complete.
 //
 // The rows are seeded with raw SQL rather than through seedIndexResult
 // deliberately: upsertBatch writes a zero LocalArtistID as literal 0,
 // not NULL, and 0 satisfies `IS NOT NULL` — so the old gate already
 // caught that shape and a fixture built through the upsert cannot
 // reproduce this at all.  NULL is what the artifact importer and any
 // older writer leave behind, the column being nullable with no default.
 func TestPruneClearsInLibraryWithNoLocalID(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	si := NewSearchIndex(db, nil, nil, slog.Default())
 	// A genuinely owned artist, to prove the wider gate does not simply
 	// clear everything it now looks at.
 	database.InsertTestTrack(t, db, database.TestTrack{
 		FilePath: "/music/owned.mp3",
 		Artist:   "Owned",
 	})
 	artist, err := db.Queries.GetArtistByName(t.Context(), "Owned")
 	if err != nil {
 		t.Fatalf("read seeded artist: %v", err)
 	}
 	seedIndexResult(t, db, SearchIndexResult{
 		EntityType:    EntityArtist,
 		MBID:          testMBID("owned"),
 		Title:         "Owned",
 		ArtistName:    "Owned",
 		ArtistMBID:    testMBID("owned"),
 		InLibrary:     true,
 		LocalArtistID: artist.ID,
 	})
 	orphans := []struct {
 		name       string
 		entityType string
 		mbid       string
 	}{
 		{"artist", EntityArtist, "orphan-artist"},
 		{"release group", EntityReleaseGroup, "orphan-release-group"},
 		{"recording", EntityRecording, "orphan-recording"},
 	}
 	for _, o := range orphans {
 		if _, err := db.ExecContext(
 			`INSERT INTO explore_index
 			     (entity_type, mbid, title, artist_name, artist_mbid,
 			      in_library,
 			      local_artist_id, local_release_group_id, local_recording_id)
 			 VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?)`,
 			dbEntityType(o.entityType), dbMBID(testMBID(o.mbid)), o.name, o.name,
 			dbMBID(testMBID(o.mbid)),
 			nil, nil, nil,
 		); err != nil {
 			t.Fatalf("seed %s orphan: %v", o.name, err)
 		}
 	}
 	si.pruneStaleLocalCrossReferences()
 	inLibrary := func(t *testing.T, mbid string) int {
 		t.Helper()
 		var flag int
 		if err := db.QueryRowWriter(
 			"SELECT in_library FROM explore_index WHERE mbid = ?", dbMBID(mbid),
 		).Scan(&flag); err != nil {
 			t.Fatalf("read in_library for %q: %v", mbid, err)
 		}
 		return flag
 	}
 	for _, o := range orphans {
 		if got := inLibrary(t, testMBID(o.mbid)); got != 0 {
 			t.Errorf("%s with a NULL local id: in_library = %d, want 0", o.name, got)
 		}
 	}
 	if got := inLibrary(t, testMBID("owned")); got != 1 {
 		t.Errorf("owned artist: in_library = %d, want 1 (it still has a file)", got)
 	}
 }
 // TestUnenrichedLibraryArtistMBIDs_OrdersByOwnedTrackCount verifies the
 // backfill queue prioritizes artists by how many tracks the user actually
 // owns, not by how many duplicate-mbid artist rows happen to exist (the
@@ -2562,19 +2562,6 @@ func (si *SearchIndex) PopulateLocalCrossReferences() {
 // The row itself is left in place (it may still be part of the shipped
 // catalog, just no longer owned) — only the "this is mine" bookkeeping
 // is cleared.
 //
 // It is gated on the flag *or* the id, not on the id alone.  Gated on
 // the id, `in_library = 1 AND local_*_id IS NULL` is a fixed point: the
 // upsert can only ever raise the flag and this pass skipped such a row
 // by construction, so nothing in the app could clear it — a row claiming
 // to be owned, permanently, with no local row to check the claim
 // against.  Nothing in the tree writes that shape today
 // (collectLibraryEntities sets both together), which is exactly why it
 // is worth closing now: the exposure is a database written by an older
 // version, and the next writer that sets the flag without an id, which
 // nothing structurally prevents.  A NULL id fails the existence test on
 // its own, so the wider gate needs no second clause to say what "not
 // owned" means.
 func (si *SearchIndex) pruneStaleLocalCrossReferences() {
 	type prune struct {
 		entityType string
@@ -2607,8 +2594,7 @@ func (si *SearchIndex) pruneStaleLocalCrossReferences() {
 		result, err := si.db.ExecContext(
 			`UPDATE explore_index
 			 SET in_library = 0, `+p.column+` = NULL
-			 WHERE entity_type = ?
+			 WHERE entity_type = ? AND `+p.column+` IS NOT NULL
 			   AND (`+p.column+` IS NOT NULL OR in_library = 1)
 			   AND NOT EXISTS (`+p.exists+`)`,
 			dbEntityType(p.entityType),
 		)
@@ -41,16 +41,7 @@ type TopResult struct {
 	ReleaseGroupMBID string `json:"releaseGroupMbid,omitempty"`
 	ReleaseName      string `json:"releaseName,omitempty"`
 	// Library status — populated from index cross-reference columns.
-	//
+	InLibrary bool `json:"inLibrary"`
 	// LocalID is the one the cards read.  It is the local row behind
 	// this entity — an album, a file, an artist — and it is set and
 	// cleared by a test against `audio_files`, so it means "there is
 	// something of mine here".  InLibrary is written by the same pass
 	// but is a one-way ratchet the prune can only clear alongside a
 	// local id, so it is the weaker of the two and stays for scoring
 	// (`fwInLibrary`), which is where an approximate answer is fine.
 	InLibrary bool  `json:"inLibrary"`
 	LocalID   int64 `json:"localId,omitempty"`
 }
 // MBArtist is a Wails-friendly projection of a MusicBrainz artist.
@@ -232,112 +232,3 @@ func TestGetAlbumCompleteness_EmptyAlbum(t *testing.T) {
 		t.Errorf("empty album reported %+v, want zero and unknown", got)
 	}
 }
 // The batch and the single-album query are two spellings of one
 // question, and the thing worth pinning is that they never disagree.
 //
 // They are genuinely different SQL — the single-album form is
 // correlated subqueries over one album, the batch is two grouping
 // levels over a slice — so the risk is not a typo but a drift in
 // meaning: a disc's total counted once per file, a duplicate counted
 // twice, a disc with no total silently covered by one that had one.
 // Every shape the table above cares about is staged here at once,
 // because a batch that is only ever asked about one album is not being
 // asked the question that can go wrong.
 func TestGetAlbumsCompletenessAgreesWithTheSingleAlbumQuery(t *testing.T) {
 	t.Parallel()
 	lib, _ := setupTestLibrary(t)
 	shapes := map[int][]track{
 		1: disc(1, 100, 12, 12),
 		2: disc(1, 200, 9, 12),
 		3: disc(1, 300, 13, 12),
 		4: {{recordingID: 400, disc: 1, number: 1}},
 		5: append(disc(1, 500, 10, 10), disc(2, 600, 2, 5)...),
 		6: append(
 			disc(1, 700, 10, 10),
 			track{recordingID: 750, disc: 2, number: 1},
 		),
 		7: append(
 			disc(1, 800, 5, 6),
 			track{recordingID: 899, disc: 1, number: 3, total: 6},
 		),
 	}
 	ids := make([]int64, 0, len(shapes))
 	for albumID, tracks := range shapes {
 		stageAlbum(t, lib, albumID, tracks)
 		ids = append(ids, albumIDFor(t, lib, albumID))
 	}
 	batch, err := lib.GetAlbumsCompleteness(ids)
 	if err != nil {
 		t.Fatalf("GetAlbumsCompleteness: %v", err)
 	}
 	if len(batch) != len(ids) {
 		t.Fatalf("batch answered for %d albums, want %d", len(batch), len(ids))
 	}
 	for _, id := range ids {
 		one, err := lib.GetAlbumCompleteness(id)
 		if err != nil {
 			t.Fatalf("GetAlbumCompleteness(%d): %v", id, err)
 		}
 		if got := batch[id]; got != one {
 			t.Errorf("album %d: batch says %+v, single says %+v", id, got, one)
 		}
 	}
 }
 // An album with no files is absent from the batch, not zeroed.
 //
 // "I have none of this" and "I have no idea" are the third state Known
 // exists to keep apart, and a caller reading a missing key gets nothing
 // rather than a confident zero it would have to know to distrust.
 func TestGetAlbumsCompletenessOmitsAnAlbumWithNoFiles(t *testing.T) {
 	t.Parallel()
 	lib, _ := setupTestLibrary(t)
 	stageAlbum(t, lib, 1, disc(1, 100, 3, 3))
 	held := albumIDFor(t, lib, 1)
 	got, err := lib.GetAlbumsCompleteness([]int64{held, 4242})
 	if err != nil {
 		t.Fatalf("GetAlbumsCompleteness: %v", err)
 	}
 	if _, ok := got[4242]; ok {
 		t.Errorf("an album with no files answered %+v, want absent", got[4242])
 	}
 	if !got[held].Complete {
 		t.Errorf("held album reported %+v, want complete", got[held])
 	}
 }
 // A caller with nothing to ask about must not issue a query at all —
 // sqlc's empty-slice branch rewrites the placeholder to NULL, which is
 // a perfectly valid query returning nothing, so this is about the round
 // trip rather than the answer.
 func TestGetAlbumsCompletenessAsksNothingForAnEmptyList(t *testing.T) {
 	t.Parallel()
 	lib, _ := setupTestLibrary(t)
 	for _, ids := range [][]int64{nil, {}, {0}, {-1, 0}} {
 		got, err := lib.GetAlbumsCompleteness(ids)
 		if err != nil {
 			t.Fatalf("GetAlbumsCompleteness(%v): %v", ids, err)
 		}
 		if len(got) != 0 {
 			t.Errorf("GetAlbumsCompleteness(%v) = %+v, want empty", ids, got)
 		}
 	}
 }
@@ -289,13 +289,8 @@ func (l *Library) scanInternal(
 		l.mu.Unlock()
 	}()
 	// The configured mode, not a hardcoded "auto".  `ScanConcurrency`
 	// has been a validated config field with three values and one
 	// caller passing a constant, so choosing `ssd` or `hdd` by hand
 	// did nothing at all.
 	diskProfile := system.ProfileForPath(libraryPath)
 	workerCount := resolveScanWorkerCount(
-		l.conf.ScanConcurrency,
+		ScanConcurrencyAuto,
 		libraryPath,
 	)
@@ -305,10 +300,6 @@ func (l *Library) scanInternal(
 		"libraryName", libraryName,
 		"libraryPath", libraryPath,
 		"workers", workerCount,
 		"mode", l.conf.ScanConcurrency,
 		"device", diskProfile.Device,
 		"rotational", diskProfile.Rotational,
 		"queueDepth", diskProfile.QueueDepth,
 	)
 	// Helper to build a ScanProgress with library identification.
@@ -827,7 +818,7 @@ func (l *Library) scanInternal(
 	g := new(errgroup.Group)
 	g.SetLimit(workerCount)
-	for work := range readaheadWork(scanCtx, workChan, diskProfile) {
+	for work := range workChan {
 		g.Go(func() error {
 			if err := l.waitIfPaused(scanCtx); err != nil {
 				return err
@@ -1294,101 +1285,9 @@ func surveyAudioFiles(
 	return count, maxModTime
 }
-// How many extraction workers a spinning disk gets, and why it is two
+// hddWorkerCount is the maximum number of concurrent extraction
-// numbers rather than one.
+// workers when the library resides on a spinning disk.
-//
+const hddWorkerCount = 2
 // Extraction is not CPU work — every parser here reads headers and
 // returns — so on a spinning disk the whole cost is seek latency, and
 // the only question worth asking is how many reads should be in flight
 // at once.  That has two different right answers and the drive says
 // which:
 //
 //   - A drive with command queueing (NCQ: /sys/block/<dev>/device/
 //     queue_depth reports 31 or 32 on any SATA disk with it enabled)
 //     reorders outstanding reads into the order its head passes over
 //     them.  Handing it several at once is most of why a parallel scan
 //     beats a serial one at all, and four is where the returns flatten:
 //     the drive needs a few requests to have anything to reorder, and
 //     past that it is queueing requests it was already going to
 //     service in that order.
 //   - A drive without it — queue_depth 1, which is what a USB bridge
 //     or a pre-2004 disk reports — services one command at a time in
 //     the order given.  Every extra worker there is one more seek
 //     competing for one head, and the scan gets *slower* the harder it
 //     is pushed.  Two is kept rather than one because the readahead
 //     hints (see readaheadWork) do the overlapping that concurrency
 //     was standing in for, and one worker cannot hide a stall.
 //
 // This used to be a flat 2 for anything rotational, which is a
 // pre-NCQ assumption: it left a modern spinning disk with a quarter of
 // the queue depth it can use.
 const (
 	hddWorkerCountQueued = 4
 	hddWorkerCountSerial = 2
 )
 // Readahead tuning.
 const (
 	// readaheadDepth is how many files ahead of the workers the
 	// prefetcher runs.  It is the channel's buffer, so it is also the
 	// number of `WILLNEED` hints outstanding at once — comfortably more
 	// than a queueing drive's 32-command window is worth filling with
 	// one library, and small enough that a cancelled scan is not
 	// holding a long tail of queued reads.
 	readaheadDepth = 16
 	// readaheadBytes is how much of each file to pull in.  Everything
 	// the scanner reads lives at the head: ID3v2 and FLAC's
 	// STREAMINFO/VORBIS_COMMENT/PICTURE blocks, and the first MPEG
 	// frame with its Xing header.  512 KB covers a tag carrying
 	// embedded cover art, which is the large case — and reading a
 	// little too much sequentially costs a spinning disk almost
 	// nothing next to the seek that got there.
 	readaheadBytes = 512 << 10
 )
 // readaheadWork forwards scan work while asking the kernel to fetch
 // each file's header before a worker reaches it.
 //
 // The buffered channel *is* the lookahead: this goroutine runs ahead
 // of the workers until the buffer fills, hinting every file as it goes,
 // so by the time a worker takes an item the read it needs has been in
 // flight for `readaheadDepth` files' worth of parsing.  That is the
 // only thing that helps a spinning disk here, because the per-file work
 // is already header-only — every parser in `backend/metadata` reads a
 // few hundred bytes and returns, so the scan is not waiting on CPU or
 // on bytes, it is waiting on the head to arrive.
 //
 // It runs on rotational disks only.  An SSD has no seek to hide and
 // already has one worker per core; issuing hints there is pure syscall
 // overhead against an OS readahead that is already ahead of us.
 func readaheadWork(
 	ctx context.Context,
 	in <-chan scanWork,
 	profile system.DiskProfile,
 ) <-chan scanWork {
 	if !profile.Rotational {
 		return in
 	}
 	out := make(chan scanWork, readaheadDepth)
 	go func() {
 		defer close(out)
 		for work := range in {
 			hintReadahead(work.absolutePath, readaheadBytes)
 			select {
 			case out <- work:
 			case <-ctx.Done():
 				return
 			}
 		}
 	}()
 	return out
 }
 // resolveScanWorkerCount returns the number of concurrent
 // extraction workers based on the configured concurrency mode
@@ -1397,45 +1296,20 @@ func resolveScanWorkerCount(
 	mode ScanConcurrency,
 	libraryPath string,
 ) int {
 	return workersForProfile(
 		mode,
 		system.ProfileForPath(libraryPath),
 		goruntime.NumCPU(),
 	)
 }
 // workersForProfile is the policy on its own, so it can be tested
 // against drives this machine does not have.
 //
 // `hdd` and `ssd` override what the device says rather than being a
 // separate branch: the mode is the user overruling detection, and
 // detection is right about the queue depth either way — a user who
 // picks `hdd` on a queueing drive still wants that drive's queue used.
 func workersForProfile(
 	mode ScanConcurrency,
 	profile system.DiskProfile,
 	cpus int,
 ) int {
 	spinning := profile.Rotational
 	switch mode {
 	case ScanConcurrencySSD:
-		spinning = false
+		return goruntime.NumCPU()
 	case ScanConcurrencyHDD:
-		spinning = true
+		return min(hddWorkerCount, goruntime.NumCPU())
-	case ScanConcurrencyAuto:
+	default: // auto
-	}
+		if system.IsRotationalDisk(libraryPath) {
 			return min(
 				hddWorkerCount, goruntime.NumCPU(),
 			)
 		}
-	if !spinning {
+		return goruntime.NumCPU()
 		return cpus
 	}
 	workers := hddWorkerCountSerial
 	if profile.Queues() {
 		workers = hddWorkerCountQueued
 	}
 	return min(workers, cpus)
 }
 // scanWork represents a file to be processed by a worker.
@@ -244,65 +244,6 @@ func (l *Library) GetAlbumCompleteness(albumID int64) (AlbumCompleteness, error)
 	}, nil
 }
 // GetAlbumsCompleteness answers the same question for a screenful of
 // albums in one query, keyed by album id.
 //
 // A card grid asks this about every card that has a local album behind
 // it, and one query per card is how a grid of fifty albums becomes
 // fifty round trips. The answer matters there for the reason it
 // matters on the album page: an album held 9 tracks of 12 has to show
 // the count, and a bare tick saying "in your library" is the complaint
 // this whole rule came from.
 //
 // An album with no row in the result is one with no files, and it is
 // absent rather than zeroed — "I have none of this" and "I have no
 // idea" are the same third state `Known` exists to keep apart, and a
 // caller reading a missing key gets nothing rather than a confident 0.
 func (l *Library) GetAlbumsCompleteness(
 	albumIDs []int64,
 ) (map[int64]AlbumCompleteness, error) {
 	out := make(map[int64]AlbumCompleteness, len(albumIDs))
 	if len(albumIDs) == 0 {
 		return out, nil
 	}
 	keys := make([]sql.NullInt64, 0, len(albumIDs))
 	for _, id := range albumIDs {
 		if id <= 0 {
 			continue
 		}
 		keys = append(keys, sql.NullInt64{Int64: id, Valid: true})
 	}
 	if len(keys) == 0 {
 		return out, nil
 	}
 	rows, err := l.db.ReadQueries.GetAlbumsCompleteness(l.ctx, keys)
 	if err != nil {
 		l.logger.Error("could not get album completeness in batch",
 			"albums", len(keys), "error", err)
 		return nil, fmt.Errorf("could not get album completeness: %w", err)
 	}
 	for _, row := range rows {
 		known := row.Known != 0 && row.Expected > 0
 		out[row.AlbumID] = AlbumCompleteness{
 			Owned:    int(row.Owned),
 			Expected: int(row.Expected),
 			Known:    known,
 			Complete: known && row.Owned >= row.Expected,
 		}
 	}
 	return out, nil
 }
 // GetAlbumTracks returns one album's tracks in disc/track order.
 func (l *Library) GetAlbumTracks(albumID, libraryID int64) ([]Track, error) {
 	rows, err := l.db.ReadQueries.GetTracksByAlbum(
@@ -1,38 +0,0 @@
 //go:build linux
 package library
 import (
 	"os"
 	"golang.org/x/sys/unix"
 )
 // hintReadahead asks the kernel to start fetching the head of a file
 // that is about to be read.
 //
 // `POSIX_FADV_WILLNEED` returns immediately and queues the read, which
 // is the whole point: on a spinning disk the first access to a file
 // costs a seek of several milliseconds, and that latency can only be
 // hidden by having the next seek already in flight while the current
 // file is being parsed.  A drive with command queueing can then service
 // the queued reads in head order rather than in the order they were
 // asked for.
 //
 // Errors are dropped on purpose.  This is a hint: a file that has since
 // been deleted, a filesystem that does not implement fadvise, or a
 // permission the walk saw and this open does not, all mean "no
 // prefetch", never "fail the scan".  The read that follows is what
 // reports a genuine problem.
 func hintReadahead(path string, bytes int64) {
 	f, err := os.Open(path)
 	if err != nil {
 		return
 	}
 	defer func() { _ = f.Close() }()
 	_ = unix.Fadvise(
 		int(f.Fd()), 0, bytes, unix.FADV_WILLNEED,
 	)
 }
@@ -1,13 +0,0 @@
 //go:build !linux
 package library
 // hintReadahead is a no-op off Linux.
 //
 // macOS has `F_RDADVISE` and Windows has `FILE_FLAG_SEQUENTIAL_SCAN`,
 // and neither is wired up here for the reason the scan concurrency
 // heuristic is not either: this package cannot tell a spinning disk
 // from an SSD on those platforms (see system.ProfileForPath), so it
 // would be prefetching without knowing whether prefetching is what the
 // device wants.
 func hintReadahead(_ string, _ int64) {}
@@ -1,122 +0,0 @@
 package library
 import (
 	"context"
 	"testing"
 	"yellowjacket/backend/system"
 )
 // How many workers a scan gets is decided by two facts about the
 // device, and the second one is new: a spinning disk that can queue
 // commands wants several reads in flight, and one that cannot wants
 // almost none.  Before this it was a flat 2 for anything rotational,
 // which is a pre-NCQ assumption — a modern SATA disk reports a queue
 // depth of 32 and was being given a quarter of what it can use.
 func TestWorkersForProfile(t *testing.T) {
 	t.Parallel()
 	const cpus = 16
 	ssd := system.DiskProfile{Device: "sda", QueueDepth: 32}
 	hddQueued := system.DiskProfile{
 		Device: "sdb", Rotational: true, QueueDepth: 32,
 	}
 	hddSerial := system.DiskProfile{
 		Device: "sdc", Rotational: true, QueueDepth: 1,
 	}
 	// Neither NVMe nor a device-mapper volume publishes queue_depth.
 	// An unknown depth must not be read as "cannot queue", or every
 	// such device would be scanned as if it were a 2003 drive.
 	unknown := system.DiskProfile{Device: "dm-0", Rotational: true}
 	tests := []struct {
 		name    string
 		mode    ScanConcurrency
 		profile system.DiskProfile
 		want    int
 	}{
 		{"ssd auto", ScanConcurrencyAuto, ssd, cpus},
 		{"queueing hdd auto", ScanConcurrencyAuto, hddQueued, hddWorkerCountQueued},
 		{"serial hdd auto", ScanConcurrencyAuto, hddSerial, hddWorkerCountSerial},
 		{"unknown depth queues", ScanConcurrencyAuto, unknown, hddWorkerCountQueued},
 		// The mode overrules detection about the *disk*, never about
 		// its queue: forcing hdd on a queueing drive still uses it.
 		{"forced hdd on an ssd", ScanConcurrencyHDD, ssd, hddWorkerCountQueued},
 		{"forced ssd on an hdd", ScanConcurrencySSD, hddQueued, cpus},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 			if got := workersForProfile(tt.mode, tt.profile, cpus); got != tt.want {
 				t.Errorf(
 					"workersForProfile(%q, %+v) = %d, want %d",
 					tt.mode, tt.profile, got, tt.want,
 				)
 			}
 		})
 	}
 }
 // A machine with fewer cores than the policy asks for gets its cores.
 func TestWorkersNeverExceedTheCPUCount(t *testing.T) {
 	t.Parallel()
 	hdd := system.DiskProfile{Rotational: true, QueueDepth: 32}
 	if got := workersForProfile(ScanConcurrencyAuto, hdd, 1); got != 1 {
 		t.Errorf("single-core hdd = %d workers, want 1", got)
 	}
 }
 // The prefetch stage must forward every item and nothing else: it is a
 // pass-through with a side effect, and a scan that drops a file because
 // of a *hint* would be a spectacular way to lose part of a library.
 func TestReadaheadForwardsEveryFile(t *testing.T) {
 	t.Parallel()
 	in := make(chan scanWork, 4)
 	for _, p := range []string{"/a", "/b", "/c", "/d"} {
 		in <- scanWork{absolutePath: p}
 	}
 	close(in)
 	var got []string
 	for w := range readaheadWork(
 		context.Background(),
 		in,
 		system.DiskProfile{Rotational: true, QueueDepth: 32},
 	) {
 		got = append(got, w.absolutePath)
 	}
 	want := []string{"/a", "/b", "/c", "/d"}
 	if len(got) != len(want) {
 		t.Fatalf("forwarded %v, want %v", got, want)
 	}
 	for i := range want {
 		if got[i] != want[i] {
 			t.Errorf("item %d = %q, want %q", i, got[i], want[i])
 		}
 	}
 }
 // On an SSD the stage is not inserted at all — the channel comes back
 // unchanged, so a scan there pays nothing for a feature it cannot use.
 func TestReadaheadIsSkippedOnSolidState(t *testing.T) {
 	t.Parallel()
 	in := make(chan scanWork)
 	out := readaheadWork(
 		context.Background(), in, system.DiskProfile{QueueDepth: 32},
 	)
 	if out != (<-chan scanWork)(in) {
 		t.Error("an ssd must get the original channel, unwrapped")
 	}
 }
@@ -279,19 +279,17 @@ func (h *MPRISHandler) enqueue(fn func()) {
 	}
 }
-// metadataMap builds the org.mpris.MediaPlayer2.Player Metadata value
+// UpdateMetadata pushes track metadata to D-Bus.
-// for one track.
+func (h *MPRISHandler) UpdateMetadata(meta Metadata) {
-//
+	h.mu.Lock()
-// It is separated from UpdateMetadata, which needs a live D-Bus
+	h.trackID++
-// connection, so the map's contents can be asserted on: this file is
+	tid := h.trackID
-// behind a build tag and everything in it that touches h is reachable
+	h.mu.Unlock()
-// only from a session bus, which is the same reason the Android
+
-// contract lives in an untagged androidpayload.go.
+	m := map[string]interface{}{
 func metadataMap(meta Metadata, trackID uint64) map[string]any {
 	m := map[string]any{
 		"mpris:trackid": dbus.ObjectPath(
 			fmt.Sprintf(
-				"/org/yellowjacket/Track/%d", trackID,
+				"/org/yellowjacket/Track/%d", tid,
 			),
 		),
 	}
@@ -308,45 +306,16 @@ func metadataMap(meta Metadata, trackID uint64) map[string]any {
 		m["xesam:album"] = meta.Album
 	}
 	// Always present, even with nothing to point at.
 	//
 	// Every other key here can be omitted safely because a client
 	// reading the map sees a track with no title or no album and
 	// renders it that way. Art is different: KDE's applet (and
 	// others) treat an *absent* mpris:artUrl as "no news about the
 	// art" and keep drawing whatever the last track had, so playing
 	// something with no cover left the previous album's sleeve on
 	// screen — which reads as the wrong track playing rather than as
 	// missing artwork.
 	//
 	// An empty string is the honest answer and is what the spec's
 	// "URI" type degrades to; a client that cannot load it falls back
 	// to its own placeholder, which is the behaviour wanted.
 	artURL := ""
 	if meta.ArtFilePath != "" {
-		artURL = "file://" + meta.ArtFilePath
+		m["mpris:artUrl"] = "file://" + meta.ArtFilePath
 	}
 	m["mpris:artUrl"] = artURL
 	if meta.DurationSec > 0 {
 		m["mpris:length"] = int64(
 			meta.DurationSec,
 		) * usPerSec
 	}
 	return m
 }
 // UpdateMetadata pushes track metadata to D-Bus.
 func (h *MPRISHandler) UpdateMetadata(meta Metadata) {
 	h.mu.Lock()
 	h.trackID++
 	tid := h.trackID
 	h.mu.Unlock()
 	m := metadataMap(meta, tid)
 	h.enqueue(func() {
 		h.props.SetMust(playerIf, "Metadata", m)
 	})
@@ -1,86 +0,0 @@
 //go:build linux && !android
 package mediacontrols
 import "testing"
 // The one key that must be present even when it is empty.
 //
 // Everything else in the map may be omitted, because a client reading
 // it renders a track with no title as a track with no title. Art is
 // different: KDE's applet treats an *absent* mpris:artUrl as no news
 // about the art and keeps drawing the last one it saw, so a track with
 // no cover wore the previous album's sleeve — which reads as the wrong
 // track playing rather than as missing artwork.
 func TestMetadataMapAlwaysCarriesArtURL(t *testing.T) {
 	t.Parallel()
 	tests := []struct {
 		name string
 		meta Metadata
 		want string
 	}{
 		{
 			name: "no art at all",
 			meta: Metadata{Title: "Blue in Green"},
 			want: "",
 		},
 		{
 			name: "art on disk",
 			meta: Metadata{
 				Title:       "Blue in Green",
 				ArtFilePath: "/covers/kind-of-blue_lg.jpg",
 			},
 			want: "file:///covers/kind-of-blue_lg.jpg",
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 			m := metadataMap(tt.meta, 1)
 			got, ok := m["mpris:artUrl"]
 			if !ok {
 				t.Fatal("mpris:artUrl is absent; it must always be sent")
 			}
 			if got != tt.want {
 				t.Errorf("mpris:artUrl = %v, want %q", got, tt.want)
 			}
 		})
 	}
 }
 // The trackid has to change between tracks or a client is entitled to
 // treat the metadata as describing the same track it already has.
 func TestMetadataMapTrackIDVaries(t *testing.T) {
 	t.Parallel()
 	first := metadataMap(Metadata{Title: "A"}, 1)["mpris:trackid"]
 	second := metadataMap(Metadata{Title: "B"}, 2)["mpris:trackid"]
 	if first == second {
 		t.Errorf("trackid did not change: %v", first)
 	}
 }
 // The optional keys stay optional — this is what makes artUrl's
 // always-present treatment a deliberate exception rather than drift.
 func TestMetadataMapOmitsEmptyOptionalFields(t *testing.T) {
 	t.Parallel()
 	m := metadataMap(Metadata{}, 1)
 	for _, key := range []string{
 		"xesam:title",
 		"xesam:artist",
 		"xesam:album",
 		"mpris:length",
 	} {
 		if _, ok := m[key]; ok {
 			t.Errorf("%s is present for an empty Metadata", key)
 		}
 	}
 }
@@ -1,188 +0,0 @@
 package player
 import (
 	"errors"
 	"testing"
 	"time"
 	"github.com/gopxl/beep/v2"
 )
 // errTestDecode stands in for a decoder blowing up mid-track.
 var errTestDecode = errors.New("decode blew up")
 // stalledStreamer never produces a sample and never reports
 // end-of-stream: (0, true), forever. A damaged file that decodes to
 // nothing looks like this, and so does any source whose producer has
 // quietly stopped.
 type stalledStreamer struct{}
 func (stalledStreamer) Stream(_ [][2]float64) (int, bool) { return 0, true }
 func (stalledStreamer) Err() error                        { return nil }
 // failingStreamer produces n good samples and then fails, which is
 // what a decode error mid-track looks like: the same (0, false) a
 // finished track returns, distinguishable only by Err.
 type failingStreamer struct {
 	remaining int
 	err       error
 }
 func (f *failingStreamer) Stream(samples [][2]float64) (int, bool) {
 	if f.remaining <= 0 {
 		return 0, false
 	}
 	n := min(len(samples), f.remaining)
 	for i := range n {
 		samples[i] = [2]float64{1, 1}
 	}
 	f.remaining -= n
 	return n, true
 }
 func (f *failingStreamer) Err() error { return f.err }
 // drainUntilEnd calls Stream until it reports end-of-stream, or gives
 // up. It returns whether the stream ended.
 //
 // The give-up bound is wall clock rather than a call count: the stall
 // budget is a duration, so a tight loop has to actually wait it out.
 func drainUntilEnd(bs *BufferedStreamer, within time.Duration) bool {
 	buf := make([][2]float64, 512)
 	deadline := time.Now().Add(within)
 	for time.Now().Before(deadline) {
 		if _, ok := bs.Stream(buf); !ok {
 			return true
 		}
 		time.Sleep(time.Millisecond)
 	}
 	return false
 }
 // A source that stops producing without ever ending is the fault this
 // whole file exists for: Stream used to answer with silence and ok
 // forever, so the chain never ended, the player stayed in Playing
 // with the button showing pause, and the decoder's position never
 // moved -- a frozen seek bar over a track that was not playing.
 func TestAStalledSourceEndsTheStream(t *testing.T) {
 	bs := NewBufferedStreamer(stalledStreamer{}, 2048)
 	defer bs.Close()
 	if !drainUntilEnd(bs, maxStarvedDuration+2*time.Second) {
 		t.Fatal(
 			"a stalled source never ended the stream: the player " +
 				"would sit in Playing with a frozen position",
 		)
 	}
 	if !errors.Is(bs.Err(), errSourceStalled) {
 		t.Fatalf(
 			"expected the stall to be reported, got %v", bs.Err(),
 		)
 	}
 }
 // Close is the other exit that used to leave `done` false, with the
 // same consequence: the ring drains and every call after it is
 // silence that claims to be audio.
 func TestClosingEndsTheStream(t *testing.T) {
 	bs := NewBufferedStreamer(finiteStreamer(1<<20), 2048)
 	// Let the read-ahead fill something, so this exercises the drain
 	// after Close rather than a buffer that was empty anyway.
 	time.Sleep(20 * time.Millisecond)
 	bs.Close()
 	if !drainUntilEnd(bs, 2*time.Second) {
 		t.Fatal("a closed streamer never reported end-of-stream")
 	}
 }
 // A source that fails is not a source that finished, and only Err
 // tells them apart. Before this, the player reported a mid-track
 // decode failure to the queue as a natural end, so the queue
 // auto-advanced in silence and counted the broken track as played.
 func TestAFailedSourceReportsItsError(t *testing.T) {
 	src := &failingStreamer{remaining: 4096, err: errTestDecode}
 	bs := NewBufferedStreamer(src, 2048)
 	defer bs.Close()
 	if !drainUntilEnd(bs, 2*time.Second) {
 		t.Fatal("a failing source never reported end-of-stream")
 	}
 	if !errors.Is(bs.Err(), errTestDecode) {
 		t.Fatalf(
 			"expected the source's error to survive, got %v",
 			bs.Err(),
 		)
 	}
 }
 // The ordinary case has to keep working: a source that ends cleanly
 // ends with no error, or every finished track would be reported as a
 // failure and skipped.
 func TestADrainedSourceReportsNoError(t *testing.T) {
 	bs := NewBufferedStreamer(finiteStreamer(4096), 2048)
 	defer bs.Close()
 	if !drainUntilEnd(bs, 2*time.Second) {
 		t.Fatal("a finite source never reported end-of-stream")
 	}
 	if bs.Err() != nil {
 		t.Fatalf(
 			"a track that finished normally reported %v", bs.Err(),
 		)
 	}
 }
 // A slow source is exactly what the read-ahead exists to absorb, so
 // underruns must not be charged cumulatively -- otherwise a file on a
 // slow disk ends itself partway through.
 func TestUnderrunsDoNotAccumulateAcrossASlowSource(t *testing.T) {
 	const total = 8192
 	src := &slowStreamer{
 		inner: finiteStreamer(total),
 		delay: 2 * time.Millisecond,
 	}
 	bs := NewBufferedStreamer(src, 1024)
 	defer bs.Close()
 	buf := make([][2]float64, 256)
 	got := 0
 	for {
 		n, ok := bs.Stream(buf)
 		if !ok {
 			break
 		}
 		for i := range n {
 			if buf[i][0] != 0 {
 				got++
 			}
 		}
 	}
 	if got != total {
 		t.Fatalf(
 			"a slow but healthy source was cut short: got %d of %d "+
 				"samples",
 			got, total,
 		)
 	}
 }
 // beep.Streamer is what the player wraps; keep the type honest.
 var _ beep.Streamer = (*BufferedStreamer)(nil)
@@ -1,7 +1,6 @@
 package player
 import (
 	"errors"
 	"sync"
 	"time"
@@ -35,45 +34,8 @@ type BufferedStreamer struct {
 	done    bool
 	err     error
 	closed  chan struct{}
 	// starved counts consecutive Stream calls served with silence
 	// because the ring was empty, and starvedSince is when that run
 	// began.  An underrun is legitimate for a moment -- that is what
 	// the read-ahead exists to absorb -- but it is not legitimate
 	// forever, and "forever" is indistinguishable from healthy
 	// playback everywhere above this type: the chain never ends, so
 	// the player stays in Playing with the button showing pause, and
 	// the decoder's position never moves, so the 1 Hz report pins the
 	// seek bar and suppresses its interpolation.
 	starved      int
 	starvedSince time.Time
 }
 // The silence fill is bounded by both a duration and a run of calls,
 // and it needs both.
 //
 // Duration alone is the real measure -- the speaker paces itself, so
 // wall clock is what says whether the source has actually stopped --
 // but a caller draining in a tight loop (a test, a decode-to-buffer)
 // makes hundreds of calls in microseconds and would trip nothing.
 // A call count alone is the opposite failure: the same tight loop
 // spends the whole budget before the read-ahead goroutine has been
 // scheduled once, and ends a perfectly good stream at sample zero.
 //
 // The duration is longer than the 2 s read-ahead it is there to
 // outlast, and the count is short enough that the speaker (~200 ms a
 // call) reaches it well inside that.
 const (
 	maxStarvedDuration = 3 * time.Second
 	minStarvedCalls    = 8
 )
 // errSourceStalled is returned by Err when the source stopped
 // producing samples without ever reporting end-of-stream.
 var errSourceStalled = errors.New(
 	"audio source stopped producing samples",
 )
 // NewBufferedStreamer creates a BufferedStreamer that pre-fills
 // bufferSize samples from source via a background goroutine.
 // A typical bufferSize is 2× the sample rate (~2 seconds of audio).
@@ -92,24 +54,8 @@ func NewBufferedStreamer(
 	return bs
 }
 // finish marks the stream ended, recording err as the reason when
 // there is one.  Every exit from readAhead goes through it: an exit
 // that leaves done false strands Stream in its underrun branch,
 // where it returns silence and ok forever.
 func (bs *BufferedStreamer) finish(err error) {
 	bs.mu.Lock()
 	defer bs.mu.Unlock()
 	bs.done = true
 	if err != nil && bs.err == nil {
 		bs.err = err
 	}
 }
 // readAhead continuously reads from the source into the ring buffer
 // until the source is drained, an error occurs, or Close is called.
 // It always marks the stream done on the way out.
 func (bs *BufferedStreamer) readAhead() {
 	// Temporary buffer for reading from source outside the lock.
 	// 512 samples per chunk keeps the critical section short.
@@ -117,13 +63,6 @@ func (bs *BufferedStreamer) readAhead() {
 	tmp := make([][2]float64, chunkSize)
 	// Every exit marks the stream done.  An exit that does not is what
 	// stranded Stream in its underrun branch, returning silence and ok
 	// for the rest of the process's life.
 	var exitErr error
 	defer func() { bs.finish(exitErr) }()
 	for {
 		// Check if closed.
 		select {
@@ -133,15 +72,6 @@ func (bs *BufferedStreamer) readAhead() {
 		}
 		bs.mu.Lock()
 		// Stream gave up waiting for us.  Nothing downstream is
 		// listening any more, so filling the ring is work for nobody.
 		if bs.done {
 			bs.mu.Unlock()
 			return
 		}
 		space := len(bs.ring) - bs.count
 		if space == 0 {
@@ -185,12 +115,14 @@ func (bs *BufferedStreamer) readAhead() {
 		}
 		if !ok {
-			// A drained source and a failed one both land here and are
+			bs.mu.Lock()
-			// not the same event: one is a track that ended, the other
+			bs.done = true
-			// is a track that broke.  Err is what tells them apart, and
+
-			// it is why the player must ask before treating this as a
+			if srcErr := bs.source.Err(); srcErr != nil {
-			// natural finish.
+				bs.err = srcErr
-			exitErr = bs.source.Err()
+			}
 			bs.mu.Unlock()
 			return
 		}
@@ -222,27 +154,7 @@ func (bs *BufferedStreamer) Stream(
 	}
 	if bs.count == 0 {
-		// The read-ahead has not caught up.  Silence buys it time --
+		// Buffer temporarily empty — fill with silence.
 		// but only for a bounded stretch, because "forever" is
 		// reported upward as healthy playback and there is no watchdog
 		// above this to notice otherwise.
 		bs.starved++
 		if bs.starvedSince.IsZero() {
 			bs.starvedSince = time.Now()
 		}
 		if bs.starved >= minStarvedCalls &&
 			time.Since(bs.starvedSince) > maxStarvedDuration {
 			bs.done = true
 			if bs.err == nil {
 				bs.err = errSourceStalled
 			}
 			return 0, false
 		}
 		for i := range samples {
 			samples[i] = [2]float64{}
 		}
@@ -250,9 +162,6 @@ func (bs *BufferedStreamer) Stream(
 		return len(samples), true
 	}
 	// Samples arrived, so whatever the stall was, it is over.
 	bs.resetStarvationLocked()
 	// Copy available samples from ring buffer.
 	n := len(samples)
 	if n > bs.count {
@@ -288,19 +197,6 @@ func (bs *BufferedStreamer) Flush() {
 	bs.readPos = 0
 	bs.writPos = 0
 	bs.count = 0
 	// A seek empties the ring on purpose, and the refill that follows
 	// is exactly the stall the budget exists to tolerate.  Charging it
 	// against a budget the previous underrun already spent would end
 	// the track on a seek near the end of a slow file.
 	bs.resetStarvationLocked()
 }
 // resetStarvationLocked forgets an underrun run.  Must be called with
 // bs.mu held.
 func (bs *BufferedStreamer) resetStarvationLocked() {
 	bs.starved = 0
 	bs.starvedSince = time.Time{}
 }
 // LockSource blocks the read-ahead goroutine from touching the
@@ -1,213 +0,0 @@
 package player
 import (
 	"log/slog"
 	"testing"
 	"time"
 	"github.com/wailsapp/wails/v3/pkg/application"
 	"yellowjacket/backend/events"
 	"yellowjacket/internal/testfixtures"
 )
 // fixtureSampleRate is what cmd/gentestdata writes (audio.go).  It is
 // deliberately not the speaker rate, which is what lets these tests
 // tell the decoder's format from the player's default.
 const fixtureSampleRate = 22050
 // newTestPlayer is a player with a context and no database, so the
 // track-metadata lookup cannot succeed.
 func newTestPlayer(t *testing.T) *Player {
 	t.Helper()
 	p := NewPlayer(slog.Default(), nil)
 	rec := events.NewRecorder()
 	_ = p.ServiceStartup(
 		events.WithSink(t.Context(), rec),
 		application.ServiceOptions{},
 	)
 	return p
 }
 // loadFileLocked needs no speaker: it decodes, builds the chain and
 // registers it paused. speaker.Play on an uninitialised device is
 // what the integration guard elsewhere is about, so these assert on
 // the state the load computed rather than on playback.
 // p.format used to be assigned once, in the constructor, to the
 // *speaker's* rate -- so it claimed 44.1 kHz for every file ever
 // loaded. Play()'s replay-after-finish path resamples from it, so a
 // finished track played again was resampled from a rate the decoder
 // never produced: audibly the wrong speed and pitch, and wrong
 // length and position arithmetic with it.
 //
 // The fixtures are 22050 Hz, which is exactly the point -- any of
 // them disagrees with the speaker rate.
 func TestLoadRecordsTheDecodersOwnFormat(t *testing.T) {
 	m := testfixtures.Load(t)
 	path := m.Case(t, testfixtures.CaseCoverDedup)[0]
 	p := newTestPlayer(t)
 	if got := p.format.SampleRate; got != speakerSampleRate {
 		t.Fatalf(
 			"precondition: a fresh player should hold the speaker "+
 				"rate, got %d",
 			got,
 		)
 	}
 	if err := p.LoadFile(path); err != nil {
 		t.Fatalf("LoadFile(%s): %v", path, err)
 	}
 	if p.format.SampleRate == speakerSampleRate {
 		t.Fatalf(
 			"p.format still holds the speaker rate (%d) after "+
 				"loading a %d Hz file: the replay path would "+
 				"resample from the wrong rate",
 			speakerSampleRate, fixtureSampleRate,
 		)
 	}
 	if got := int(p.format.SampleRate); got != fixtureSampleRate {
 		t.Errorf(
 			"expected the decoder's rate %d, got %d",
 			fixtureSampleRate, got,
 		)
 	}
 }
 // trackLengthMs is written only when the database has a row for the
 // file and cleared only by UnloadTrack, so a track with no row used
 // to inherit whatever the last track's duration was -- and every
 // position report is scaled by it, so the whole seek bar was then
 // reporting one track's progress on another track's scale.
 //
 // There is no database here, so the lookup cannot succeed: exactly
 // the case that used to inherit.
 func TestLoadDoesNotInheritThePreviousTracksDuration(t *testing.T) {
 	m := testfixtures.Load(t)
 	path := m.Case(t, testfixtures.CaseCoverDedup)[0]
 	p := newTestPlayer(t)
 	// Stand in for a previous track whose duration was resolved.
 	p.trackLengthMs = 9_999_000
 	if err := p.LoadFile(path); err != nil {
 		t.Fatalf("LoadFile(%s): %v", path, err)
 	}
 	if p.trackLengthMs == 9_999_000 {
 		t.Fatal(
 			"the previous track's duration survived the load: every " +
 				"position report for this track would be scaled by it",
 		)
 	}
 }
 // A new chain supersedes the old one's pending finished callback.
 // Without this, a callback that queued for p.mu behind a LoadFile
 // woke up and rewound, stopped and auto-advanced the *new* track.
 func TestANewChainSupersedesTheOldFinishedCallback(t *testing.T) {
 	m := testfixtures.Load(t)
 	paths := m.Case(t, testfixtures.CaseCoverDedup)
 	if len(paths) < 2 {
 		t.Skip("need two fixture tracks")
 	}
 	p := newTestPlayer(t)
 	if err := p.LoadFile(paths[0]); err != nil {
 		t.Fatalf("LoadFile(%s): %v", paths[0], err)
 	}
 	stale := p.chainID
 	if err := p.LoadFile(paths[1]); err != nil {
 		t.Fatalf("LoadFile(%s): %v", paths[1], err)
 	}
 	if p.chainID == stale {
 		t.Fatal("loading a second file did not supersede the chain")
 	}
 	called := false
 	p.SetPlaybackFinishedHandler(func(error) { called = true })
 	// The first track's callback, arriving late.
 	p.onPlaybackFinished(stale, nil)
 	if called {
 		t.Error(
 			"a superseded chain's callback drove auto-advance: the " +
 				"track that is loaded now would be skipped",
 		)
 	}
 	if p.state == Stopped {
 		t.Error(
 			"a superseded chain's callback stopped the current track",
 		)
 	}
 }
 // The decoder is read by the read-ahead goroutine and by every
 // position emit, and those used to be guarded by different mutexes:
 // the read by srcMu, the position by the speaker lock, which
 // read-ahead never takes. Under -race this failed on the emit that
 // LoadFile itself makes.
 //
 // It needs the read-ahead goroutine to actually be running, so it
 // keeps asking for the position for long enough to overlap it.
 func TestPositionReadsDoNotRaceTheReadAhead(t *testing.T) {
 	m := testfixtures.Load(t)
 	path := m.Case(t, testfixtures.CaseFLACAlbum)[0]
 	p := newTestPlayer(t)
 	if err := p.LoadFile(path); err != nil {
 		t.Fatalf("LoadFile(%s): %v", path, err)
 	}
 	for range 200 {
 		if _, err := p.CurrentPositionSeconds(); err != nil {
 			t.Fatalf("CurrentPositionSeconds: %v", err)
 		}
 	}
 }
 // Seeking emits the landing position, and that emit reads the
 // decoder -- so the source lock the seek holds must be released
 // before it. A reentrant take here is a deadlock, not a failure,
 // which is why this test exists rather than a comment.
 func TestSeekEmitsWithoutDeadlocking(t *testing.T) {
 	m := testfixtures.Load(t)
 	path := m.Case(t, testfixtures.CaseFLACAlbum)[0]
 	p := newTestPlayer(t)
 	if err := p.LoadFile(path); err != nil {
 		t.Fatalf("LoadFile(%s): %v", path, err)
 	}
 	done := make(chan struct{})
 	go func() {
 		defer close(done)
 		_ = p.Seek(1)
 	}()
 	select {
 	case <-done:
 	case <-time.After(10 * time.Second):
 		t.Fatal("Seek deadlocked: the position emit re-took the source lock")
 	}
 }
@@ -52,17 +52,9 @@ type Player struct {
 	control                 *beep.Ctrl
 	volume                  *effects.Volume
 	speakerStreamer         beep.Streamer
-	playbackFinishedHandler func(error)
+	playbackFinishedHandler func()
 	trackChangeID           uint64
-
+	mediaControls           mediacontrols.Handler
 	// chainID identifies the streamer chain currently registered with
 	// the speaker.  updateStreamers bumps it, and the finished
 	// callback carries the value it was registered with, so a callback
 	// that queued for p.mu behind a LoadFile can tell that the player
 	// has moved on and return rather than rewinding somebody else's
 	// track.
 	chainID       uint64
 	mediaControls mediacontrols.Handler
 	// duckAmount is the attenuation currently applied on top of the
 	// user's volume, in the same base-2 exponent effects.Volume uses.
@@ -71,19 +63,6 @@ type Player struct {
 	// not something the user chose.
 	duckAmount float64
 	// systemVolume is what SystemOwnsVolume answers: the platform's own
 	// control is the only one, so ours neither acts nor persists.  It is
 	// a field rather than the build constant read directly so that a
 	// test can exercise both sides on any machine.  See systemvolume.go.
 	systemVolume bool
 	// storedVolume and storedMuted hold the persisted level as it was
 	// found at restore, for a platform whose volume we do not own: the
 	// maximum we then run at is not a level the user chose, so saveState
 	// writes back what it read rather than overwriting it.
 	storedVolume UserVolume
 	storedMuted  bool
 	// trackLengthMs holds the authoritative track duration in
 	// milliseconds, sourced from the database (which uses the
 	// custom header parser).  The go-mp3 decoder's Len() can be
@@ -169,8 +148,6 @@ func NewPlayer(logger *slog.Logger, db *database.DB) *Player {
 		logger:       logger,
 		db:           db,
 		state:        Stopped,
 		systemVolume: platformOwnsVolume,
 		storedVolume: DefaultUserVol,
 		baseStreamer: generators.Silence(-1),
 		format: beep.Format{
 			SampleRate: speakerSampleRate,
@@ -203,18 +180,11 @@ func (p *Player) InitSpeaker() error {
 }
 // SetPlaybackFinishedHandler sets a callback invoked when a track
-// stops streaming. This allows the queue to drive auto-advance
+// finishes naturally. This allows the queue to drive auto-advance
 // without circular imports.
 //
 // The error says *why* the track stopped: nil for a track that
 // reached its end, non-nil for one that broke partway through.  Both
 // arrive here because both look identical to the speaker, and only
 // the queue holds the metadata a PlaybackFailed needs -- but they are
 // not the same event, and reporting a decode failure as a natural
 // finish is how a broken file used to auto-advance in silence.
 //
 //wails:ignore // internal wiring, not part of the app's IPC surface.
-func (p *Player) SetPlaybackFinishedHandler(handler func(error)) {
+func (p *Player) SetPlaybackFinishedHandler(handler func()) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
@@ -454,19 +424,6 @@ func (p *Player) updateStreamers(
 	newBaseStreamer beep.StreamSeeker,
 	sr beep.SampleRate,
 ) error {
 	// A new chain supersedes the old one, so any finished callback the
 	// old one still owes is stale from here on.
 	p.chainID++
 	// The previous read-ahead goroutine reads the same decoder this
 	// one is about to, under its own srcMu -- two goroutines, two
 	// mutexes, one decoder that is not safe for concurrent use.  The
 	// replay-after-finish path rebuilds from p.seeker without going
 	// through LoadFile, which is where that pair could meet.
 	if p.buffered != nil {
 		p.buffered.Close()
 	}
 	// set base streamer
 	p.baseStreamer = newBaseStreamer
 	p.seeker = newBaseStreamer
@@ -517,57 +474,23 @@ func (p *Player) startPaused() {
 	p.control.Paused = true
 	speaker.Unlock()
 	// Captured, not read at callback time: by then p.chainID names
 	// whatever is loaded *now*, which is the thing the guard exists to
 	// distinguish this chain from.
 	chainID := p.chainID
 	buffered := p.buffered
 	// The beep.Callback runs with the speaker mutex held, so we
 	// dispatch to a goroutine that can safely acquire p.mu.
 	speaker.Play(beep.Seq(
 		p.speakerStreamer,
 		beep.Callback(func() {
-			// Asked here rather than under p.mu: this is the chain that
+			go p.onPlaybackFinished()
 			// just ended, and by the time the goroutine holds the lock
 			// p.buffered may be a different one.
 			var err error
 			if buffered != nil {
 				err = buffered.Err()
 			}
 			go p.onPlaybackFinished(chainID, err)
 		}),
 	))
 	p.state = Paused
 }
-// onPlaybackFinished handles a track that stopped streaming, whether
+// onPlaybackFinished handles the natural end of a track. It is
-// it ended or broke. It is called on a new goroutine from the beep
+// called on a new goroutine from the beep callback (which holds
-// callback (which holds the speaker lock) so that it can safely
+// the speaker lock) so that it can safely acquire p.mu.
-// acquire p.mu.
+func (p *Player) onPlaybackFinished() {
 //
 // chainID names the streamer chain the callback fired for and srcErr
 // says why it stopped.
 func (p *Player) onPlaybackFinished(chainID uint64, srcErr error) {
 	p.mu.Lock()
 	// The player has moved on while this callback queued for the lock
 	// -- a user pressing Next during the last second of a track is
 	// enough. Everything below is about the *current* track: rewinding
 	// the decoder, saying playback stopped, asking the queue to
 	// advance. Doing any of it now would do it to the wrong track.
 	if chainID != p.chainID {
 		p.mu.Unlock()
 		p.logger.Debug(
 			"Ignoring finished callback for a superseded chain",
 			"chain", chainID, "current", p.chainID,
 		)
 		return
 	}
 	p.state = Stopped
 	handler := p.playbackFinishedHandler
 	mc := p.mediaControls
@@ -578,11 +501,10 @@ func (p *Player) onPlaybackFinished(chainID uint64, srcErr error) {
 	// the Stopped state anyway, so this only moves the decoder.
 	p.rewindLocked()
 	p.emitPositionLocked()
 	p.mu.Unlock()
-	// Emitted under p.mu, like every other transition in this file.
+	// Emit Wails events outside the lock — these are non-blocking
-	// Outside it, a Play() taking the lock in the gap emits `playing`
+	// calls that don't need player state.
 	// first and this stale `stopped` lands last -- leaving the button
 	// showing play over a track that is audibly running.
 	p.emitPlaybackFinished()
 	events.Emit(
@@ -591,8 +513,6 @@ func (p *Player) onPlaybackFinished(chainID uint64, srcErr error) {
 		map[string]string{"state": string(Stopped)},
 	)
 	p.mu.Unlock()
 	// Notify media controls outside the lock. The track just
 	// ended so position is 0.
 	if mc != nil {
@@ -601,19 +521,12 @@ func (p *Player) onPlaybackFinished(chainID uint64, srcErr error) {
 		)
 	}
-	if srcErr != nil {
+	p.logger.Info("Playback finished naturally")
 		p.logger.Error(
 			"Playback stopped: the audio source failed",
 			"err", srcErr,
 		)
 	} else {
 		p.logger.Info("Playback finished naturally")
 	}
 	// Notify queue for auto-advance. Called without p.mu held
 	// because it re-enters the player via LoadFile/Play.
 	if handler != nil {
-		handler(srcErr)
+		handler()
 	}
 }
@@ -674,18 +587,6 @@ func (p *Player) loadFileLocked(filePath string) error {
 	p.currentFile = f
 	// The decoder's own format, kept for the paths that rebuild the
 	// chain later: Play()'s replay branch resamples from it, so a
 	// stale rate there plays a finished track back at the wrong speed.
 	p.format = format
 	// The previous track's duration must not outlive it.  This is set
 	// again by emitTrackChanged below, but only when the database has
 	// a row for the file -- and every position this player reports is
 	// scaled by it, so inheriting means every report is wrong by the
 	// ratio between two unrelated tracks.
 	p.trackLengthMs = 0
 	if err := p.updateStreamers(
 		streamer, format.SampleRate,
 	); err != nil {
@@ -890,10 +791,6 @@ func (p *Player) SetVolume(desiredVolume UserVolume) {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 	if p.systemVolume {
 		return
 	}
 	p.setVolumeLocked(desiredVolume)
 	p.emitVolumeChanged()
 	p.saveState()
@@ -942,10 +839,6 @@ func (p *Player) ChangeVolume(deltaVolume int) error {
 	p.mu.Lock()
 	defer p.mu.Unlock()
 	if p.systemVolume {
 		return nil
 	}
 	p.setVolumeLocked(p.getUserVolume() + UserVolume(deltaVolume))
 	p.emitVolumeChanged()
 	p.saveState()
@@ -976,14 +869,6 @@ func (p *Player) MuteToggle() error {
 		return errNoAudioFileLoaded
 	}
 	// Mute is a level of zero by another name, so it goes with the rest
 	// of the volume where the system owns it -- and it would be the one
 	// state on such a platform the user could not get out of, since with
 	// no control rendered there is nothing left to un-mute with.
 	if p.systemVolume {
 		return nil
 	}
 	speaker.Lock()
 	p.volume.Silent = !p.volume.Silent
 	speaker.Unlock()
@@ -1021,8 +906,6 @@ func (p *Player) CurrentPosition() (int, error) {
 		return 0, errNoAudioFileLoaded
 	}
 	defer p.lockSourceLocked()()
 	speaker.Lock()
 	pos := math.Round(
 		100.0 * float64(p.seeker.Position()) /
@@ -1041,28 +924,6 @@ func (p *Player) Seek(targetSeconds int) error {
 	return p.seekLocked(targetSeconds)
 }
 // lockSourceLocked blocks the read-ahead goroutine from touching the
 // decoder and returns the function that releases it, so a caller can
 // `defer p.lockSourceLocked()()`.
 //
 // Reading the decoder's position is a read *of the decoder*, and the
 // speaker lock does not exclude the read-ahead goroutine -- it never
 // takes it.  That was a genuine data race on every position emit,
 // once a second for the whole of playback.
 //
 // srcMu is not reentrant, so nothing that already holds it may call
 // this; seekSourceLocked exists to keep that region free of emits.
 // Must be called with p.mu held.
 func (p *Player) lockSourceLocked() func() {
 	if p.buffered == nil {
 		return func() {}
 	}
 	p.buffered.LockSource()
 	return p.buffered.UnlockSource
 }
 // rewindLocked returns the decoder to the start of the track without
 // touching playback state.  Must be called with p.mu held.
 func (p *Player) rewindLocked() {
@@ -1098,46 +959,6 @@ func (p *Player) seekLocked(targetSeconds int) error {
 		return fmt.Errorf("cannot get track length: %w", err)
 	}
 	// The source lock is released before anything below is emitted:
 	// emitPositionLocked reads the decoder's position and takes the
 	// same lock, which is not reentrant.
 	seekErr := p.seekSourceLocked(targetSeconds, lengthSecs)
 	if seekErr != nil {
 		p.logger.Warn(
 			"Seek failed, playback will start from "+
 				"the beginning",
 			"target-seconds", targetSeconds,
 			"err", seekErr,
 		)
 		// The optimistic move the UI already made has to be taken
 		// back, and only the backend knows it did not happen.
 		events.Emit(p.ctx, events.SeekFailed)
 		p.emitPositionLocked()
 		return fmt.Errorf("failed to seek: %w", seekErr)
 	}
 	if p.mediaControls != nil {
 		p.mediaControls.NotifySeek(targetSeconds)
 	}
 	// Report the landing position immediately rather than leaving the
 	// UI to guess until the next tick — this is the half of H-3 that
 	// desynced the seek bar by 30 s over four keyboard seeks.
 	p.emitPositionLocked()
 	return nil
 }
 // seekSourceLocked moves the decoder and flushes the stale read-ahead
 // behind it.  It owns the source lock for exactly that long and
 // emits nothing, so its caller is free to read the position
 // afterwards.  Must be called with p.mu held.
 func (p *Player) seekSourceLocked(
 	targetSeconds int,
 	lengthSecs int,
 ) error {
 	// Block the read-ahead goroutine from reading the source while
 	// we seek it. The decoder (e.g. FLAC's bufseekio.ReadSeeker) is
 	// not safe for concurrent Read+Seek, and read-ahead runs on its
@@ -1193,11 +1014,19 @@ func (p *Player) seekSourceLocked(
 	if seekErr != nil {
 		speaker.Unlock()
-		p.logger.Debug(
+		p.logger.Warn(
-			"seek rejected by the decoder",
+			"Seek failed, playback will start from "+
-			"samples", samples, "err", seekErr,
+				"the beginning",
 			"target-seconds", targetSeconds,
 			"samples", samples,
 			"err", seekErr,
 		)
 		// The optimistic move the UI already made has to be taken
 		// back, and only the backend knows it did not happen.
 		events.Emit(p.ctx, events.SeekFailed)
 		p.emitPositionLocked()
 		return fmt.Errorf("failed to seek: %w", seekErr)
 	}
@@ -1210,6 +1039,15 @@ func (p *Player) seekSourceLocked(
 		p.buffered.Flush()
 	}
 	if p.mediaControls != nil {
 		p.mediaControls.NotifySeek(targetSeconds)
 	}
 	// Report the landing position immediately rather than leaving the
 	// UI to guess until the next tick — this is the half of H-3 that
 	// desynced the seek bar by 30 s over four keyboard seeks.
 	p.emitPositionLocked()
 	return nil
 }
@@ -1302,10 +1140,6 @@ func (p *Player) seekerLengthSecsLocked() (int, error) {
 		return 0, errNoAudioFileLoaded
 	}
 	// Len is fixed for the life of the decoder, so unlike Position it
 	// races with nothing and needs no source lock -- which it must not
 	// take anyway: displayPositionSecsLocked calls this while holding
 	// it, and srcMu is not reentrant.
 	speaker.Lock()
 	length := p.seeker.Len() / int(p.format.SampleRate)
 	speaker.Unlock()
@@ -1322,8 +1156,6 @@ func (p *Player) displayPositionSecsLocked() int {
 		return 0
 	}
 	defer p.lockSourceLocked()()
 	speaker.Lock()
 	pos := p.seeker.Position()
 	total := p.seeker.Len()
@@ -1434,15 +1266,7 @@ func (p *Player) saveState() {
 	volume := int64(DefaultUserVol)
 	muted := false
-	switch {
+	if p.volume != nil {
 	case p.systemVolume:
 		// The maximum this platform runs at is not a level anybody
 		// chose, so it is not one to remember.  Writing back what
 		// restore found keeps the row a description of the user's
 		// setting without needing a second query that omits the column.
 		volume = int64(p.storedVolume)
 		muted = p.storedMuted
 	case p.volume != nil:
 		volume = int64(p.getUserVolume())
 		muted = p.volume.Silent
 	}
@@ -1526,20 +1350,11 @@ func (p *Player) restoreStateLocked() {
 		}
 	}
-	if p.systemVolume {
+	vol := clampVolume(UserVolume(state.Volume))
-		// Remembered, not applied: the device's keys are the volume
+	p.setVolumeLocked(vol)
 		// control here, so the player runs wide open and hands the
 		// stored level back untouched at the next save.
 		p.storedVolume = clampVolume(UserVolume(state.Volume))
 		p.storedMuted = state.Muted
 		p.setVolumeLocked(MaxUserVol)
 	} else {
 		vol := clampVolume(UserVolume(state.Volume))
 		p.setVolumeLocked(vol)
-		if state.Muted {
+	if state.Muted {
-			p.volume.Silent = true
+		p.volume.Silent = true
 		}
 	}
 	// Restore last track if the file still exists.
@@ -1579,9 +1394,8 @@ func (p *Player) restoreStateLocked() {
 	}
 	p.logger.Info("Player state restored",
-		"volume", p.getUserVolume(),
+		"volume", vol,
-		"muted", p.volume.Silent,
+		"muted", state.Muted,
 		"systemVolume", p.systemVolume,
 		"trackPath", state.LastTrackPath,
 		"positionSeconds", state.LastPositionSeconds,
 	)
@@ -1,42 +0,0 @@
 package player
 // Who owns the volume, and what follows when it is not us.
 //
 // On Android the hardware keys *are* the volume control and the
 // framework mixes our stream against the device level, so a second
 // control inside the app is a slider that moves something the user
 // already moved (#64).  Where that is true the player's own level sits
 // at maximum, nothing changes it, and nothing persists it.
 //
 // **The predicate is named after the capability, not the platform.**
 // The frontend asks "is there a volume for me to control", which is a
 // question about this build; asking "is this a phone" instead would
 // key the answer to a viewport, and an Android tablet at 600px or more
 // would then draw the bottom bar's slider over a level pinned at
 // maximum -- a control that cannot act, which is the thing
 // `library-status-indicator` already settled is worse than none.
 //
 // **Only `platformOwnsVolume` is behind a build tag**, in two files
 // that declare nothing else.  A tagged file is compiled by nothing
 // `make lint` or `make test` runs and is untestable off a phone, which
 // is the reasoning `mediacontrols/androidpayload.go` states for
 // keeping its contract out of one -- so everything decidable here is
 // decided against `Player.systemVolume`, a field a test sets either
 // way, and the tag decides only what that field starts as.
 //
 // The one thing this must not disturb is ducking.  `SetDuck` applies
 // its attenuation by re-applying the *user's* level through
 // `setVolumeLocked`, so pinning that level to maximum leaves the
 // offset arithmetic exactly as it was: an OS asking us to get out of
 // the way of a navigation prompt is not the user setting a volume, and
 // it is the only thing that may move the output on such a platform.
 // SystemOwnsVolume reports whether the platform's own control is the
 // only volume control there is, so this app neither offers one nor
 // remembers a level.
 //
 // It is bound: the frontend renders no `<volume-control>` when it is
 // true, at any width.
 func (p *Player) SystemOwnsVolume() bool {
 	return p.systemVolume
 }
@@ -1,11 +0,0 @@
 //go:build android
 package player
 // platformOwnsVolume is true on Android: volume is the device's, set
 // with the hardware keys, and `mediacontrols`' Android handler
 // implements no volume callback for the same reason.
 //
 // See systemvolume.go for why this constant is the whole of what a
 // build tag decides here.
 const platformOwnsVolume = true
@@ -1,10 +0,0 @@
 //go:build !android
 package player
 // platformOwnsVolume is false everywhere but Android: a desktop mixer
 // is per-application, so our level is the one the user reaches for.
 //
 // See systemvolume.go for why this constant is the whole of what a
 // build tag decides here.
 const platformOwnsVolume = false
@@ -1,215 +0,0 @@
 package player
 import (
 	"log/slog"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 	"github.com/gopxl/beep/v2/effects"
 	"yellowjacket/backend/database"
 )
 // pinnedPlayer is a player on a platform whose volume belongs to the
 // device.  The field is set rather than the build constant read,
 // because the constant is true on exactly one platform and no tier
 // here runs on it -- see systemvolume.go.
 func pinnedPlayer(t *testing.T, db *database.DB) *Player {
 	t.Helper()
 	p := NewPlayer(slog.Default(), db)
 	p.systemVolume = true
 	p.volume = &effects.Volume{Base: 2}
 	p.setVolumeLocked(MaxUserVol)
 	return p
 }
 // TestSystemVolumeRefusesEveryWayToChangeTheLevel is the first half of
 // #64: where the device owns the volume, ours sits at maximum and none
 // of the three routes to a level moves it.  Mute is in that list
 // because it is a level of zero by another name, and because with no
 // control rendered it is the one state on such a platform there would
 // be nothing to get out of.
 func TestSystemVolumeRefusesEveryWayToChangeTheLevel(t *testing.T) {
 	t.Parallel()
 	p := pinnedPlayer(t, nil)
 	if !p.SystemOwnsVolume() {
 		t.Fatal("SystemOwnsVolume() = false on a pinned player")
 	}
 	if got := p.getUserVolume(); got != MaxUserVol {
 		t.Errorf("starting volume = %d, want %d", got, MaxUserVol)
 	}
 	p.SetVolume(20)
 	if got := p.getUserVolume(); got != MaxUserVol {
 		t.Errorf("volume after SetVolume(20) = %d, want %d", got, MaxUserVol)
 	}
 	if err := p.ChangeVolume(-30); err != nil {
 		t.Fatalf("ChangeVolume: %v", err)
 	}
 	if got := p.getUserVolume(); got != MaxUserVol {
 		t.Errorf("volume after ChangeVolume(-30) = %d, want %d", got, MaxUserVol)
 	}
 	if err := p.MuteToggle(); err != nil {
 		t.Fatalf("MuteToggle: %v", err)
 	}
 	if p.volume.Silent {
 		t.Error("MuteToggle silenced a player whose volume the system owns")
 	}
 }
 // TestAnUnpinnedPlayerStillChangesItsVolume is the other side of the
 // same switch.  Without it the test above passes on a player that
 // refuses everything, which is what a mis-wired field would produce.
 func TestAnUnpinnedPlayerStillChangesItsVolume(t *testing.T) {
 	t.Parallel()
 	p := NewPlayer(slog.Default(), nil)
 	p.volume = &effects.Volume{Base: 2}
 	p.setVolumeLocked(MaxUserVol)
 	if p.SystemOwnsVolume() {
 		t.Fatal("SystemOwnsVolume() = true off Android")
 	}
 	p.SetVolume(20)
 	if got := p.getUserVolume(); got != 20 {
 		t.Errorf("volume after SetVolume(20) = %d, want 20", got)
 	}
 	if err := p.MuteToggle(); err != nil {
 		t.Fatalf("MuteToggle: %v", err)
 	}
 	if !p.volume.Silent {
 		t.Error("MuteToggle did not silence an ordinary player")
 	}
 }
 // TestSystemVolumeStillDucks is the issue's second Finding, made a
 // test: pinning the user's level must leave the OS's attenuation
 // working, because a duck is not a volume the user chose and is the
 // only thing that may move the output on such a platform.
 func TestSystemVolumeStillDucks(t *testing.T) {
 	t.Parallel()
 	p := pinnedPlayer(t, nil)
 	open := p.volume.Volume
 	p.SetDuck(true)
 	if p.volume.Volume >= open {
 		t.Errorf(
 			"ducked output = %v, want less than %v", p.volume.Volume, open,
 		)
 	}
 	if got := p.getUserVolume(); got != MaxUserVol {
 		t.Errorf("user volume while ducked = %d, want %d", got, MaxUserVol)
 	}
 	// A refused SetVolume must not disturb the offset either: it
 	// returns before setVolumeLocked, which is what re-applies it.
 	ducked := p.volume.Volume
 	p.SetVolume(10)
 	if p.volume.Volume != ducked {
 		t.Errorf(
 			"output after a refused SetVolume = %v, want %v",
 			p.volume.Volume, ducked,
 		)
 	}
 	p.SetDuck(false)
 	if p.volume.Volume != open {
 		t.Errorf("output after unduck = %v, want %v", p.volume.Volume, open)
 	}
 }
 // TestSystemVolumeWritesBackTheLevelItFound is the rest of the
 // Direction: "make sure nothing writes a persisted volume from that
 // platform".  The maximum the player runs at is synthetic, so saving
 // must not record it over whatever the row already said.
 func TestSystemVolumeWritesBackTheLevelItFound(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	// A level set by some earlier, unpinned session.
 	writer := NewPlayer(slog.Default(), db)
 	writer.volume = &effects.Volume{Base: 2}
 	writer.setVolumeLocked(30)
 	writer.SaveState()
 	p := pinnedPlayer(t, db)
 	p.RestoreState()
 	if got := p.getUserVolume(); got != MaxUserVol {
 		t.Errorf("restored volume = %d, want %d (the level is pinned)", got, MaxUserVol)
 	}
 	if p.volume.Silent {
 		t.Error("restore muted a player whose volume the system owns")
 	}
 	p.SaveState()
 	state, err := db.Queries.GetPlayerState(db.Ctx)
 	if err != nil {
 		t.Fatalf("GetPlayerState: %v", err)
 	}
 	if state.Volume != 30 {
 		t.Errorf("persisted volume = %d, want 30 (untouched)", state.Volume)
 	}
 }
 // TestPlatformVolumeOwnershipIsDeclaredOncePerPlatform sweeps the
 // source, because the pair of tagged files is the one thing here no
 // tier compiles both halves of: `make lint` and `make test` build the
 // `!android` side only, so a deleted or edited android file fails
 // nothing until somebody has a phone in their hand.
 func TestPlatformVolumeOwnershipIsDeclaredOncePerPlatform(t *testing.T) {
 	t.Parallel()
 	want := map[string]string{
 		"systemvolume_other.go":   "const platformOwnsVolume = false",
 		"systemvolume_android.go": "const platformOwnsVolume = true",
 	}
 	tags := map[string]string{
 		"systemvolume_other.go":   "//go:build !android",
 		"systemvolume_android.go": "//go:build android",
 	}
 	for name, decl := range want {
 		src, err := os.ReadFile(filepath.Join(".", name))
 		if err != nil {
 			t.Errorf("%s: %v", name, err)
 			continue
 		}
 		if !strings.Contains(string(src), decl) {
 			t.Errorf("%s does not declare %q", name, decl)
 		}
 		if !strings.Contains(string(src), tags[name]) {
 			t.Errorf("%s does not carry %q", name, tags[name])
 		}
 	}
 }
@@ -81,7 +81,6 @@ func (q *Queue) emitTracksModified(
 			Index:        index,
 			Positions:    positions,
 			CurrentIndex: q.currentIndex,
 			Source:       q.source,
 		},
 	)
 }
@@ -219,56 +219,6 @@ func TestEmit_AddTrackSendsDeltaNotSnapshot(t *testing.T) {
 	}
 }
 // The append clears the source, and the delta is the only event those
 // paths emit — so if it does not carry the source, the frontend keeps
 // the label it was last given and goes on offering a link back to an
 // album the queue no longer holds until something forces a full state.
 func TestEmit_AppendDeltaCarriesClearedSource(t *testing.T) {
 	t.Parallel()
 	q, db, rec := setupRecordedQueue(t)
 	paths := seedAudioFiles(t, db, 4)
 	q.SetQueue(
 		paths[:3], 0, false,
 		Source{Type: "album", ID: 1, Label: "Abbey Road"},
 	)
 	if _, ok := rec.Wait(events.QueueChanged, waitFor); !ok {
 		t.Fatalf("no QueueChanged after SetQueue; got %v", rec.Names())
 	}
 	rec.Reset()
 	q.AddTrack(paths[3])
 	if got := modifiedOf(t, rec).Source; got != (Source{}) {
 		t.Errorf("delta source = %+v, want zero value", got)
 	}
 }
 // And a delta that did not clear it still reports the source it has,
 // or the frontend would drop a perfectly good label on every removal.
 func TestEmit_NonAppendDeltaCarriesSource(t *testing.T) {
 	t.Parallel()
 	q, db, rec := setupRecordedQueue(t)
 	paths := seedAudioFiles(t, db, 4)
 	album := Source{Type: "album", ID: 1, Label: "Abbey Road"}
 	q.SetQueue(paths, 0, false, album)
 	if _, ok := rec.Wait(events.QueueChanged, waitFor); !ok {
 		t.Fatalf("no QueueChanged after SetQueue; got %v", rec.Names())
 	}
 	rec.Reset()
 	q.RemoveTrack(3)
 	if got := modifiedOf(t, rec).Source; got != album {
 		t.Errorf("delta source = %+v, want %+v", got, album)
 	}
 }
 func TestEmit_RemoveTracksReportsPositions(t *testing.T) {
 	t.Parallel()
@@ -83,7 +83,7 @@ func TestFallback_TriggersOnNaturalFinish(t *testing.T) {
 	q.SetFallbackSource(fake)
 	q.SetQueue(seedPaths, 0, false, Source{Type: "album", ID: 1, Label: "Seed Album"})
-	q.OnPlaybackFinished(nil)
+	q.OnPlaybackFinished()
 	waitUntil(t, func() bool { return fake.callCount() == 1 }, "fallback to be resolved")
 	waitUntil(t, func() bool {
@@ -159,7 +159,7 @@ func TestFallback_EmptyResultLeavesQueueExhausted(t *testing.T) {
 	q.SetFallbackSource(fake)
 	q.SetQueue(seedPaths, 0, false, Source{})
-	q.OnPlaybackFinished(nil)
+	q.OnPlaybackFinished()
 	waitUntil(t, func() bool { return fake.callCount() == 1 }, "fallback to be resolved")
@@ -193,7 +193,7 @@ func TestFallback_StaleResolutionDiscarded(t *testing.T) {
 	q.SetFallbackSource(fake)
 	q.SetQueue(seedPaths, 0, false, Source{})
-	q.OnPlaybackFinished(nil) // starts resolving, blocked on gate
+	q.OnPlaybackFinished() // starts resolving, blocked on gate
 	time.Sleep(20 * time.Millisecond) // let the goroutine reach the gate
@@ -1,78 +0,0 @@
 package queue
 import (
 	"errors"
 	"testing"
 	"yellowjacket/backend/events"
 )
 // errTestDecode stands in for a decoder blowing up mid-track.
 var errTestDecode = errors.New("decode blew up")
 // currentIndex == -1 against a non-empty queue is a state this
 // package produces on purpose: onQueueExhausted(false) sets it and
 // deliberately leaves the finished track loaded in the player, so it
 // stays on the now-playing bar. Pressing play from there and letting
 // it finish re-enters OnPlaybackFinished with exactly that pair --
 // which used to index q.tracks[-1] and panic, on a goroutine
 // dispatched from the audio callback with no caller to recover it.
 func TestFinishedWithNoCurrentTrackDoesNotPanic(t *testing.T) {
 	t.Parallel()
 	tests := []struct {
 		name  string
 		index int
 	}{
 		{"exhausted queue leaves -1", -1},
 		{"index past the end", 3},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 			q, _, _ := setupRecordedQueue(t)
 			q.tracks = []Track{
 				{FilePath: "/a.mp3"},
 				{FilePath: "/b.mp3"},
 			}
 			q.currentIndex = tt.index
 			// The assertion is that this returns at all.
 			q.OnPlaybackFinished(nil)
 			if q.currentIndex != tt.index {
 				t.Errorf(
 					"an out-of-range index was acted on: %d became %d",
 					tt.index, q.currentIndex,
 				)
 			}
 		})
 	}
 }
 // A track that broke mid-playback is not a track that was listened
 // to. The player cannot say so itself -- the metadata is here -- so
 // it hands the reason over and this is where it becomes a
 // PlaybackFailed rather than a silent auto-advance.
 func TestAFailedTrackIsReportedAndNotCountedAsAPlay(t *testing.T) {
 	t.Parallel()
 	q, _, rec := setupRecordedQueue(t)
 	q.tracks = []Track{
 		{FilePath: "/a.mp3", Title: "A", AudioFileID: 1},
 		{FilePath: "/b.mp3", Title: "B", AudioFileID: 2},
 	}
 	q.currentIndex = 0
 	q.OnPlaybackFinished(errTestDecode)
 	if _, ok := rec.Last(events.PlaybackFailed); !ok {
 		t.Errorf(
 			"a track that failed mid-playback told the user nothing; "+
 				"got %v",
 			rec.Names(),
 		)
 	}
 }
@@ -1,45 +1,18 @@
 package queue
-// OnPlaybackFinished is called when a track stops streaming. This
+// OnPlaybackFinished is called when a track finishes playing naturally.
-// drives the auto-advance behavior and records the play.
+// This drives the auto-advance behavior and records the play.
-//
+func (q *Queue) OnPlaybackFinished() {
 // srcErr says why the track stopped: nil for one that reached its
 // end, non-nil for one that broke partway through.  The player cannot
 // tell the user which, because the metadata lives here -- so a failure
 // is reported as PlaybackFailed and *not* recorded as a play, while
 // the advance happens either way.  Before this, a file that failed
 // mid-track advanced in silence and was counted as listened to.
 //
 //wails:ignore // internal wiring, not part of the app's IPC surface.
 func (q *Queue) OnPlaybackFinished(srcErr error) {
 	q.mu.Lock()
-	// currentIndex is -1 whenever the queue has been exhausted, and
+	if len(q.tracks) == 0 {
 	// onQueueExhausted deliberately leaves the finished track loaded
 	// in the player -- so a natural finish can re-enter here against a
 	// queue that is not empty and an index that is not valid.  Every
 	// other path in this package bounds-checks before indexing; this
 	// one panicked, on a goroutine with no caller to recover it.
 	if q.currentIndex < 0 || q.currentIndex >= len(q.tracks) {
 		q.mu.Unlock()
 		return
 	}
 	// Capture the track that just finished before advancing.
-	finished := q.tracks[q.currentIndex]
+	finishedID := q.tracks[q.currentIndex].AudioFileID
 	finishedID := finished.AudioFileID
 	if srcErr != nil {
 		q.emitPlaybackFailed(finished, srcErr)
 	}
 	// A track that broke was not listened to.
 	recordFinished := func() {
 		if srcErr == nil {
 			q.recordPlay(finishedID)
 		}
 	}
 	// Repeat One: replay the current track.
 	if q.repeatMode == RepeatOne {
@@ -48,7 +21,7 @@ func (q *Queue) OnPlaybackFinished(srcErr error) {
 		}
 		q.mu.Unlock()
-		recordFinished()
+		q.recordPlay(finishedID)
 		return
 	}
@@ -58,7 +31,7 @@ func (q *Queue) OnPlaybackFinished(srcErr error) {
 		// Queue exhausted — this is the extension point for a future fallback playlist.
 		q.onQueueExhausted(false)
 		q.mu.Unlock()
-		recordFinished()
+		q.recordPlay(finishedID)
 		return
 	}
@@ -71,12 +44,12 @@ func (q *Queue) OnPlaybackFinished(srcErr error) {
 	if !q.playCurrentOrSkip(true, q.nextIndex) {
 		q.onQueueExhausted(false)
 		q.mu.Unlock()
-		recordFinished()
+		q.recordPlay(finishedID)
 		return
 	}
 	q.emitIndexChanged()
 	q.mu.Unlock()
-	recordFinished()
+	q.recordPlay(finishedID)
 }
@@ -107,7 +107,7 @@ func TestPlaybackFailed_AutoAdvanceSkipsPastIt(t *testing.T) {
 	// The first track finished: auto-advance lands on the missing
 	// file and must step over it rather than stopping dead.
-	q.OnPlaybackFinished(nil)
+	q.OnPlaybackFinished()
 	if got := q.GetState().CurrentIndex; got != 2 {
 		t.Errorf("currentIndex after skipping: got %d, want 2", got)
@@ -183,7 +183,7 @@ func TestQueueExhausted_KeepsTheFinishedTrackLoaded(t *testing.T) {
 	q.SetQueue(paths, 0, false, Source{})
 	q.Play()
-	q.OnPlaybackFinished(nil)
+	q.OnPlaybackFinished()
 	if q.GetState().CurrentIndex != -1 {
 		t.Errorf(
@@ -156,21 +156,12 @@ type PlaybackFailure struct {
 }
 // TracksModified is the payload for the QueueTracksModified event.
 //
 // Source is carried because an append is exactly what can *invalidate*
 // it: a queue built from one album stops being that album the moment a
 // track from somewhere else is added to it. The delta is the only event
 // those paths emit, so without this the frontend would keep the label
 // it was last given and go on saying "Playing from" an album that is no
 // longer what is queued — an event carrying what its consumer needs, so
 // nothing has to invalidate anything.
 type TracksModified struct {
 	Action       string  `json:"action"`
 	Tracks       []Track `json:"tracks,omitempty"`
 	Index        int     `json:"index"`
 	Positions    []int   `json:"positions,omitempty"`
 	CurrentIndex int     `json:"currentIndex"`
 	Source       Source  `json:"source"`
 }
 // Queue manages an ordered list of tracks for playback.
@@ -464,8 +455,6 @@ func (q *Queue) AddTrack(filePath string) {
 		q.generateShuffleOrder()
 	}
 	q.dropSource()
 	q.persistAddTrack(track)
 	q.persistState()
 	q.emitTracksModified(
@@ -516,8 +505,6 @@ func (q *Queue) AddTracks(filePaths []string) {
 		q.generateShuffleOrder()
 	}
 	q.dropSource()
 	q.persistAddTracks(newTracks)
 	q.persistState()
 	q.emitTracksModified(
@@ -576,8 +563,6 @@ func (q *Queue) InsertNextTracks(filePaths []string) {
 		q.generateShuffleOrder()
 	}
 	q.dropSource()
 	q.persistInsertTracks(newTracks, insertPos)
 	q.persistState()
 	q.emitTracksModified(
@@ -628,8 +613,6 @@ func (q *Queue) InsertNext(filePath string) {
 		q.generateShuffleOrder()
 	}
 	q.dropSource()
 	q.persistInsertTracks([]Track{track}, insertPos)
 	q.persistState()
 	q.emitTracksModified(
@@ -697,8 +680,6 @@ func (q *Queue) InsertTracksAt(filePaths []string, index int) {
 		q.generateShuffleOrder()
 	}
 	q.dropSource()
 	q.persistInsertTracks(newTracks, index)
 	q.persistState()
 	q.emitTracksModified(
@@ -1556,31 +1537,6 @@ func (q *Queue) reindexPositions() {
 	}
 }
 // dropSource forgets which collection the queue was built from.
 //
 // A Source is a claim that everything queued came from one album,
 // playlist, genre or artist, and the frontend renders it as a
 // "Playing from X" link back to that page. Adding or inserting a track
 // makes the claim false — the queue is now that album *plus* something
 // else — so every path that does so calls this.
 //
 // It was set by SetQueue and cleared in exactly one place, Clear, so a
 // label survived every append. It is persisted too (source_type /
 // source_id / source_label on the queue state row), which is what made
 // a wrong label outlive the session that earned it: an album queued on
 // Monday, added to on Tuesday, still offered a link back to that album
 // on Friday.
 //
 // Removing, reordering and shuffling deliberately do not call this. A
 // queue with a track taken out of it, or played in another order, is
 // still that album — the link still goes somewhere true. Only the
 // arrival of a track from elsewhere makes it a lie.
 //
 // The caller must hold q.mu.
 func (q *Queue) dropSource() {
 	q.source = Source{}
 }
 // commitMutation persists the current queue state after a mutation.
 // When reindex is true, track positions are renumbered first.
 // The caller must hold q.mu.
@@ -126,117 +126,6 @@ func TestClear_ResetsSource(t *testing.T) {
 	}
 }
 // A queue built from one album stops being that album the moment a
 // track from somewhere else joins it, so every path that adds one
 // drops the source. Before this, SetQueue was the only writer and
 // Clear the only clearer, so "Playing from Abbey Road" outlived every
 // append — and, being persisted, every restart too.
 func TestAppendPathsDropSource(t *testing.T) {
 	t.Parallel()
 	album := Source{Type: "album", ID: 1, Label: "Abbey Road"}
 	tests := []struct {
 		name   string
 		append func(q *Queue, paths []string)
 	}{
 		{
 			name: "AddTrack",
 			append: func(q *Queue, paths []string) {
 				q.AddTrack(paths[5])
 			},
 		},
 		{
 			name: "AddTracks",
 			append: func(q *Queue, paths []string) {
 				q.AddTracks(paths[5:7])
 			},
 		},
 		{
 			name: "InsertNext",
 			append: func(q *Queue, paths []string) {
 				q.InsertNext(paths[5])
 			},
 		},
 		{
 			name: "InsertNextTracks",
 			append: func(q *Queue, paths []string) {
 				q.InsertNextTracks(paths[5:7])
 			},
 		},
 		{
 			name: "InsertTracksAt",
 			append: func(q *Queue, paths []string) {
 				q.InsertTracksAt(paths[5:7], 1)
 			},
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 			q, db := setupTestQueue(t)
 			paths := seedAudioFiles(t, db, 8)
 			q.SetQueue(paths[:5], 0, false, album)
 			if got := q.GetState().Source; got != album {
 				t.Fatalf("source before append: got %+v, want %+v", got, album)
 			}
 			tt.append(q, paths)
 			if got := q.GetState().Source; got != (Source{}) {
 				t.Errorf(
 					"source after %s: got %+v, want zero value",
 					tt.name, got,
 				)
 			}
 		})
 	}
 }
 // Removing and reordering deliberately do not drop it: a queue with a
 // track taken out of it is still that album, and the link still goes
 // somewhere true.
 func TestRemoveAndMoveKeepSource(t *testing.T) {
 	t.Parallel()
 	album := Source{Type: "album", ID: 1, Label: "Abbey Road"}
 	t.Run("RemoveTrack", func(t *testing.T) {
 		t.Parallel()
 		q, db := setupTestQueue(t)
 		paths := seedAudioFiles(t, db, 5)
 		q.SetQueue(paths, 0, false, album)
 		q.RemoveTrack(3)
 		if got := q.GetState().Source; got != album {
 			t.Errorf("source after RemoveTrack: got %+v, want %+v", got, album)
 		}
 	})
 	t.Run("MoveQueueTracks", func(t *testing.T) {
 		t.Parallel()
 		q, db := setupTestQueue(t)
 		paths := seedAudioFiles(t, db, 5)
 		q.SetQueue(paths, 0, false, album)
 		q.MoveQueueTracks([]int{0}, 3)
 		if got := q.GetState().Source; got != album {
 			t.Errorf(
 				"source after MoveQueueTracks: got %+v, want %+v",
 				got, album,
 			)
 		}
 	})
 }
 func TestSetQueue_WithStartIndex(t *testing.T) {
 	t.Parallel()
@@ -24,19 +24,10 @@ func DefaultBindings() map[string]string {
 		"player.repeat":      "R",
 		"player.mute":        "M",
-		// Navigation (Global scope).  Back and forward are the browser's
+		// Navigation (Global scope)
 		// own combination on every platform, which is the whole design
 		// brief for them: the app has one global history and this is the
 		// gesture people already have for it.  The modifier is what keeps
 		// them clear of `player.seekBack`/`seekForward`, which are the
 		// bare arrows -- a binding is matched on its full canonical
 		// string, so "Alt+Left" and "Left" are different keys and not a
 		// conflict.
 		"nav.search":    "/",
 		"nav.searchAlt": "Ctrl+F",
 		"nav.queue":     "Q",
 		"nav.back":      "Alt+Left",
 		"nav.forward":   "Alt+Right",
 		// App actions
 		"app.selectAll": "Ctrl+A",
@@ -28,7 +28,6 @@ var (
 	errUnsupportedOp    = errors.New("unsupported operator")
 	errInvalidSortField = errors.New("invalid sort field: not in allowed field list")
 	errNotNumeric       = errors.New("value must be numeric")
 	errInvalidMatch     = errors.New("match must be \"all\" or \"any\"")
 )
 // Rule represents a single filter condition for a smart playlist.
@@ -38,45 +37,13 @@ type Rule struct {
 	Value    string `json:"value"`
 }
 // MatchType decides how a rule set's conditions combine.
 //
 // The rules used to be joined with " AND " and nothing else, so a
 // playlist could only ever narrow: "jazz released after 1960" was
 // expressible and "jazz or blues" was not, which is most of what
 // anyone reaches for a second rule to say.
 type MatchType string
 const (
 	// MatchAll requires every rule to hold — the historical behaviour,
 	// and what an empty match means so that every rule set written
 	// before this existed keeps the meaning it was saved with.
 	MatchAll MatchType = "all"
 	// MatchAny requires at least one rule to hold.
 	MatchAny MatchType = "any"
 )
 // joiner returns the SQL keyword that combines two conditions.
 // An unrecognised value cannot reach here — ParseRuleSet rejects one
 // — so the default is about the empty string, which is every rule set
 // saved before this field existed.
 func (m MatchType) joiner() string {
 	if m == MatchAny {
 		return " OR "
 	}
 	return " AND "
 }
 // RuleSet holds the complete filter configuration for a smart
 // playlist, including optional sort and limit.
 type RuleSet struct {
-	Rules []Rule `json:"rules"`
+	Rules     []Rule `json:"rules"`
-	// Match is "all" or "any"; empty means "all". It is omitempty so
+	Limit     int    `json:"limit,omitempty"`
-	// an untouched playlist's stored JSON does not change shape.
+	SortField string `json:"sort_field,omitempty"`
-	Match     MatchType `json:"match,omitempty"`
+	SortDir   string `json:"sort_dir,omitempty"`
 	Limit     int       `json:"limit,omitempty"`
 	SortField string    `json:"sort_field,omitempty"`
 	SortDir   string    `json:"sort_dir,omitempty"`
 }
 // fieldMap maps user-facing rule field names to track_metadata column
@@ -149,12 +116,7 @@ const genreDelimiter = "||"
 // slice of rules. It is a pure function — no database access needed.
 // Returns the clause (without the leading "WHERE"), the parameter
 // args, and any validation error.
-//
+func BuildWhereClause(rules []Rule) (string, []any, error) {
 // match decides how the conditions combine; an empty match is MatchAll,
 // which is what every rule set saved before the field existed means.
 func BuildWhereClause(
 	rules []Rule, match MatchType,
 ) (string, []any, error) {
 	if len(rules) == 0 {
 		return "", nil, nil
 	}
@@ -217,28 +179,7 @@ func BuildWhereClause(
 		args = append(args, condArgs...)
 	}
-	// Under OR, each condition is parenthesised; under AND it is not.
+	return strings.Join(conditions, " AND "), args, nil
 	//
 	// The asymmetry is deliberate rather than an omission. AND is the
 	// tighter operator in SQL, so an OR-join has to protect any
 	// condition that contains a top-level AND of its own or the halves
 	// come apart: `days_since_played less_than` is
 	// `last_played IS NOT NULL AND <expr> < ?`, which read without
 	// brackets under an OR-join happens to still parse correctly and
 	// would stop doing so the moment a condition grows a top-level OR.
 	// Bracketing under AND would be a no-op semantically and would
 	// rewrite the clause every existing test pins, so the brackets go
 	// exactly where they change something.
 	if match == MatchAny {
 		bracketed := make([]string, len(conditions))
 		for i, cond := range conditions {
 			bracketed[i] = "(" + cond + ")"
 		}
 		conditions = bracketed
 	}
 	return strings.Join(conditions, match.joiner()), args, nil
 }
 // validateOperator checks that the operator is valid for the field
@@ -658,7 +599,7 @@ func Evaluate(
 	start := time.Now()
 	logger := db.Logger()
-	where, args, err := BuildWhereClause(ruleSet.Rules, ruleSet.Match)
+	where, args, err := BuildWhereClause(ruleSet.Rules)
 	if err != nil {
 		return nil, fmt.Errorf(
 			"smart playlist rule error: %w", err,
@@ -1095,16 +1036,6 @@ func ParseRuleSet(jsonStr string) (RuleSet, error) {
 		)
 	}
 	// A match nobody recognises would otherwise fall through to AND,
 	// which is a playlist quietly returning the wrong tracks rather
 	// than refusing to be saved. This is the only place a rule set
 	// enters the backend, so it is the only place that has to ask.
 	if rs.Match != "" && rs.Match != MatchAll && rs.Match != MatchAny {
 		return RuleSet{}, fmt.Errorf(
 			"%w: %q", errInvalidMatch, rs.Match,
 		)
 	}
 	return rs, nil
 }
@@ -1,7 +1,6 @@
 package smartplaylist
 import (
 	"errors"
 	"strings"
 	"testing"
@@ -171,7 +170,7 @@ func TestBuildWhereClause_TextIs(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -190,7 +189,7 @@ func TestBuildWhereClause_TextIsNot(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is_not", Value: "Queen"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -210,7 +209,7 @@ func TestBuildWhereClause_TextContains(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "title", Operator: "contains", Value: "Black"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -232,7 +231,7 @@ func TestBuildWhereClause_TextDoesNotContain(t *testing.T) {
 			Field: "title", Operator: "does_not_contain",
 			Value: "Black",
 		},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -252,7 +251,7 @@ func TestBuildWhereClause_TextStartsWith(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "title", Operator: "starts_with", Value: "Back"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -271,7 +270,7 @@ func TestBuildWhereClause_TextEndsWith(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "title", Operator: "ends_with", Value: "Black"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -293,7 +292,7 @@ func TestBuildWhereClause_TextIsAnyOf(t *testing.T) {
 			Field: "artist", Operator: "is_any_of",
 			Value: `["Queen","AC/DC"]`,
 		},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -313,7 +312,7 @@ func TestBuildWhereClause_NumericIs(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "is", Value: "1980"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -332,7 +331,7 @@ func TestBuildWhereClause_NumericIsNot(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "is_not", Value: "1980"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -351,7 +350,7 @@ func TestBuildWhereClause_NumericGreaterThan(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "greater_than", Value: "2000"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -370,7 +369,7 @@ func TestBuildWhereClause_NumericLessThan(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "less_than", Value: "1980"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -392,7 +391,7 @@ func TestBuildWhereClause_NumericBetween(t *testing.T) {
 			Field: "year", Operator: "between",
 			Value: "1975,1985",
 		},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -415,7 +414,7 @@ func TestBuildWhereClause_NumericBetweenJSON(t *testing.T) {
 			Field: "year", Operator: "between",
 			Value: `["1975","1985"]`,
 		},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -435,7 +434,7 @@ func TestBuildWhereClause_GenreIsProducesSubquery(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "genre", Operator: "is", Value: "Rock"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -467,7 +466,7 @@ func TestBuildWhereClause_GenreIsNotProducesSubquery(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "genre", Operator: "is_not", Value: "Rock"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -496,7 +495,7 @@ func TestBuildWhereClause_GenreIsAnyOfProducesSubquery(t *testing.T) {
 			Field: "genre", Operator: "is_any_of",
 			Value: `["Rock","Pop"]`,
 		},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -525,7 +524,7 @@ func TestBuildWhereClause_GenreContainsUsesSubquery(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "genre", Operator: "contains", Value: "Rock"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -558,7 +557,7 @@ func TestBuildWhereClause_MultipleRulesAND(t *testing.T) {
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
 		{Field: "year", Operator: "greater_than", Value: "1975"},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -573,110 +572,6 @@ func TestBuildWhereClause_MultipleRulesAND(t *testing.T) {
 	}
 }
 func TestBuildWhereClause_MultipleRulesOR(t *testing.T) {
 	t.Parallel()
 	clause, args, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
 		{Field: "year", Operator: "greater_than", Value: "1975"},
 	}, MatchAny)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	want := "(artist_name = ? COLLATE NOCASE) OR (year > ?)"
 	if clause != want {
 		t.Errorf("clause = %q, want %q", clause, want)
 	}
 	if len(args) != 2 || args[0] != "Queen" || args[1] != int64(1975) {
 		t.Errorf("args = %v, want [Queen 1975]", args)
 	}
 }
 // An empty match is what every rule set saved before the field existed
 // carries, and it has to keep meaning AND — a playlist silently
 // widening to OR on upgrade is the whole risk of adding this field.
 func TestBuildWhereClause_EmptyMatchIsAll(t *testing.T) {
 	t.Parallel()
 	rules := []Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
 		{Field: "year", Operator: "greater_than", Value: "1975"},
 	}
 	empty, _, err := BuildWhereClause(rules, "")
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	all, _, err := BuildWhereClause(rules, MatchAll)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	if empty != all {
 		t.Errorf("empty match = %q, want the same as MatchAll %q",
 			empty, all)
 	}
 }
 // A condition carrying its own top-level AND is what makes the
 // bracketing under OR load-bearing: `days_since_played less_than`
 // is two predicates, and both belong to the same rule.
 func TestBuildWhereClause_ORBracketsCompoundCondition(t *testing.T) {
 	t.Parallel()
 	clause, _, err := BuildWhereClause([]Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
 		{
 			Field:    "days_since_played",
 			Operator: "less_than",
 			Value:    "30",
 		},
 	}, MatchAny)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	if !strings.Contains(clause, "(last_played IS NOT NULL AND") {
 		t.Errorf(
 			"compound condition is not bracketed under OR: %q",
 			clause,
 		)
 	}
 }
 func TestParseRuleSet_RejectsUnknownMatch(t *testing.T) {
 	t.Parallel()
 	_, err := ParseRuleSet(`{"rules":[],"match":"either"}`)
 	if err == nil {
 		t.Fatal("expected an error for an unknown match type")
 	}
 	if !errors.Is(err, errInvalidMatch) {
 		t.Errorf("err = %v, want errInvalidMatch", err)
 	}
 }
 func TestParseRuleSet_AcceptsAnyAndAll(t *testing.T) {
 	t.Parallel()
 	for _, want := range []MatchType{MatchAll, MatchAny} {
 		rs, err := ParseRuleSet(
 			`{"rules":[],"match":"` + string(want) + `"}`,
 		)
 		if err != nil {
 			t.Fatalf("match %q: unexpected error: %v", want, err)
 		}
 		if rs.Match != want {
 			t.Errorf("match = %q, want %q", rs.Match, want)
 		}
 	}
 }
 func TestBuildWhereClause_SameFieldMultipleTimes(t *testing.T) {
 	t.Parallel()
@@ -686,7 +581,7 @@ func TestBuildWhereClause_SameFieldMultipleTimes(t *testing.T) {
 			Field: "genre", Operator: "does_not_contain",
 			Value: "Punk",
 		},
-	}, MatchAll)
+	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -714,7 +609,7 @@ func TestBuildWhereClause_SameFieldMultipleTimes(t *testing.T) {
 func TestBuildWhereClause_EmptyRules(t *testing.T) {
 	t.Parallel()
-	clause, args, err := BuildWhereClause(nil, MatchAll)
+	clause, args, err := BuildWhereClause(nil)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -736,7 +631,7 @@ func TestBuildWhereClause_InvalidField(t *testing.T) {
 			Field: "nonexistent", Operator: "is",
 			Value: "anything",
 		},
-	}, MatchAll)
+	})
 	if err == nil {
 		t.Fatal("expected error for invalid field, got nil")
 	}
@@ -759,7 +654,7 @@ func TestBuildWhereClause_InvalidOperatorForNumeric(t *testing.T) {
 	_, _, err := BuildWhereClause([]Rule{
 		{Field: "year", Operator: "contains", Value: "1980"},
-	}, MatchAll)
+	})
 	if err == nil {
 		t.Fatal(
 			"expected error for text operator on numeric field",
@@ -781,7 +676,7 @@ func TestBuildWhereClause_InvalidOperatorForText(t *testing.T) {
 			Field: "artist", Operator: "greater_than",
 			Value: "Queen",
 		},
-	}, MatchAll)
+	})
 	if err == nil {
 		t.Fatal(
 			"expected error for numeric operator on text field",
@@ -828,80 +723,6 @@ func TestEvaluate_TextIs(t *testing.T) {
 	}
 }
 // Two rules that share no track at all: under AND this is empty, and
 // under OR it is the union. Before Match existed only the first was
 // expressible, so a playlist could only ever narrow — "jazz or blues"
 // had no way to be said.
 func TestEvaluate_MatchAnyUnionsWhereMatchAllIntersects(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	seedSmartPlaylistData(t, db)
 	// Queen has two tracks; Beyoncé has one; no track is by both.
 	rules := []Rule{
 		{Field: "artist", Operator: "is", Value: "Queen"},
 		{Field: "artist", Operator: "is", Value: "Beyoncé"},
 	}
 	all, err := Evaluate(db, RuleSet{Rules: rules, Match: MatchAll})
 	if err != nil {
 		t.Fatalf("Evaluate(all): %v", err)
 	}
 	if len(all) != 0 {
 		t.Errorf("match=all returned %d tracks, want 0", len(all))
 	}
 	either, err := Evaluate(db, RuleSet{Rules: rules, Match: MatchAny})
 	if err != nil {
 		t.Fatalf("Evaluate(any): %v", err)
 	}
 	if len(either) != 3 {
 		t.Fatalf("match=any returned %d tracks, want 3", len(either))
 	}
 	for _, tr := range either {
 		if tr.ArtistName != "Queen" && tr.ArtistName != "Beyoncé" {
 			t.Errorf(
 				"track %q has artist %q, want Queen or Beyoncé",
 				tr.TrackName, tr.ArtistName,
 			)
 		}
 	}
 }
 // An empty match is what every playlist saved before the field existed
 // carries, and it has to keep meaning AND all the way through Evaluate
 // — a stored playlist silently widening on upgrade is the only real
 // risk in adding this.
 func TestEvaluate_EmptyMatchStillIntersects(t *testing.T) {
 	t.Parallel()
 	db := database.NewTestDB(t)
 	seedSmartPlaylistData(t, db)
 	tracks, err := Evaluate(db, RuleSet{
 		Rules: []Rule{
 			{Field: "artist", Operator: "is", Value: "Queen"},
 			{Field: "year", Operator: "greater_than", Value: "1979"},
 		},
 	})
 	if err != nil {
 		t.Fatalf("Evaluate: %v", err)
 	}
 	// Only "Another One Bites the Dust" (Queen, 1980) satisfies both.
 	if len(tracks) != 1 {
 		t.Fatalf("got %d tracks, want 1", len(tracks))
 	}
 	if want := "Another One Bites the Dust"; tracks[0].TrackName != want {
 		t.Errorf("got %q, want %q", tracks[0].TrackName, want)
 	}
 }
 // TestEvaluate_ArtworkEnrichment verifies the presentation-only
 // cover-art and MusicBrainz-ID fields are attached to matched tracks
 // by the batched fetchArtwork pass (they are no longer part of the
@@ -1519,7 +1340,7 @@ func TestSQLInjection_FieldName(t *testing.T) {
 			Field:    "title; DROP TABLE playlists",
 			Operator: "is", Value: "x",
 		},
-	}, MatchAll)
+	})
 	if err == nil {
 		t.Fatal(
 			"expected error for injected field name, got nil",
@@ -16,107 +16,32 @@ var errNoBlockDevice = errors.New(
 	"no matching block device found",
 )
 // DiskProfile is what the scanner needs to know about the device a
 // library sits on.  Both fields are about the same question — how many
 // reads should be in flight at once — and they answer different halves
 // of it, so they travel together rather than as two probes.
 type DiskProfile struct {
 	// Device is the whole-disk kernel name ("sdb"), or "" when the
 	// path could not be resolved to one.
 	Device string
 	// Rotational is /sys/block/<dev>/queue/rotational: true for a
 	// spinning disk, where a seek costs milliseconds.
 	Rotational bool
 	// QueueDepth is /sys/block/<dev>/device/queue_depth — how many
 	// commands the drive will accept and reorder at once.  This is
 	// NCQ: a SATA disk with it enabled reports 31 or 32, and one
 	// without reports 1.  Zero means the file was not there to read,
 	// which is the case for anything that is not a SCSI/SATA device
 	// (NVMe, MMC, device-mapper, loop, a VM's virtio disk).
 	//
 	// It is the difference between concurrency helping and hurting.
 	// With queueing, several outstanding reads let the drive service
 	// them in the order its head passes over them, which is most of
 	// why a parallel scan is faster at all.  Without it, every extra
 	// worker is one more seek competing for one head, and the scan
 	// gets slower the harder it is pushed.
 	QueueDepth int
 }
 // Queues reports whether the drive can reorder outstanding commands.
 //
 // An unknown depth (0) counts as queueing: everything that does not
 // publish this file is a device where concurrency is fine — NVMe has
 // its own queues, virtio and device-mapper are not the physical layer
 // at all.  The only case worth being careful about is the one that
 // says so explicitly.
 func (p DiskProfile) Queues() bool {
 	return p.QueueDepth != 1
 }
 // IsRotationalDisk reports whether the block device backing the
-// given path is a rotational (spinning) disk.  Returns false on any
+// given path is a rotational (spinning) disk.  Detection uses the
-// error (assumes SSD).
+// Linux sysfs interface at /sys/block/<dev>/queue/rotational.
 // Returns false on any error (assumes SSD).
 func IsRotationalDisk(path string) bool {
-	return ProfileForPath(path).Rotational
+	dev, err := deviceForPath(path)
 }
 // ProfileForPath describes the device backing a filesystem path.  A
 // path that cannot be resolved yields the zero profile, which reads as
 // "not rotational, queueing" — the permissive answer, since assuming a
 // spinning disk on an SSD would halve a scan for nothing.
 func ProfileForPath(path string) DiskProfile {
 	dev, err := diskForPath(path)
 	if err != nil {
-		return DiskProfile{}
+		return false
 	}
-	return DiskProfile{
+	rotational, err := os.ReadFile(
-		Device:     dev,
+		filepath.Join(
-		Rotational: sysfsInt(dev, "queue", "rotational") == 1,
+			"/sys/block", dev, "queue", "rotational",
-		QueueDepth: sysfsInt(dev, "device", "queue_depth"),
+		),
 	}
 }
 // sysfsInt reads one small integer out of /sys/block/<dev>/<parts...>,
 // returning 0 when it is absent or unparseable.  Every attribute here
 // is optional: sysfs layout varies by driver, and a missing file is
 // "this device does not say", never an error worth propagating.
 func sysfsInt(dev string, parts ...string) int {
 	p := filepath.Join(
 		append([]string{"/sys/block", dev}, parts...)...,
 	)
 	data, err := os.ReadFile(p) //nolint:gosec // sysfs, name from the kernel
 	if err != nil {
-		return 0
+		return false
 	}
-	n, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	return strings.TrimSpace(string(rotational)) == "1"
 	if err != nil {
 		return 0
 	}
 	return n
 }
-// diskForPath resolves a filesystem path to the *whole disk* backing
+// deviceForPath resolves a filesystem path to its underlying block
-// it — "sdb" for a file on "sdb3".
+// device name (e.g. "sda") by matching the device major:minor
-//
+// from stat(2) against /sys/block/ entries.
-// It goes through /sys/dev/block/<major>:<minor>, which the kernel
+func deviceForPath(path string) (string, error) {
 // maintains as a symlink to the device's own sysfs directory, and then
 // walks up to the parent when that directory turns out to be a
 // partition.  The previous implementation scanned /sys/block comparing
 // dev numbers and, failing an exact match, took the first entry whose
 // *major* agreed — and every SATA disk shares major 8.  So a library on
 // /dev/sdb3 resolved to whatever /sys/block listed first, which is
 // alphabetical, which is sda.  On the machine this was found on that
 // meant a 6 TB spinning disk was read as the SSD next to it and scanned
 // with one worker per core.  Matching on major alone cannot be right
 // whenever a machine has two disks, which is the case this exists for.
 func diskForPath(path string) (string, error) {
 	var st syscall.Stat_t
 	if err := syscall.Stat(path, &st); err != nil {
 		return "", fmt.Errorf(
@@ -124,50 +49,48 @@ func diskForPath(path string) (string, error) {
 		)
 	}
-	// Linux packs dev_t as 12 bits of major and 20 of minor, split
+	// Extract major and minor device numbers.
-	// across the word.  Masking the low byte of each — which is what
+	major := (st.Dev >> 8) & 0xff
-	// this used to do — is right only for the first 256 of either.
+	minor := st.Dev & 0xff
 	major := unixMajor(uint64(st.Dev))
 	minor := unixMinor(uint64(st.Dev))
-	link := filepath.Join(
+	// Scan /sys/block/ for a matching device.
-		"/sys/dev/block",
+	entries, err := os.ReadDir("/sys/block")
 		strconv.FormatUint(major, 10)+":"+
 			strconv.FormatUint(minor, 10),
 	)
 	target, err := filepath.EvalSymlinks(link)
 	if err != nil {
 		return "", fmt.Errorf(
-			"%w: %s (%w)", errNoBlockDevice, link, err,
+			"could not read /sys/block: %w", err,
 		)
 	}
-	// A partition's directory sits inside its disk's, and only the
+	majorStr := strconv.FormatUint(major, 10)
-	// disk carries `queue`. Climb at most one level: sysfs nests a
+	devStr := majorStr + ":" +
-	// partition exactly one deep under its disk.
+		strconv.FormatUint(minor, 10)
 	name := filepath.Base(target)
-	if _, err := os.Stat(filepath.Join(target, "queue")); err != nil {
+	for _, entry := range entries {
-		name = filepath.Base(filepath.Dir(target))
+		devFile := filepath.Join(
-	}
+			"/sys/block", entry.Name(), "dev",
 	if name == "" || name == "." || name == string(filepath.Separator) {
 		return "", fmt.Errorf(
 			"%w for %d:%d", errNoBlockDevice, major, minor,
 		)
 		data, err := os.ReadFile(devFile)
 		if err != nil {
 			continue
 		}
 		content := strings.TrimSpace(string(data))
 		if content == devStr {
 			return entry.Name(), nil
 		}
 		// The filesystem might be on a partition (e.g. sda1)
 		// whose parent block device is sda.  Check if the
 		// major number matches.
 		parts := strings.SplitN(content, ":", 2)
 		if len(parts) == 2 && parts[0] == majorStr {
 			return entry.Name(), nil
 		}
 	}
-	return name, nil
+	return "", fmt.Errorf(
-}
+		"%w for %s", errNoBlockDevice, devStr,
-
+	)
 // unixMajor and unixMinor decode a Linux dev_t.  Spelled out rather
 // than taken from golang.org/x/sys/unix so this file stays readable
 // beside the encoding it is undoing.
 func unixMajor(dev uint64) uint64 {
 	return (dev>>8)&0xfff | (dev >> 32 & ^uint64(0xfff))
 }
 func unixMinor(dev uint64) uint64 {
 	return dev&0xff | (dev >> 12 & ^uint64(0xff))
 }
@@ -2,34 +2,9 @@
 package system
 // DiskProfile is what the scanner needs to know about the device a
 // library sits on.  See the Linux implementation for what each field
 // means; off Linux nothing fills them, because neither macOS nor
 // Windows publishes an equivalent of sysfs's `rotational` and
 // `queue_depth` without going through platform APIs this package
 // deliberately does not link.
 type DiskProfile struct {
 	Device     string
 	Rotational bool
 	QueueDepth int
 }
 // Queues reports whether the drive can reorder outstanding commands.
 // Always true here: an unknown depth is the permissive answer, and
 // assuming otherwise would halve every scan on every Mac.
 func (p DiskProfile) Queues() bool {
 	return p.QueueDepth != 1
 }
 // IsRotationalDisk reports whether the block device backing the
 // given path is a rotational (spinning) disk.  On non-Linux
 // platforms this always returns false (assumes SSD).
 func IsRotationalDisk(_ string) bool {
 	return false
 }
 // ProfileForPath describes the device backing a filesystem path.  Off
 // Linux that is the zero profile, which reads as "an SSD that queues".
 func ProfileForPath(_ string) DiskProfile {
 	return DiskProfile{}
 }
@@ -1,56 +0,0 @@
 // Package tagtotals derives the totals a tag's "5/12" form declares.
 //
 // It exists because the two writers that know a release's full
 // tracklist -- the autotag apply pass and the download importer --
 // must not import each other or the tag writer, and because getting
 // the denominator wrong is invisible: a total that is too large marks
 // a complete album incomplete forever, and nothing fails.
 package tagtotals
 // Position is one track's place in a release.  A zero Disc means the
 // release did not say, which is disc 1.
 type Position struct {
 	Disc  int
 	Track int
 }
 // For returns the totals to write on a file sitting on disc `disc`:
 // how many tracks that disc has, and how many discs the release has.
 //
 // The track total is **per disc** and not the release's track count,
 // because that is what the tag form means and what
 // GetAlbumCompleteness sums -- summing a release total once per disc
 // would multiply a two-disc album's expectation by two.
 //
 // Tracks are counted by distinct position rather than by row: a
 // tracklist that lists a position twice is a defect in the source, and
 // counting it twice would put an album permanently out of reach of its
 // own total.
 func For(all []Position, disc int) (tracks, discs int) {
 	disc = normaliseDisc(disc)
 	seenTracks := make(map[int]struct{}, len(all))
 	seenDiscs := make(map[int]struct{}, 1)
 	for _, p := range all {
 		d := normaliseDisc(p.Disc)
 		seenDiscs[d] = struct{}{}
 		if d != disc || p.Track <= 0 {
 			continue
 		}
 		seenTracks[p.Track] = struct{}{}
 	}
 	return len(seenTracks), len(seenDiscs)
 }
 // normaliseDisc treats an undeclared disc as disc 1.
 func normaliseDisc(d int) int {
 	if d <= 0 {
 		return 1
 	}
 	return d
 }
@@ -1,92 +0,0 @@
 package tagtotals_test
 import (
 	"testing"
 	"yellowjacket/backend/tagtotals"
 )
 func TestFor(t *testing.T) {
 	t.Parallel()
 	singleDisc := []tagtotals.Position{
 		{Disc: 0, Track: 1}, {Disc: 0, Track: 2}, {Disc: 0, Track: 3},
 	}
 	twoDiscs := []tagtotals.Position{
 		{Disc: 1, Track: 1},
 		{Disc: 1, Track: 2},
 		{Disc: 2, Track: 1},
 		{Disc: 2, Track: 2},
 		{Disc: 2, Track: 3},
 	}
 	tests := []struct {
 		name       string
 		all        []tagtotals.Position
 		disc       int
 		wantTracks int
 		wantDiscs  int
 	}{
 		{
 			name: "a single-disc release totals its own tracks",
 			all:  singleDisc, disc: 0, wantTracks: 3, wantDiscs: 1,
 		},
 		{
 			// An undeclared disc is disc 1, on both sides of the
 			// question -- a file tagged "disc 1" and a tracklist that
 			// declares no disc describe the same disc.
 			name: "an undeclared disc is disc 1",
 			all:  singleDisc, disc: 1, wantTracks: 3, wantDiscs: 1,
 		},
 		{
 			// The whole point: 5 here would be the release's track
 			// count, which summed once per disc claims a ten-track
 			// expectation for a five-track album.
 			name: "a multi-disc release totals the file's own disc",
 			all:  twoDiscs, disc: 2, wantTracks: 3, wantDiscs: 2,
 		},
 		{
 			name: "the other disc gets its own total",
 			all:  twoDiscs, disc: 1, wantTracks: 2, wantDiscs: 2,
 		},
 		{
 			// A disc the tracklist does not mention cannot be totalled,
 			// and 0 is how the caller is told to write nothing.
 			name: "a disc with no tracks totals nothing",
 			all:  twoDiscs, disc: 3, wantTracks: 0, wantDiscs: 2,
 		},
 		{
 			name: "an empty tracklist totals nothing",
 			all:  nil, disc: 1, wantTracks: 0, wantDiscs: 0,
 		},
 		{
 			// A source that lists a position twice would otherwise put
 			// the album permanently one track short of its own total.
 			name: "a repeated position counts once",
 			all: []tagtotals.Position{
 				{Disc: 1, Track: 1}, {Disc: 1, Track: 1}, {Disc: 1, Track: 2},
 			},
 			disc: 1, wantTracks: 2, wantDiscs: 1,
 		},
 		{
 			name: "a track with no position is not counted",
 			all: []tagtotals.Position{
 				{Disc: 1, Track: 0}, {Disc: 1, Track: 1},
 			},
 			disc: 1, wantTracks: 1, wantDiscs: 1,
 		},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 			tracks, discs := tagtotals.For(tc.all, tc.disc)
 			if tracks != tc.wantTracks || discs != tc.wantDiscs {
 				t.Errorf("For(%v, %d) = (%d, %d), want (%d, %d)",
 					tc.all, tc.disc, tracks, discs, tc.wantTracks, tc.wantDiscs)
 			}
 		})
 	}
 }
@@ -183,15 +183,6 @@ func syncDatabase(
 		discNum = toNullInt64(v)
 	}
 	// The completeness evidence.  Without this the row keeps whatever
 	// the last scan read while the file on disk now declares a total,
 	// so the album stays "unknown" until a full rescan -- which is the
 	// state the report describes.
 	totalTracks := old.TotalTracks
 	if v, ok := asInt(params.changes[FieldTotalTracks]); ok {
 		totalTracks = toNullInt64(v)
 	}
 	composer := old.Composer
 	if v, ok := params.changes[FieldComposer].(string); ok {
 		composer = v
@@ -216,7 +207,7 @@ func syncDatabase(
 		AlbumID:            albumID,
 		TrackNumber:        trackNum,
 		DiscNumber:         discNum,
-		TotalTracks:        totalTracks,
+		TotalTracks:        old.TotalTracks,
 		Year:               year,
 		Composer:           composer,
 		Comment:            old.Comment,
@@ -101,11 +101,6 @@ func applyFlacTextChanges(cmt *flacvorbis.MetaDataBlockVorbisComment, changes Ta
 		{FieldYear, flacvorbis.FIELD_DATE, true},
 		{FieldTrackNumber, flacvorbis.FIELD_TRACKNUMBER, true},
 		{FieldDiscNumber, "DISCNUMBER", true},
 		// TRACKTOTAL/DISCTOTAL and no other spelling: dhowden/tag's
 		// Vorbis reader looks at exactly these two keys, so TOTALTRACKS
 		// or a "1/12" inside TRACKNUMBER reads back as no total at all.
 		{FieldTotalTracks, "TRACKTOTAL", true},
 		{FieldTotalDiscs, "DISCTOTAL", true},
 		{FieldComposer, "COMPOSER", false},
 	}
@@ -6,7 +6,6 @@ import (
 	"log/slog"
 	"os"
 	"strconv"
 	"strings"
 	id3v2 "github.com/bogem/id3v2/v2"
@@ -67,10 +66,17 @@ func applyTextChanges(tag *id3v2.Tag, changes TagChanges) {
 		tag.SetYear(strconv.Itoa(v))
 	}
-	applyPositionFrame(tag, "Track number/Position in set", changes,
+	if v, ok := asInt(changes[FieldTrackNumber]); ok {
-		FieldTrackNumber, FieldTotalTracks)
+		trckID := tag.CommonID("Track number/Position in set")
-	applyPositionFrame(tag, "Part of a set", changes,
+		tag.DeleteFrames(trckID)
-		FieldDiscNumber, FieldTotalDiscs)
+		tag.AddTextFrame(trckID, id3v2.EncodingUTF8, strconv.Itoa(v))
 	}
 	if v, ok := asInt(changes[FieldDiscNumber]); ok {
 		tposID := tag.CommonID("Part of a set")
 		tag.DeleteFrames(tposID)
 		tag.AddTextFrame(tposID, id3v2.EncodingUTF8, strconv.Itoa(v))
 	}
 	if v, ok := changes[FieldComposer].(string); ok {
 		tag.DeleteFrames("TCOM")
@@ -84,64 +90,6 @@ func applyTextChanges(tag *id3v2.Tag, changes TagChanges) {
 	}
 }
 // applyPositionFrame writes an ID3v2 position frame (TRCK or TPOS) in
 // the "n/N" form the readers parse.
 //
 // The number and the total are separate diff entries and either may be
 // absent, so the frame's *existing* value is the base: writing a total
 // alone must not discard the number that is already there, and writing
 // a number alone must not discard a total the file already declared.
 // A total with no number at all is not written, since "/12" says
 // nothing a reader can use.
 func applyPositionFrame(
 	tag *id3v2.Tag, description string, changes TagChanges, numKey, totalKey string,
 ) {
 	_, hasNum := changes[numKey]
 	_, hasTotal := changes[totalKey]
 	if !hasNum && !hasTotal {
 		return
 	}
 	frameID := tag.CommonID(description)
 	num, total := parseXofN(
 		strings.TrimRight(tag.GetTextFrame(frameID).Text, "\x00 \t\n\r"),
 	)
 	if v, ok := asInt(changes[numKey]); ok {
 		num = v
 	}
 	if v, ok := asInt(changes[totalKey]); ok {
 		total = v
 	}
 	if num <= 0 {
 		return
 	}
 	value := strconv.Itoa(num)
 	if total > 0 {
 		value += "/" + strconv.Itoa(total)
 	}
 	tag.DeleteFrames(frameID)
 	tag.AddTextFrame(frameID, id3v2.EncodingUTF8, value)
 }
 // parseXofN splits an ID3v2 "n/N" position value.  A bare "n" yields a
 // zero total, and anything unparseable yields zeros — the same reading
 // dhowden/tag gives the frame.
 func parseXofN(s string) (int, int) {
 	numText, totalText, _ := strings.Cut(s, "/")
 	num, _ := strconv.Atoi(strings.TrimSpace(numText))
 	total, _ := strconv.Atoi(strings.TrimSpace(totalText))
 	return num, total
 }
 // applyCoverArtChanges handles the FieldCoverArt entry in the diff map.
 //
 //   - []byte with len > 0: embed the given image as front cover.
@@ -166,8 +166,6 @@ var oggFieldMappings = []struct { //nolint:gochecknoglobals // field mapping tab
 	{FieldYear, "DATE", true},
 	{FieldTrackNumber, "TRACKNUMBER", true},
 	{FieldDiscNumber, "DISCNUMBER", true},
 	{FieldTotalTracks, "TRACKTOTAL", true},
 	{FieldTotalDiscs, "DISCTOTAL", true},
 	{FieldComposer, "COMPOSER", false},
 }
@@ -333,31 +333,3 @@ func TestWriteTrackTags_DBSync(t *testing.T) {
 		t.Error("expected FTS5 result for 'New Title'")
 	}
 }
 // The row is what the album page reads, and it is only refreshed by a
 // scan.  Leaving total_tracks at whatever the last scan saw means an
 // album autotagged just now stays "unknown" -- a plain tick on an album
 // the user holds two tracks of -- until a full rescan happens to run.
 func TestWriteTrackTags_PersistsTheTotal(t *testing.T) {
 	db := database.NewTestDB(t)
 	dir := t.TempDir()
 	trackID := seedTestTrack(t, db, createPipelineTestMP3(t, dir))
 	tw := NewTagWriter(testLogger(), db, &mockPlayer{}, &mockPipelineLocker{})
 	if err := tw.WriteTrackTags(trackID, TagChanges{
 		FieldTrackNumber: 2,
 		FieldTotalTracks: 10,
 	}); err != nil {
 		t.Fatalf("WriteTrackTags: %v", err)
 	}
 	af, err := db.Queries.GetAudioFile(context.Background(), trackID)
 	if err != nil {
 		t.Fatalf("get audio file: %v", err)
 	}
 	if !af.TotalTracks.Valid || af.TotalTracks.Int64 != 10 {
 		t.Errorf("total_tracks: got %v, want 10", af.TotalTracks)
 	}
 }
@@ -26,15 +26,6 @@ const (
 	FieldDiscNumber  = "disc_number"
 	FieldComposer    = "composer"
 	FieldCoverArt    = "cover_art" // []byte for set, nil for clear
 	// FieldTotalTracks is how many tracks are on *this file's disc*, not
 	// in the whole release.  That is what the "5/12" form declares and
 	// what GetAlbumCompleteness sums per disc; a release total written
 	// here would multiply the expectation by the number of discs.
 	FieldTotalTracks = "total_tracks"
 	// FieldTotalDiscs is how many discs the release has.
 	FieldTotalDiscs = "total_discs"
 )
 // AudioFormat represents a supported audio file format.
--- a/Show More
+++ b/Show More