feat(ui): badge an album drag with how many tracks it carries

Dragging an album to the queue put its cover under the cursor and said
nothing about how much that was -- an album is 1 track or 30 and the
thumbnail is the same picture either way, so the one number the drop is
about was the one thing the drag did not show. Every other drag in the
app already says it; this was the exception, because it had a picture
to show instead.

A count of 1 draws no badge: "1" over a single cover is noise, and the
absence reads clearly beside a badge that only appears above one.

The badge sits inside the cover's box rather than overhanging it,
because setDragImage snapshots the element and anything outside it
risks being clipped -- while padding the box instead would move the
cover away from the cursor.

Refs #19

.gitea/workflows/android-apk.yml

@@ -0,0 +1,474 @@
+name: Build & publish the Android APK
+
+# The fifth workflow, and the second that publishes.  It builds a signed
+# arm64-v8a APK on every version tag and puts it in
+# Gitea's *generic* package registry, which — unlike the repository — is
+# readable without credentials.  That is what lets an Obtainium client
+# poll a plain URL with no token and no public mirror of the source.
+#
+# **Why its own file rather than a job in ci.yml.**  `ci.yml` runs on
+# every branch push and is the workflow that gates; this one runs on
+# tags only, takes tens of minutes on a cold cache, and the runner has
+# capacity 1.  Hanging it off the gate would put every push behind an
+# SDK download.
+#
+# **Why it is keyed on the tag.**  The ljos pipeline this is modelled on
+# computes a version in CI and cuts the release itself, then gates the
+# Android job on `needs.release.outputs.version != ''` with an
+# `always()` whose absence silently kills the manual path.  This repo
+# has no release automation — tags are pushed by hand and
+# homebrew-formula.yml already keys on `v*` — so the tag *is* the
+# version and none of that machinery, or its failure modes, is needed.
+#
+# It deliberately does **not** carry `continue-on-error`.  In ljos the
+# Android job shared a pipeline with a server deploy that must never go
+# red over a phone build; here it is standalone and can neither delay
+# nor redden anything, so a release step that fails silently would be
+# strictly worse than one that fails visibly.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to build (default: the latest v* tag)"
+        required: false
+
+concurrency:
+  group: android-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  apk:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    container:
+      image: ubuntu:24.04
+      # /cache/tool holds the Go toolchain ci.yml already downloads.
+      # The other three are this workflow's own and are ~4 GB between
+      # them, which is most of its wall clock on a cold run:
+      #   android-sdk  the SDK, the NDK and the platform (~2 GB)
+      #   gradle       GRADLE_USER_HOME — the wrapper distribution and
+      #                the AGP dependency graph (~700 MB)
+      #   pnpm-store   shared with ci.yml
+      # Every path must be inside the runner's `valid_volumes` allowlist:
+      # a directory outside it makes the job **fail to start**, rather
+      # than silently skipping the mount.
+      volumes:
+        - /home/logan/docker/gitea/data/runner/cache/tool:/cache/tool
+        - /home/logan/docker/gitea/data/runner/cache/android-sdk:/cache/android-sdk
+        - /home/logan/docker/gitea/data/runner/cache/gradle:/cache/gradle
+        - /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 }}
+      OWNER: ${{ github.repository_owner }}
+      SHA: ${{ github.sha }}
+      REF_NAME: ${{ github.ref_name }}
+      DEBIAN_FRONTEND: noninteractive
+      GO_VERSION: '1.25.0'
+      npm_config_store_dir: /cache/pnpm-store
+      # The Go half wants the NDK; the Gradle half wants a platform.
+      ANDROID_HOME: /cache/android-sdk
+      ANDROID_SDK_ROOT: /cache/android-sdk
+      GRADLE_USER_HOME: /cache/gradle
+      # Pinned, not "whatever sdkmanager installs": newer NDKs have
+      # broken the Wails Android build before, and r26d is what plan
+      # 015 phase 0 was verified against.
+      NDK_VERSION: 26.3.11579264
+      # The registry package name.  Obtainium watches
+      # <server>/api/packages/<owner>/generic/yellowjacket-android/latest/yellowjacket.apk
+      PACKAGE_NAME: yellowjacket-android
+
+    steps:
+      # libgtk-4-dev and libwebkitgtk-6.0-dev are here even though
+      # nothing in this job builds a desktop app: `wails3` is the task
+      # runner the whole Android build goes through, and the CLI links
+      # the GTK/WebKit bindings, so `go tool wails3` cannot compile
+      # without them.  libasound2-dev is oto's `pkg-config -- alsa`
+      # probe, for the same reason (the *Android* build uses oboe, not
+      # ALSA — this is the host toolchain only).
+      - name: System packages
+        run: |
+          set -eu
+          apt-get update -qq
+          apt-get install -y -qq --no-install-recommends \
+            ca-certificates curl git jq unzip zip \
+            build-essential pkg-config \
+            libwebkitgtk-6.0-dev libgtk-4-dev libasound2-dev \
+            openjdk-21-jdk-headless
+
+      # By hand rather than actions/checkout: that is a JS action and
+      # needs node inside the container before any step has installed
+      # it.  Same approach as the other four workflows.
+      - 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
+
+      # A tag push carries the version in its own name.  A manual run has
+      # no tag, so it takes the input or falls back to the latest v* tag,
+      # which is what a hand-triggered rebuild wants anyway.
+      - 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]*' 2>/dev/null || echo "v0.0.0") ;;
+            esac
+          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
+          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.
+          IFS=. read -r maj min pat <<EOF
+          $v
+          EOF
+          code=$(( ${maj:-0} * 10000 + ${min:-0} * 100 + ${pat:-0} ))
+          if [ "$code" -le 0 ]; then
+            echo "refusing to build version '$v' (versionCode $code)" >&2
+            exit 1
+          fi
+
+          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
+            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
+
+      # Idempotent by directory check.  sdkmanager is itself idempotent
+      # 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"
+
+          if [ ! -x "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" ]; then
+            echo "command line tools: installing"
+            cd /tmp
+            curl -fsSL -o tools.zip \
+              https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
+            unzip -q tools.zip
+            rm -rf "$ANDROID_HOME/cmdline-tools/latest"
+            mv cmdline-tools "$ANDROID_HOME/cmdline-tools/latest"
+          else
+            echo "command line tools: cached"
+          fi
+
+          export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$PATH"
+          yes | sdkmanager --licenses >/dev/null 2>&1 || true
+
+          install_if_missing() {
+            if [ -d "$ANDROID_HOME/$2" ]; then
+              echo "$1: cached"
+            else
+              echo "$1: installing"
+              yes | sdkmanager --install "$1" >/dev/null
+            fi
+          }
+          # android-35 matches compileSdk/targetSdk in
+          # build/android/app/build.gradle.  No system image and no
+          # emulator: this job builds, it does not run.
+          install_if_missing "platform-tools"       "platform-tools"
+          install_if_missing "platforms;android-35" "platforms/android-35"
+          install_if_missing "build-tools;34.0.0"   "build-tools/34.0.0"
+          install_if_missing "ndk;${NDK_VERSION}"   "ndk/${NDK_VERSION}"
+
+          echo "ANDROID_NDK_HOME=$ANDROID_HOME/ndk/${NDK_VERSION}" >> "$GITHUB_ENV"
+          du -sh "$ANDROID_HOME" || true
+
+      # **Signing is not optional past the first install.**  Android
+      # refuses to update an app whose signing key changed and the only
+      # remedy is an uninstall, which takes the user's library with it.
+      # build.gradle falls back to the *debug* keystore when these are
+      # absent, and that key differs between every machine and every
+      # runner — so publishing an unsigned build is a decision to
+      # reinstall by hand for ever.  Fail instead.
+      # **Signing is not optional past the first install.**  Android
+      # refuses to update an app whose signing key changed and the only
+      # remedy is an uninstall, which takes the user's library with it.
+      # build.gradle falls back to the *debug* keystore when these are
+      # absent, and that key differs between every machine and every
+      # runner — so publishing an unsigned build is a decision to
+      # reinstall by hand for ever.  Fail instead.
+      #
+      # Decode, check and build are one step on purpose.  Splitting them
+      # would mean either handing the password to a later step through
+      # `$GITHUB_ENV` — where the `env:` dump is only masked for values
+      # 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 }}
+          KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
+          KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+          YJ_VERSION: ${{ steps.version.outputs.version }}
+          YJ_VERSION_CODE: ${{ steps.version.outputs.code }}
+        run: |
+          set -eu
+
+          if [ -z "${KEYSTORE_B64:-}" ]; then
+            echo "ANDROID_KEYSTORE_B64 is not set."
+            echo
+            echo "Building without it signs with the debug key, and every future"
+            echo "update then fails with a signature mismatch.  See"
+            echo "docs/android-release.md for the keytool command and the secrets."
+            exit 1
+          fi
+          if [ -z "${KEYSTORE_PASSWORD:-}" ]; then
+            echo "ANDROID_KEYSTORE_PASSWORD is not set — see docs/android-release.md" >&2
+            exit 1
+          fi
+
+          # The path is decided here rather than composed in an `env:`
+          # block: `${{ env.HOME }}` evaluates to an empty string in
+          # Gitea's expression context, which turns "$HOME/x.jks" into
+          # "/x.jks" — reported by Gradle as a missing file, a minute in.
+          keystore="${RUNNER_TEMP:-/tmp}/yellowjacket-release.jks"
+          printf '%s' "$KEYSTORE_B64" | base64 -d > "$keystore"
+          chmod 600 "$keystore"
+
+          # **A secret pasted into a web form very often carries a
+          # trailing newline**, and a password is compared byte for byte.
+          # Trim CR and LF from all three, and say so when it mattered —
+          # "the keystore did not open" with a correct password is an
+          # unpleasant thing to debug blind.
+          pass=$(printf '%s' "$KEYSTORE_PASSWORD" | tr -d '\r\n')
+          if [ "${#pass}" -ne "${#KEYSTORE_PASSWORD}" ]; then
+            echo "note: stripped newline(s) from ANDROID_KEYSTORE_PASSWORD"
+          fi
+          alias_want=$(printf '%s' "${KEY_ALIAS:-yellowjacket}" | tr -d '\r\n')
+          keypass=$(printf '%s' "${KEY_PASSWORD:-$pass}" | tr -d '\r\n')
+
+          # Describe the artifact before trying to open it.  A truncated
+          # or mis-pasted base64 yields a file that is the wrong size or
+          # has no keystore header at all, and that is a different
+          # problem from a wrong password.
+          size=$(stat -c %s "$keystore")
+          magic=$(od -An -N4 -tx1 "$keystore" | tr -s ' ' | sed 's/^ //')
+          echo "keystore: $size bytes, first four bytes: $magic"
+
+          # The fingerprint of the decoded file, so "is the secret the
+          # keystore I have locally?" is answerable without guessing.
+          # A hash of a *public* certificate store gives nothing away,
+          # and the alternative is comparing byte counts by eye.
+          #
+          #     sha256sum ~/path/to/yellowjacket-release.jks
+          #
+          # A password that is right for one keystore and wrong for
+          # another is indistinguishable from a wrong password, and this
+          # is the line that distinguishes them.
+          echo "  sha256: $(sha256sum "$keystore" | cut -d' ' -f1)"
+          case "$magic" in
+            "30 82"*)       echo "  header: PKCS12 (keytool's default since JDK 9)" ;;
+            "fe ed fe ed")  echo "  header: legacy JKS" ;;
+            *)              echo "  WARNING: not a keystore header.  Is the secret the base64 of the .jks?" ;;
+          esac
+
+          # Open it here rather than letting Gradle discover the problem
+          # at :app:validateSigningRelease, a minute of build time in and
+          # reported as a missing file rather than a bad password.
+          if ! keytool -list -keystore "$keystore" -storepass "$pass" >/tmp/ks.txt 2>/tmp/ks.err; then
+            echo "the keystore did not open with ANDROID_KEYSTORE_PASSWORD." >&2
+            echo "  password length after trimming: ${#pass}" >&2
+            sed 's/^/  keytool: /' /tmp/ks.err | head -5 >&2
+            echo >&2
+
+            # A password pasted *with its shell quotes* is the one
+            # remaining cause that looks identical to a wrong password:
+            # the secret is two characters longer than the password and
+            # nothing in the error says so.  Naming it is safe --
+            # stripping the quotes and carrying on would not be, since a
+            # password may legitimately contain them.
+            unquoted=$(printf '%s' "$pass" | sed "s/^['\"]//;s/['\"]$//")
+            if [ "$unquoted" != "$pass" ] &&
+               keytool -list -keystore "$keystore" -storepass "$unquoted" >/dev/null 2>&1; then
+              echo "  ** it opens with the surrounding quotes removed. **" >&2
+              echo "  Re-paste ANDROID_KEYSTORE_PASSWORD without them." >&2
+              echo >&2
+            fi
+            echo "Check it locally with the same two values:" >&2
+            echo "  printf %s \"\$SECRET_B64\" | base64 -d > /tmp/k.jks" >&2
+            echo "  keytool -list -keystore /tmp/k.jks -storepass '<password>'" >&2
+            exit 1
+          fi
+          echo "keystore opens with the supplied password"
+
+          # And check the alias now, for the same reason.  It defaults to
+          # `yellowjacket`, so a keystore created with any other alias
+          # would otherwise fail deep inside Gradle.
+          if ! keytool -list -keystore "$keystore" -storepass "$pass" -alias "$alias_want" >/dev/null 2>&1; then
+            echo "alias '$alias_want' is not in this keystore.  It holds:" >&2
+            sed -n 's/^\([^,]*\),.*Entry.*$/    \1/p' /tmp/ks.txt >&2
+            echo "Set ANDROID_KEY_ALIAS to one of those." >&2
+            exit 1
+          fi
+          echo "alias '$alias_want': present"
+
+          ANDROID_KEYSTORE_FILE="$keystore"
+          ANDROID_KEYSTORE_PASSWORD="$pass"
+          ANDROID_KEY_ALIAS="$alias_want"
+          ANDROID_KEY_PASSWORD="$keypass"
+          export ANDROID_KEYSTORE_FILE ANDROID_KEYSTORE_PASSWORD
+          export ANDROID_KEY_ALIAS ANDROID_KEY_PASSWORD
+
+          # ANDROID_SDK is passed explicitly: the Makefile defaults it to
+          # ~/Android/Sdk, which is the developer-machine layout and not
+          # this container's.
+          make android ANDROID_SDK="$ANDROID_HOME" ANDROID_NDK="$ANDROID_NDK_HOME"
+
+      - name: Verify the APK
+        id: apk
+        if: steps.version.outputs.skip == 'false'
+        working-directory: /src
+        run: |
+          set -eu
+          apk=bin/yellowjacket.apk
+          [ -s "$apk" ] || { echo "no APK was produced" >&2; ls -la bin || true; exit 1; }
+          bt="$ANDROID_HOME/build-tools/34.0.0"
+
+          ls -la "$apk"
+          "$bt/aapt2" dump badging "$apk" | sed -n '1p;/application-label:/p;/native-code/p'
+
+          # arm64 and *only* arm64.  x86_64 Android cannot run this app
+          # (modernc's raw lstat against Android's seccomp filter, which
+          # is every x86_64 device and not merely the emulator), so an
+          # x86_64 slice would be ~31 MB that runs nowhere -- and its
+          # reappearance would mean someone had put the ABI back in
+          # app/build.gradle without knowing that.
+          "$bt/aapt2" dump badging "$apk" | grep -q "native-code: 'arm64-v8a'$" || {
+            echo "the APK's ABI set is not exactly arm64-v8a" >&2; exit 1; }
+
+          # The identity the pipeline exists to keep stable.
+          "$bt/aapt2" dump badging "$apk" | grep -q "versionCode='${{ steps.version.outputs.code }}'" || {
+            echo "versionCode is not ${{ steps.version.outputs.code }}" >&2; exit 1; }
+
+          echo
+          "$bt/apksigner" verify --print-certs "$apk" |
+            grep -E 'Signer #1 certificate (DN|SHA-256 digest)'
+
+          # A build signed with the debug key installs once and can never
+          # be updated.  It must never reach the registry.
+          if "$bt/apksigner" verify --print-certs "$apk" | grep -q 'CN=Android Debug'; then
+            echo "REFUSING TO PUBLISH: signed with the debug keystore" >&2
+            exit 1
+          fi
+          echo
+          echo "Record that SHA-256.  If it ever changes, updates will fail."
+
+      # Two copies: a versioned one for history and a fixed `latest` URL
+      # for Obtainium to watch.  Gitea refuses to overwrite an existing
+      # 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 }}
+        run: |
+          set -eu
+          base="${SERVER_URL}/api/packages/${OWNER}/generic/${PACKAGE_NAME}"
+          apk=bin/yellowjacket.apk
+
+          put() {
+            code=$(curl -s -o /tmp/put.out -w '%{http_code}' \
+              --user "${OWNER}:${PACKAGE_TOKEN}" \
+              --upload-file "$apk" "$1")
+            echo "  -> $1 : $code"
+            # 409 is "already there", which is the correct outcome for a
+            # re-run of the same tag and not a failure.
+            if [ "$code" != "201" ] && [ "$code" != "409" ]; then
+              cat /tmp/put.out >&2
+              return 1
+            fi
+          }
+
+          echo "publishing the versioned copy"
+          put "$base/$VERSION/yellowjacket-$VERSION.apk"
+
+          echo "clearing the previous latest"
+          curl -s -o /dev/null -w '  -> delete latest: %{http_code}\n' \
+            --user "${OWNER}:${PACKAGE_TOKEN}" \
+            -X DELETE "$base/latest/yellowjacket.apk" || true
+
+          echo "publishing latest"
+          put "$base/latest/yellowjacket.apk"
+
+          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"

.gitea/workflows/arch-package.yml

@@ -1,8 +1,23 @@
 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:
-    branches: [main]
+    tags: ["v*"]
+  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:
@@ -17,6 +32,7 @@ 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:
@@ -26,8 +42,9 @@ 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 \
+            base-devel git go nodejs pnpm curl sudo jq \
             webkitgtk-6.0 gtk4 alsa-lib
 
       - name: Create unprivileged build user
@@ -36,15 +53,43 @@ 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
+
+          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
@@ -54,6 +99,7 @@ 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
@@ -67,3 +113,20 @@ 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

.gitea/workflows/ci.yml

@@ -1,6 +1,6 @@
 name: CI
 
-# The other three workflows package and publish; none of them test
+# The other five workflows package, publish or release; 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,9 +9,23 @@ 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: ['**']
+    branches: [main]
   pull_request:
   workflow_dispatch:
 
@@ -78,7 +92,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
-      # three workflows in this directory.
+      # other workflows in this directory.
       - name: Clone repo at this commit
         run: |
           set -eu

.gitea/workflows/desktop-assets.yml

@@ -0,0 +1,176 @@
+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
+
+          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"

.gitea/workflows/homebrew-formula.yml

@@ -14,6 +14,15 @@ 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:
@@ -30,10 +39,25 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Compute version and tarball checksum
+        id: version
         run: |
           set -euo pipefail
-          TAG="${GITHUB_REF_NAME}"          # e.g. v1.3.0
-          VERSION="${TAG#v}"                 # e.g. 1.3.0
+          TAG="${{ inputs.version }}"
+          [ -n "$TAG" ] || TAG="${GITHUB_REF_NAME}"   # e.g. v0.0.1
+          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
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+
           TARBALL="${SOURCE_TARBALL_BASE}/${TAG}.tar.gz"
 
           echo "Fetching ${TARBALL}"
@@ -53,6 +77,7 @@ 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"
@@ -66,6 +91,7 @@ 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

.gitea/workflows/index-artifact.yml

@@ -7,11 +7,29 @@ name: Search index maintenance
 #   import older than 6mo -> rebuild (re-import from the newest dump)
 #   otherwise             -> refresh (fold in new incremental listens)
 #
-# A refresh is cheap and no-ops when nothing new has been published, so
-# running it on every push to main is safe.
+# **There is deliberately no `push` trigger, and restoring one is a
+# decision rather than a cleanup.** A refresh is individually cheap, so
+# 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
+# database is deliberately in the older encoding, so the stale-shape
+# 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
+# which cannot be rebuilt in ten minutes is triggered deliberately, not
+# by a push.** The weekly cron keeps the catalog current, and
+# workflow_dispatch resumes or forces a build — indexbuild picks up from
+# its checkpoint either way, so nothing is lost by not running on every
+# merge. See docs/index-cache.md for the snapshot and the restore.
 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.
@@ -33,6 +51,10 @@ on:
 
 # Runs share one persistent working directory, so they must not overlap.
 # A push landing mid-build waits rather than corrupting the checkpoint.
+#
+# That directory holds the only copy of a catalog nothing can cheaply
+# re-derive: see docs/index-cache.md for the snapshot it takes and the
+# restore, which is minutes against the hours a rebuild costs.
 concurrency:
   group: search-index
   cancel-in-progress: false
@@ -42,7 +64,10 @@ jobs:
     runs-on: ubuntu-latest
     container:
       # CGO is not needed: the project uses the pure-Go modernc sqlite
-      # driver, and neither command imports the Wails app.
+      # driver, and neither command imports the Wails app — which is a
+      # claim with a test behind it now (cmd/indexbuild/deps_test.go),
+      # because the v3 migration quietly broke it and this job was where
+      # that surfaced.
       image: golang:1.25
       # This host path must exist on the runner and be listed verbatim in
       # act_runner's container.valid_volumes. It holds explore-staging/

.gitea/workflows/release.yml

@@ -0,0 +1,182 @@
+name: Release
+
+# The sixth workflow, and the one that decides whether the other three
+# run at all.  On every push to main 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.
+#
+# **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:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# 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.
+      - name: Run semantic-release
+        if: steps.guard.outputs.skip == 'false'
+        working-directory: /src
+        run: |
+          set -eu
+          git config user.name  "yellowjacket-ci"
+          git config user.email "yj@yellowjacket.app"
+
+          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 \
+              --repository-url "https://x-access-token:${PACKAGE_TOKEN}@${SERVER_URL#https://}/${REPO}.git"

.gitignore

@@ -63,10 +63,28 @@ bin/
 # packaging tasks that depend on it. A derived file with one source.
 build/linux/yellowjacket.desktop
 
-# `wails3 task common:update:build-assets` regenerates the mobile trees
-# whether or not anything asks for them. This is a desktop player and
-# cannot target iOS/Android, so their includes: entries are dropped from
-# Taskfile.yml and the trees themselves are not carried — ignored rather
-# than deleted-and-rediscovered on every asset refresh.
+# iOS is not carried. `wails3 update build-assets` regenerates the tree
+# whether or not anything asks for it, so it is ignored rather than
+# deleted-and-rediscovered on every asset refresh, and its includes:
+# entry is dropped from Taskfile.yml.
+#
+# build/android/ *is* carried — see plan 015. Note that `update
+# build-assets` does NOT regenerate it (only `generate build-assets`
+# does, and that rewrites the whole of build/), so the tree is committed
+# and edited by hand like any other source. Only its output is ignored,
+# below.
 build/ios/
-build/android/
+
+# Android build output. jniLibs holds the ~30 MB per-ABI c-shared
+# libraries the Go build produces; gen/ and overlay.json are written by
+# `wails3 android overlay:gen`; the rest is Gradle's.
+build/android/app/src/main/jniLibs/
+build/android/app/build/
+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

.golangci.yml

@@ -29,6 +29,17 @@ linters:
     - usetesting
     - whitespace
     - wsl_v5
+  exclusions:
+    paths:
+      # Wails scaffold, not ours.  `build/android/` is generated by
+      # `wails3 generate build-assets` and carried verbatim (plan 015),
+      # and it contains one Go file -- scripts/deps/install_deps.go, the
+      # interactive SDK installer behind `task android:install:deps`.
+      # It trips 24 of the strict linters above, and reformatting
+      # upstream's file to our house style would be undone by the next
+      # refresh and would make the diff against upstream unreadable.
+      # `make android-setup` is what this repo uses instead.
+      - build/android/
 formatters:
   enable:
     - gci

.pi/skills/yellowjacket-dev/SKILL.md

@@ -96,6 +96,15 @@ reference, because you need them *before* the failure, not after.
   Run against the `bulk` seed a measurement session left behind and a
   third of them fail (13 of 36, when it was measured), in a list that
   reads exactly like a regression in whatever you are holding. `make dev-headless SEED=default` first.
+- **The catalog is stubbed out locally now, like CI.**
+  `dev-headless.sh` defaults `YJ_CORE_INDEX_URL` to a dead address
+  because it was the only launcher that did not — `seed-sandbox.sh` and
+  `ci.yml` always have. Without it the app downloads the real ~1M-row
+  Explore catalog into the run's `YJ_HOME`, and specs that stage their
+  own catalog rows then search a million real ones and fail *locally
+  only*, which reads as a regression and is an environment. Pass
+  `YJ_CORE_INDEX_URL=<real url>` when you want the real catalog to
+  explore by hand.
 - **…and the suite spends state it cannot always give back.**
   `view-lifecycle.spec.ts` **skips an autotag album** on every run, out
   of the eleven the seed has, and does not put it back — so around the
@@ -151,6 +160,7 @@ only climb when it cannot.
 | Something you cannot predict — exploring | `make dev-headless SEED=default` + `playwright-cli` | interactive |
 | Something whose answer is a *number*, not a pass | `make perf` against a bulk-seeded app | ~1 min + setup |
 | A `.sql` or `.templ` file | `make generate`, then the checklist in [references/schema-change.md](references/schema-change.md) | |
+| Anything that has to survive on a phone | `make android-smoke` against a booted emulator | ~1 min + setup |
 
 Two targets are once-per-clone prerequisites that are **not**
 dependencies of the targets needing them, so on a fresh checkout each
@@ -426,3 +436,9 @@ fails the build otherwise, including in files no lint pass compiles.
   and what breaks in it.
 - [schema-change.md](references/schema-change.md) — the two-file
   schema/migration checklist.
+- [android-tier.md](references/android-tier.md) — the emulator tier,
+  and the three reasons a failure there looks like a success. **Read
+  its first section before running anything on Android**: Go's stdout
+  does not reach logcat, `os.Exit` leaves no panic and no tombstone,
+  and ActivityManager restarts a dying app fast enough that `pidof`
+  always answers.

.pi/skills/yellowjacket-dev/references/android-tier.md

@@ -0,0 +1,350 @@
+# The Android tier
+
+A sixth tier, and the only one where **the app failing looks exactly
+like the app working**. Read the first section before you run anything;
+it is the difference between a diagnosis and an afternoon.
+
+This tier answers "does the phone build run", nothing else. It is not a
+spec tier, it does not run in CI, and the app is not a usable Android
+player yet (plan 015 says why, at length).
+
+## Three facts that make failure invisible
+
+**Go's stdout does not reach logcat.** An Android app's fd 1 and 2 go to
+`/dev/null`. Every `slog` line the app writes is discarded — including
+the one naming the error it is about to exit on. `setprop
+log.redirect-stdio true` does not help: it redirects the *Java*
+runtime's `System.out`, and the Go code is a c-shared native library.
+
+**`os.Exit` is a silent death.** `main()` ends several failure paths in
+`os.Exit(1)`. From Android's side that is a process that vanished:
+`ActivityManager: Process com.wails.app has died`, `Zygote: exited due
+to signal 9`, and **no** panic, **no** `AndroidRuntime` stack, **no**
+tombstone under `/data/tombstones` and nothing in `logcat -b crash` or
+dropbox. All three of the places you would look are empty, and the one
+signal that is present — SIGKILL — reads as "the system killed it",
+which is the wrong hypothesis.
+
+**ActivityManager restarts it, so a dead app looks alive.** A
+crash-looping app is respawned several times a second, so `pidof` always
+answers and `am start` always reports `Status: ok`. "Did it start" is
+the wrong question. `make android-smoke` asks the right one — is it the
+*same pid* a few seconds later.
+
+The tell, once you know it: `I/WailsBridge: Wails bridge initialized`
+followed immediately by a new pid doing the same thing. That means the
+native library loaded, the JNI bridge came up, Go's `main()` ran, and
+`main()` left. Work backwards through its `os.Exit(1)` paths.
+
+## What to run
+
+One-time, ~3.5 GB:
+
+```bash
+make android-setup          # SDK pieces + the yj-test AVD, idempotent
+```
+
+Then:
+
+```bash
+make android                # arm64-v8a APK -> bin/yellowjacket.apk (~16 MB)
+make android-emulator       # boot headless in the background, wait for boot
+make android-install        # adb install -r
+make android-smoke          # launch, then assert the same pid survives 10s
+make android-logs           # filtered logcat, follow
+make android-emulator-stop  # console kill, then the saved PID
+```
+
+`make android-smoke SECONDS=30` for a longer window. On failure it
+prints the last 40 app-relevant logcat lines and how to read them.
+
+Never `pkill -f emulator` — the pattern matches the invoking shell's own
+command line and kills it, silently dropping the rest of your compound
+command. The emulator is addressed by its saved pid in
+`.dev/emulator.pid`, same discipline as `make dev-stop`.
+
+**adb is addressed by AVD name, not by whatever is plugged in.** The
+script resolves `ANDROID_SERIAL` from `ro.boot.qemu.avd_name` before
+any device command, because a second emulator (another project's, or
+this one's own corpse left `offline` by a previous run) makes a bare
+`adb` fail with "more than one device" — which `cmd_install` reported
+as *"no device — run 'make android-emulator' first"* immediately after
+that had succeeded. Serials are assigned in boot order and change
+between runs, so the AVD name is the identity. Set `ANDROID_SERIAL`
+yourself and it is honoured; one device that is not ours (a phone) is
+taken as the target.
+
+## Things that cost a cycle
+
+- **`ANDROID_HOME` must carry a platform, and Arch's does not.**
+  `/opt/android-sdk` (the `android-sdk` package) has an NDK and
+  build-tools but `platforms/` is *empty*, so Gradle fails with a
+  compileSdk error that reads like a version mismatch. The Makefile
+  defaults `ANDROID_SDK` to `~/Android/Sdk` (user-owned, writable,
+  where sdkmanager puts things) and `ANDROID_NDK` to `/opt/android-ndk`
+  separately, because the Go half wants the NDK and the Gradle half
+  wants the platform and they are in different places.
+- **The NDK is pinned to r26d** (`26.3.11579264`, Arch's
+  `android-ndk-26`). Newer NDKs have broken the Wails Android build
+  before. CI pins the same one.
+- **Without KVM the emulator still works and is unusably slow** — a 30 s
+  boot becomes tens of minutes, which reads as a hung target rather than
+  a slow one. `make android-setup` checks and warns.
+- **`-no-snapshot` is deliberate.** A snapshot-resumed emulator carries
+  the previous run's app state, and a smoke result that depends on what
+  the last run left behind is not a result.
+- **The logcat filter is not optional.** The emulator emits thousands of
+  lines a second, nearly all WindowManager transitions; an unfiltered
+  `adb logcat` buries the six lines that matter. `make android-logs`
+  filters to `WailsBridge`, the app's own tag, `GoLog`, `AndroidRuntime`,
+  `DEBUG` and `libc:F`.
+- **`run-as` does not work on a release-signed APK** (`package not
+  debuggable`), so you cannot read the app's data directory or its
+  environment that way. Ask the device instead, or build a debug variant.
+- **The `google_apis` system image, not `default`.** This app is a
+  WebView app; `google_apis` ships the Chrome-based WebView that
+  actually renders it.
+
+## The current state of the build
+
+**The app starts. The x86_64 emulator cannot run it, and that is not a
+bug in the app.**
+
+`modernc.org/libc` — which `modernc.org/sqlite`, and therefore the whole
+database layer, sits on — issues a **raw `lstat` syscall on
+linux/amd64** (`libc_linux_amd64.go`'s `Xlstat64` calls
+`unix.Syscall(unix.SYS_LSTAT, …)`). Android's seccomp policy forbids
+syscall 6 on x86_64, because bionic never issues it, so the process
+takes `SIGSYS` the first time anything touches the database:
+
+```
+F/libc: Fatal signal 31 (SIGSYS), code 1 (SYS_SECCOMP), syscall 6
+F/DEBUG: Cause: seccomp prevented call to disallowed x86_64 system call 6
+```
+
+**arm64 is unaffected, and structurally so.** There is no `lstat`
+syscall on arm64 at all, so `ccgo_linux_arm64.go`'s `Xlstat` is
+`Xfstatat(…, AT_SYMLINK_NOFOLLOW)` → `SYS_newfstatat` (79), which
+Android permits. `grep -c SYS_LSTAT ccgo_linux_arm64.go` is 0. Go's own
+`syscall` package already uses `fstatat` on both architectures, which
+is why this is *only* the modernc path.
+
+So: **verify on arm64, and on this machine that means a real device.**
+`make android-smoke` on an x86_64 AVD reports a `SIGSYS` tombstone that
+says nothing about your change.
+
+**Do not reach for an arm64 system image — it will not run here, and
+finding that out costs a 3.8 GB download.** Emulator 37 refuses
+outright:
+
+```
+FATAL | Avd's CPU Architecture 'arm64' is not supported by the QEMU2
+        emulator on x86_64 host. System image must match the host
+        architecture.
+```
+
+Google dropped cross-architecture emulation; there is no flag. The
+options are an arm64 host, a physical device, or `adb connect` to one.
+
+**The x86_64 ABI is therefore gone from the build** (`abiFilters` in
+`build/android/app/build.gradle`, `android:package` rather than
+`package:fat` in the Makefile, and a `native-code: 'arm64-v8a'$`
+assertion in `android-apk.yml` that fails if it comes back). It could
+not run on any Android until modernc fixes this — x86 Chromebooks
+included — and dropping it took the artifact from 27 MB to 15.9 MB.
+The tombstone was at least honest while it lasted: unlike the
+`os.Exit` that came before it, it left a real crash record with a
+backtrace.
+
+### The emulator still installs it, and it still does not run
+
+The obvious guess about dropping x86_64 — that `make android-install`
+would now refuse with `INSTALL_FAILED_NO_MATCHING_ABIS` — is **wrong,
+and was measured wrong before it was written down.** Google's
+`google_apis` x86_64 images carry arm64 translation:
+
+```
+ro.product.cpu.abilist = x86_64,arm64-v8a
+```
+
+So the arm64-only APK installs, the loader maps `lib/arm64/libwails.so`
+and runs it (the tombstone says `Guest architecture: 'arm64'`). It then
+dies **before any of our code**, with SIGILL rather than SIGSYS:
+
+```
+signal 4 (SIGILL), code -6 (SI_TKILL)
+#00 pc 00000000015911d0  .../lib/arm64/libwails.so
+```
+
+Disassembling that offset names the reason exactly:
+
+```
+15911d0: d5380600   mrs  x0, ID_AA64ISAR0_EL1
+```
+
+That is Go's `internal/cpu` reading the arm64 CPU-feature ID register
+at runtime init, which the translator does not implement. So it is not
+"our Go program is unlucky": **no Go binary starts under this
+translation layer**, and no amount of work on this app changes it.
+
+The three failures are worth holding side by side, because each looks
+like the app's fault and none is:
+
+| build | on x86_64 Android | signal |
+|---|---|---|
+| x86_64 | modernc's raw `lstat` vs seccomp | SIGSYS, syscall 6 |
+| arm64, translated | Go reads `ID_AA64ISAR0_EL1` | SIGILL |
+| arm64, real device | — | unverified, still |
+
+**A physical arm64 device remains the only verification path.**
+
+### What was fixed to get here
+
+`backend/system`'s `buildUserDirPath` switched on `runtime.GOOS` with a
+`default:` returning `errUnsupportedOS`, so Android failed at startup
+and `main()` called `os.Exit(1)` six milliseconds after the bridge came
+up. `main()` now calls `system.UseHomeOverride(application.Mobile.
+StoragePath())` before anything asks for a path — a documented,
+build-tag-free API that returns `""` on desktop, where the setter is a
+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.
+
+### What is still not done
+
+The shell is still a desktop shell, and the x86_64 half of the APK is
+still dead weight. Everything in plan 016's section A is now built:
+storage access, an in-app folder picker (Android's directory dialog
+returns an error, since the Storage Access Framework yields tree URIs
+rather than paths), MPRIS excluded, and a MediaSession with a transport
+notification and audio focus.
+
+### Compiling the `android`-tagged Go by hand
+
+`make lint` and `make test` never see it: their three tag sets are all
+linux/amd64, so the only thing that compiles `backend/mediacontrols/
+android.go` is `make android` — a full APK build for a Go type error.
+The short way round:
+
+```bash
+B=$(echo /opt/android-ndk/toolchains/llvm/prebuilt/*/bin)
+CC=$B/aarch64-linux-android21-clang CXX=$B/aarch64-linux-android21-clang++ \
+  GOOS=android GOARCH=arm64 CGO_ENABLED=1 go build ./backend/...
+```
+
+**`CXX` is not optional.** Without it the oboe C++ sources in `oto`
+compile against the host sysroot and fail on `android/log.h` and
+`sys/system_properties.h`, which reads like a broken or missing NDK.
+Restrict it to `./backend/...`: `./...` additionally builds
+`build/android/gen`, a scaffold shim that only resolves inside the
+wails task and fails with `undefined: main` on its own.
+
+A Go method added to a bound service also reaches the frontend unless
+it says not to — `//wails:ignore` above the func, which `make bindings`
+then honours. `Player.SetDuck` is driven by OS audio focus and carries
+one.
+
+## The scaffold's own tasks
+
+`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:
+
+```
+wails3 task android:run              # debug build + emulator install + launch
+wails3 task android:run:device       # same, first connected physical device
+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
+wails3 task android:logs:all
+wails3 task android:clean
+```
+
+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`
+does not match it) and misses `ActivityManager`'s "has died" line, which
+is the one that tells you it crashed; `make android-logs` filters by tag
+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 declared twice
+
+`applicationId` in `build/android/app/build.gradle` is what Gradle
+installs. `APP_ID` in `build/android/Taskfile.yml` is what every
+adb-driven task uninstalls, launches and filters. **Nothing enforces
+that they agree**, and `ANDROID.md`'s advice to set `APP_ID` in
+`build/config.yml` does not work in beta.8 — `wails3 task` never reads
+that file (verified with `--dry`), and even when set it feeds only the
+adb commands, never Gradle. Change both or the official `run`/`deploy`
+tasks address a package that is not installed.
+
+Related, and it will bite once: the launcher activity is
+`com.wails.app.MainActivity` and the applicationId is
+`app.yellowjacket`. `am start -n app.yellowjacket/.MainActivity`
+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.
+
+## What only a device can answer
+
+The emulator cannot run this app (three separate reasons, none of them
+ours — see plan 016), so the phone in someone's pocket is a tier, and
+asking for it is cheap. The first run of it, on 2026-08-17, confirmed
+the whole of A4 and found two faults **no other tier can see**:
+
+- **The back gesture.** `MainActivity.onBackPressed` asks
+  `webView.canGoBack()`. Nothing in a desktop shell has a back gesture,
+  so no spec had ever called `page.goBack()` and the app had never
+  pushed a history entry — back quit from any depth. It is a history
+  entry per navigation now, which is also what made it assertable in the
+  browser tier (`e2e/specs/back-navigation.spec.ts`).
+- **The safe area.** `targetSdk 35` forces edge-to-edge, so the
+  transport and the tab bar sat under the gesture bar. **A browser
+  viewport has no system bars**: `phone-shell.spec.ts` at 390x844 will
+  keep passing on a build the device is clipping 48dp off. Insets are
+  handled in `applyWindowInsets()`.
+
+So when asking for a device run, ask about what the platform *adds* —
+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.
+
+## Asking the device, not just looking at it
+
+A real phone can be inspected, and that turns this tier from "reported
+symptoms" into evidence. Three commands:
+
+```bash
+make android-screenshot          # what the screen shows (.dev/ by default)
+make android-inspect             # forward the WebView's devtools socket
+make android-eval EXPR='JSON.stringify({vp:[innerWidth,innerHeight]})'
+```
+
+Four things about it, each of which costs an hour if met cold:
+
+- **Only a `debuggable` build has a devtools socket**, and a debug build
+  carries `applicationIdSuffix ".dev"` so it installs **beside** the
+  release app. That matters more than convenience: the two are signed by
+  different certificates, and Android's only remedy for a changed
+  certificate is an uninstall, which takes the user's library with it.
+  Never uninstall to make room for a build.
+- **Playwright cannot drive it.** `connectOverCDP` calls
+  `Browser.setDownloadBehavior`, a WebView answers "Browser context
+  management is not supported", and the connection dies before the first
+  evaluate. `scripts/android-eval.mjs` is raw CDP over Node's built-in
+  WebSocket for that reason.
+- **Wireless adb drops when the screen sleeps.** The symptoms are
+  `device offline` mid-session and a `fetch failed` from the eval
+  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.
+
+**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
+other tier runs a current Chromium or WebKit, so a spec that passes at
+that viewport says nothing about the phone — 113 has no Popover API and
+no relaxed CSS nesting, and a dropped CSS declaration renders as
+"present but wrong", which is the hardest failure to read from a
+picture. Get the version first; it reframes every other symptom.

.planning/plans/active/015-android-release-pipeline.md

@@ -0,0 +1,383 @@
+# 015 — Android release pipeline
+
+Ship an Android APK from CI on every version tag, published to the Gitea
+generic package registry so Obtainium can poll a plain URL.
+
+The baseline is `~/Development/ljos`, whose `.gitea/workflows/ci.yml`
+`android:` job has been through the failure modes already. Most of what
+follows is a transcription of that job onto this repo's conventions;
+where it differs, the difference is argued.
+
+## What this is not
+
+**This ships a pipeline, not a usable Android music player.** The
+success criterion is a signed, installable APK that launches — not an
+app anyone would want. Explicitly out of scope, and each is real:
+
+- `backend/mediacontrols/mpris_linux.go` **will be compiled on Android**.
+  Go's `android` GOOS implies the `linux` build tag, so the `//go:build
+  linux` file is in the build and MPRIS will look for a session bus that
+  does not exist. It compiles; it will error at runtime.
+- `backend/system` resolves XDG paths. Android has no XDG.
+- The explore catalog artifact is ~0.6 GB. Nothing on a phone wants that.
+- The shell is a desktop shell: an eleven-item sidebar, a 800×600
+  measured minimum, a transport bar. None of that is a phone layout.
+- The library scanner walks a filesystem Android does not grant.
+
+Those are the *next* plan, if there is one. Conflating them with this one
+is how a build pipeline takes six weeks.
+
+## Phase 0 — the gate  [DONE 2026-08-16]
+
+**Passed, further than asked.** No source changes were needed; a full
+27 MB fat APK built first try, both ABIs, production-stripped. Numbers,
+the environment and four non-obvious findings are in
+`.planning/NOTES.md` — including a scaffold bug that put a *debug*
+library in the release APK's phone ABI, fixed here.
+
+**It also installs and launches on an emulator, and then exits.** One
+line stops it: `backend/system/buildUserDirPath` switches on
+`runtime.GOOS` and Android takes the `default:` branch returning
+`errUnsupportedOS`, so `main()` hits `os.Exit(1)` six milliseconds
+after the JNI bridge comes up. That is the *first* thing that stops it,
+not the only one — see the "not this" section above, all of which is
+still true and still out of scope.
+
+The emulator tier that found it is now part of the harness:
+`scripts/android-emulator.sh`, the `make android-*` targets, and
+`.pi/skills/yellowjacket-dev/references/android-tier.md`. It exists
+because the failure is invisible in all three places anyone would look
+(no panic, no tombstone, no crash buffer) and ActivityManager restarts
+the app fast enough that `pidof` always answers — so the tier's
+assertion is "same pid after N seconds", not "it started".
+
+Original phase 0 text follows, kept because its reasoning is what the
+later phases rest on.
+
+
+Everything downstream is wasted if the c-shared link fails. Establish it
+by hand, locally, before writing a line of YAML.
+
+Already established, by probe rather than by assumption:
+
+```
+GOOS=android GOARCH=arm64 CGO_ENABLED=0 go build ./backend/... ./internal/...
+```
+
+compiles the entire tree. Exactly two packages fail, and both fail only
+because their Android implementation is cgo:
+
+- `ebitengine/oto/v3` — `driver_android.go` needs the bundled **oboe**
+  C++ backend. Oto supports Android natively; there is no Java audio
+  glue to write.
+- `wails/v3/pkg/application` — `mobile_features_android.go` needs the
+  JNI bridge.
+
+`modernc.org/sqlite` (the whole database layer), `beep`, `godbus` and
+every `backend/` package are clean. **No source changes are known to be
+required**, which is the single most surprising finding here and the
+reason this plan is worth doing at all.
+
+What Phase 0 must actually verify:
+
+1. Install NDK **r26d** (`26.3.11579264`) locally. Pinned, not "whatever
+   sdkmanager gives you" — ljos's AGENTS.md records newer NDKs breaking
+   this build.
+2. Generate the scaffolding (Phase 1) and run
+   `wails3 task android:compile:go:shared ARCH=arm64` by hand.
+3. Confirm `build/android/app/src/main/jniLibs/arm64-v8a/libwails.so`
+   exists and is an ARM64 shared object.
+4. Repeat for `amd64` (the emulator ABI).
+
+**If the link fails, stop and re-plan.** The likely culprits, in order:
+alsa (oto must select oboe, not ALSA — if it reaches for `alsa.pc` the
+build tags are wrong), and `main.go`'s `//go:embed all:frontend/dist`
+combined with the generated `main_android.gen.go` overlay.
+
+Deliverable: a note in `.planning/NOTES.md` recording the exact command
+and the NDK version that produced a `.so`, or the reason it cannot.
+
+## Phase 1 — un-ignore and commit the Android scaffolding  [DONE]
+
+Done as a side-effect of phase 0, which could not run without it. One
+correction to the text below: **step 1 is wrong.** `update
+build-assets` does not generate the android tree (NOTES.md explains);
+it was generated with `generate build-assets` into a scratch dir and
+`android/` copied across. CLAUDE.md is corrected to match. Steps 2-5
+were done as written.
+
+
+`build/android/` is gitignored (`.gitignore:72`) and its `includes:`
+entry was dropped from `Taskfile.yml` during plan 009. That was correct
+when nothing could target Android and is what has to be undone.
+
+1. `wails3 task common:update:build-assets` — beta.8 embeds
+   `internal/commands/build_assets/android/`, so this generates the tree.
+2. Remove `build/android/` from `.gitignore`; add `build/ios/`'s reason
+   to a comment so the asymmetry is explained rather than looking like an
+   oversight.
+3. Add `android: ./build/android/Taskfile.yml` to `Taskfile.yml`'s
+   `includes:`.
+4. **Gitignore the tree's own output**, or the repo grows a few hundred
+   Gradle intermediates. ljos has exactly this problem — its
+   `app/build/android/app/build/**` is committed. Ignore:
+   - `build/android/app/build/`
+   - `build/android/app/src/main/jniLibs/`
+   - `build/android/overlay.json` and `build/android/gen/`
+5. `make build-prod` and `make test` still pass — the new include must
+   not perturb the desktop path.
+
+**The refresh hazard has to be written down.** CLAUDE.md's Packaging
+section already says `build/`'s platform metadata is regenerated from
+`build/config.yml` and hand edits are lost. Phase 2 edits `build.gradle`
+by hand. Extend that paragraph to name `build/android/app/build.gradle`
+specifically, because the loss is silent and the symptom (a debug-signed
+APK) appears months later as a failed update.
+
+## Phase 2 — make the APK identifiable and updatable  [DONE 2026-08-16]
+
+**Narrower than planned, because beta.8's scaffold is ahead of ljos's
+beta.3: the release signing config already exists** and reads the four
+`ANDROID_KEYSTORE_*` variables with a debug-keystore fallback. So this
+phase was identity and versioning only. Verified end to end:
+
+| | |
+|---|---|
+| package | `app.yellowjacket` (was `com.wails.app`) |
+| versionCode / versionName | `10301` / `1.3.1`, from `YJ_VERSION_CODE` / `YJ_VERSION` |
+| label | `YellowJacket` |
+| signing | throwaway keystore -> `Signer #1 DN: CN=YellowJacket Test`, not the debug key |
+| ABIs | arm64-v8a + x86_64, both production-stripped |
+
+Installs and launches under the new identity. Still exits on the known
+`buildUserDirPath` bug, which is phase 0's finding and not this phase's.
+
+Two things this phase learned that the text below did not know:
+
+- **The identity has to be declared twice.** `applicationId` in
+  `app/build.gradle` is what Gradle installs; `APP_ID` in
+  `build/android/Taskfile.yml` is what every adb-driven task targets.
+  `ANDROID.md` says to set `APP_ID` in `build/config.yml` — that does
+  nothing in beta.8, verified with `--dry`. Both are set, each
+  commented pointing at the other.
+- **The launcher activity is not under the applicationId.** It stays
+  `com.wails.app.MainActivity` (the scaffold's Java package), so
+  `am start -n app.yellowjacket/.MainActivity` resolves the dot against
+  the wrong package and fails. `scripts/android-emulator.sh` carries the
+  fully-qualified name and a comment saying why.
+
+The `keytool` PKCS12 note below was confirmed verbatim: given a
+`-keypass` differing from `-storepass` it prints "Different store and
+key passwords not supported for PKCS12 KeyStores. Ignoring
+user-specified -keypass value."
+
+Original phase 2 text follows.
+
+
+Edit `build/android/app/build.gradle`, following ljos's, whose comments
+are worth reading before writing this:
+
+- `applicationId "app.yellowjacket"` — matches `config.yml`'s
+  `productIdentifier`. The `namespace` stays `com.wails.app` (it is the
+  Java package, not the app identity).
+- `versionCode Integer.parseInt(System.getenv("YJ_VERSION_CODE") ?: "1")`
+  — **`Integer.parseInt`, not `(...) as Integer`**. Groovy binds the
+  parentheses to `versionCode` first, so the cast reads as
+  `versionCode("1") as Integer`, which sets a String and then casts the
+  setter's null return; Gradle fails the whole project with "Value is
+  null" at that line.
+- `versionName System.getenv("YJ_VERSION") ?: "0.0.0"`.
+- `abiFilters 'arm64-v8a', 'x86_64'`.
+- A `release` signing config reading `ANDROID_KEYSTORE_FILE` /
+  `_PASSWORD` / `ANDROID_KEY_ALIAS` / `ANDROID_KEY_PASSWORD`, falling
+  back to the debug keystore only when no keystore is supplied.
+
+**Android orders releases by an integer and refuses anything not greater
+than what is installed.** A hardcoded `versionCode 1` means the first
+install is the last: every later build is rejected as a downgrade and the
+only fix is an uninstall. `1.3.1 -> 10301`, monotonic as long as minor
+and patch stay under 100.
+
+**Signing is not optional past the first install.** Android refuses to
+update an app whose signing key changed, and the debug keystore differs
+between every machine and every runner — so an unsigned CI build is a
+decision to reinstall by hand forever. The job must **refuse to build**
+without the keystore rather than quietly produce an APK that can never be
+updated.
+
+There is **one password and two required secrets**. keytool has defaulted
+to PKCS12 since JDK 9 regardless of the `.jks` extension, and PKCS12
+cannot hold a separate key password — given `-keypass` it warns and
+ignores it. So `ANDROID_KEY_PASSWORD` defaults to the store password and
+`ANDROID_KEY_ALIAS` to `yellowjacket`. Asking for a second password that
+cannot exist is how someone sets a wrong value and debugs Gradle at
+midnight.
+
+Add `make android` → `PATH="$(TOOLBIN):$$PATH" go tool wails3 task
+android:package:fat`, beside `build-prod`. `make skill-check` fails on a
+documented target that does not exist, so document it only once it does.
+
+## Phase 3 — the workflow  [DONE 2026-08-16]
+
+`.gitea/workflows/android-apk.yml`, plus `docs/android-release.md` as
+the operating document its error messages point at (phase 4's
+documentation half; the secrets themselves still have to be created by
+hand — see the table there).
+
+Three departures from the text below, all argued in the file:
+
+- **No `continue-on-error`.** The plan inherited it from ljos, where
+  the Android job shares a pipeline with a server deploy that must
+  never go red over a phone build. Here it is standalone and can
+  neither delay nor redden anything, so a release step that fails
+  silently is strictly worse than one that fails visibly.
+- **No cached `wails3` binary.** The plan budgeted for ljos's
+  `tools-bin` copy. Unnecessary: the CLI is a vendored `go tool`, and
+  the runner already bind-mounts `GOCACHE`/`GOMODCACHE` for every job,
+  so it is warm from `ci.yml`'s own `make bindings-check`. The GTK and
+  WebKit *dev* headers are still installed, because `go tool wails3`
+  links them.
+- **A fourth cache volume, `/cache/gradle`.** Not in the plan and worth
+  ~700 MB a run.
+
+Four publish-gates were added and each was checked against a real APK:
+both ABIs present, `versionCode` equal to the one derived from the tag,
+a non-empty artifact, and **not signed with the debug key** — verified
+by pointing the check at a deliberately debug-signed build, which it
+refused.
+
+Rehearsed locally with the exact CI invocation
+(`make android ANDROID_SDK=... ANDROID_NDK=...`, `YJ_VERSION`,
+`YJ_VERSION_CODE`, a throwaway keystore): `app.yellowjacket`,
+versionCode 10301, versionName 1.3.1, label YellowJacket, both ABIs,
+`Signer #1 DN: CN=YellowJacket`. Not yet run on the runner.
+
+Original phase 3 text follows.
+
+
+New file: `.gitea/workflows/android-apk.yml`. **Not a job in `ci.yml`.**
+`ci.yml` runs on every branch push and is the workflow that gates; the
+runner is capacity 1, and a 45-minute Android build in it would put every
+push behind an SDK download.
+
+```yaml
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+```
+
+This is where the baseline genuinely diverges. ljos computes its version
+in CI (`scripts/next-version.sh`) and gates the Android job on
+`needs.release.outputs.version != ''`, with an `always()` whose absence
+would silently kill the manual path. **This repo has no release
+automation** — tags are pushed by hand and `homebrew-formula.yml` already
+keys on `v*`. So there is no `needs:`, no `always()`, and no status
+function to get wrong: the tag *is* the version, and a dispatch falls
+back to `git describe --tags --abbrev=0`.
+
+Container, matching `ci.yml`'s conventions (`ubuntu:24.04`, clone by hand
+with `PACKAGE_TOKEN` rather than `actions/checkout`, which is a JS action
+needing node before any step has installed it):
+
+```yaml
+container:
+  image: ubuntu:24.04
+  volumes:
+    - /home/logan/docker/gitea/data/runner/cache/tool:/cache/tool
+    - /home/logan/docker/gitea/data/runner/cache/android-sdk:/cache/android-sdk
+```
+
+The SDK path must be inside the runner's `valid_volumes` allowlist —
+a directory outside it makes the job **fail to start**, not silently skip
+the mount. `/cache/tool` is already allowed and already holds the Go
+toolchain `ci.yml` downloads.
+
+`continue-on-error: true` and `timeout-minutes: 45`. Advisory, because a
+tag's other three workflows must not go red over a phone build, and a
+backstop because a wedged SDK download must not hold the only runner slot
+for hours.
+
+Steps:
+
+1. **System packages.** `ci.yml`'s set plus `unzip` and `openjdk-17-jdk`.
+   `libasound2-dev` stays — it is for the *host* `wails3` build, not the
+   Android cross-build, which uses oboe.
+2. **Go toolchain** — reuse `ci.yml`'s `/cache/tool/go` block verbatim.
+3. **Android SDK and NDK (cached).** ljos's `install_if_missing`
+   idempotent guard, unchanged: cmdline-tools 11076708, `platform-tools`,
+   `platforms;android-34`, `build-tools;34.0.0`, `ndk;26.3.11579264`.
+   sdkmanager is itself idempotent but still spends minutes verifying,
+   which is why the explicit directory guards are there. ~3 GB and most of
+   the job's wall clock on the first run; a directory listing after.
+4. **wails3.** Cheaper here than in ljos, which pins
+   `go install …/wails3@$version` against `app/go.mod`. This repo vendors
+   the CLI (`go tool wails3`, `scripts/toolbin/wails3`), so the version is
+   already pinned by `go.mod` and there is nothing to drift. It still
+   *links* GTK and WebKit, so cache the built binary in
+   `/cache/android-sdk/tools-bin` keyed on the wails version — and note
+   ljos's finding that **caching the binary alone turned a slow job into
+   a broken one**: `wails3` is dynamically linked, so the runtime
+   packages are needed even on a cache hit. Here they are already in
+   step 1.
+5. **Frontend + codegen.** `pnpm install --frozen-lockfile && pnpm build`
+   (pnpm, not ljos's npm), then `make generate`. `main.go` embeds
+   `frontend/dist`, so nothing Go-side typechecks without it.
+6. **Decode the keystore.** Refuse to build if `ANDROID_KEYSTORE_B64` is
+   unset, with the sentence explaining why (Phase 2). Decide the absolute
+   path *here* and export it via `$GITHUB_ENV` — **`${{ env.HOME }}`
+   evaluates to an empty string in Gitea's expression context**, which
+   turned `$HOME/x.jks` into `/x.jks` and surfaced as a missing file
+   fifty-five seconds into a Gradle run.
+7. **Build.** Compute `YJ_VERSION_CODE` from the tag, verify the keystore
+   opens with `keytool -list` *before* Gradle does (Gradle only notices at
+   `:app:validateSigningRelease`, a minute in, and reports it as a missing
+   file), then `make android`.
+8. **Verify the signature.** `apksigner verify --print-certs`, and print
+   the SHA-256 with the note that a change to it breaks every future
+   update. **Nothing here pipes into `head`**: under `set -o pipefail`,
+   `head -1` exits early, the producer takes SIGPIPE, and the step fails
+   with 141 *after* printing a perfectly good APK. Use `find … -print
+   -quit` and a captured variable.
+9. **Publish** to `api/packages/${OWNER}/generic/yellowjacket-android`,
+   authenticating `--user "${OWNER}:${PACKAGE_TOKEN}"` — the same
+   credential pair `arch-package.yml` already uses, not ljos's
+   `REGISTRY_USER`/`REGISTRY_TOKEN`. Two copies: a versioned one for
+   history and a fixed `latest/yellowjacket.apk` that Obtainium watches.
+   Gitea refuses to overwrite, so delete `latest` first. The generic
+   registry is readable **without credentials**, which is what lets
+   Obtainium poll a plain URL with no token and no public source mirror.
+
+## Phase 4 — secrets and documentation
+
+Secrets to create on the repo (all under Settings → Actions → Secrets):
+
+| Secret | Required | Note |
+|---|---|---|
+| `ANDROID_KEYSTORE_B64` | yes | `base64 -w0 yellowjacket-release.jks` |
+| `ANDROID_KEYSTORE_PASSWORD` | yes | |
+| `ANDROID_KEY_ALIAS` | no | defaults to `yellowjacket` |
+| `ANDROID_KEY_PASSWORD` | no | defaults to the store password |
+| `PACKAGE_TOKEN` | already exists | used by `arch-package.yml` |
+
+Write the keytool command, the Obtainium URL and the signing-key warning
+into a docs page — this is the part of ljos's setup that lives in
+`docs/clients.md` and is referenced from the workflow's error messages,
+so the messages have somewhere to point.
+
+Then extend CLAUDE.md's CI section: it currently says "four workflows,
+three of them package and publish; only `ci.yml` gates". That becomes
+five, with the same sentence still true.
+
+## Order and stopping points
+
+Phase 0 gates everything. Phases 1–2 are one commit's worth of work and
+are verifiable locally without CI. Phase 3 is the only part that needs a
+runner, and its first run will be slow and will probably fail once on
+something in the SDK step — budget for that rather than treating it as a
+setback.
+
+**Stop after Phase 0 if the c-shared link does not work.** Every later
+phase is scaffolding for a build that does not exist, and the honest
+outcome is a NOTES.md entry saying which package cannot cross-compile and
+what it would take.

.planning/plans/active/015-multi-artist-credits.md

@@ -0,0 +1,337 @@
+# 015 — Multi-artist credits, navigable
+
+## The problem
+
+A track credited to more than one artist has exactly one navigable
+artist in this app, and the others are punctuation.
+
+`audio_files` carries `artist_credit` (the credit as tagged, for
+display) and `artist_id` (one artist, for grouping and browsing).
+`primaryArtist()` (`backend/library/artistcredit.go:53`) resolves that
+one artist by *string-parsing* the credit: it strips a " feat. "
+clause, and deliberately does not split on `&`, `x`, `with` or `,`
+because those appear inside real artist names. So "Lana Del Rey ft.
+Sean Lennon" stores Lana Del Rey and discards Sean Lennon entirely,
+and "Alina Baraz & Galimatias" stores one artist whose name is the
+whole credit.
+
+### What the measurement says
+
+Measured 2026-08-16 against a real 26,069-file library (19,840 mp3,
+6,229 flac; 57 unreadable, m4a/ogg not examined), plus an 80+80
+MusicBrainz `inc=artist-credits` sample.
+
+- **13%** of a random sample of the library's recordings have more
+  than one credited artist in MusicBrainz (10 of 79 resolved).
+  Extrapolates to ~3,250 of the 24,989 files carrying a recording
+  MBID.
+- **0.86%** of files (224) carry any structured multi-artist signal in
+  their own tags. mp3 carries **zero** files with multiple
+  `MUSICBRAINZ_ARTISTID` values across 19,840 files; flac has 87.
+- **1,286** files say "feat." in `ARTIST`; **1,159 of them (90%)**
+  have nothing structured behind it. A sample of 80 such files was
+  multi-artist in MB **80 of 80 times**.
+
+CLAUDE.md currently justifies plan 013's removal of `artist_credit` /
+`artist_credit_artist` with "3 credits of 2,823 listed more than one
+artist". That figure measured **our own writer**, not the library:
+`cachedLinkArtist` was called exactly once per credit
+(`e7748f1^:backend/library/library.go:1842`), so a collaboration could
+never have been recorded, and the three were resolution collisions on
+shared credit text. Dropping the join table was still correct — it only
+ever held one row, so it was pure join cost — but the stated evidence
+does not support "multi-artist is rare". Correcting that claim is part
+of this plan.
+
+### Why the tags cannot answer it
+
+Deriving the decomposition locally, with no network, works **79% of the
+time** (169 of 215 files with a multi-value `ARTISTS` tag: mp3 69/105,
+flac 100/110), and the failures are systematic rather than random:
+
+```
+ARTIST  = '2Pac feat. Snoop Dogg, Nate Dogg, Hussein Fatal & Yaki Kadafi'
+ARTISTS = ['2Pac', 'Snoop Doggy Dogg', 'Nate Dogg', 'Fatal', 'Yaki Kadafi']
+```
+
+`ARTISTS` holds **canonical** artist names; `ARTIST` holds
+**as-credited** names. Locating one inside the other fails on
+"Snoop Doggy Dogg" vs "Snoop Dogg", on "Fatal" vs "Hussein Fatal", and
+on Unicode (`Michel'le` vs `Michel’le`, `K-Ci` vs `K‐Ci` — U+2010, not
+a hyphen). That distinction is precisely what a join phrase encodes,
+and it is why this cannot be a tag-parsing feature.
+
+Two format details that will mislead anyone re-running the probe:
+Picard writes `ARTISTS` **slash-joined into one TXXX frame** on mp3 and
+as **true repeated Vorbis keys** on flac, so a probe splitting only on
+NUL undercounts mp3 to zero.
+
+## The shape
+
+MusicBrainz models a credit as ordered parts, and the credit *string*
+is derived from them — `artist_credit.name` is a cached render, nothing
+more. Each participant is `(position, artist, name, join_phrase)`,
+where `artist` is the MBID (canonical, what you navigate to) and `name`
+is the credited spelling (what you display).
+
+**Join phrases are assembly instructions, not disassembly
+instructions.** Rendering is a concatenation, never a search:
+
+```
+for each (position, artist_mbid, credited_name, join_phrase):
+    emit link(credited_name -> artist_mbid)
+    emit text(join_phrase)
+```
+
+The link positions are known **by construction**. This is load-bearing:
+if we instead located each `credited_name` inside the stored
+`artist_credit` text, we would reintroduce the mismatch above — the
+stored string may have come from the tags while the parts come from the
+catalog, and those **disagree for ~1 in 3 multi-artist files** (61 of
+90 sampled credits rendered exactly equal to the tag string).
+Divergences seen: `'Skrillex feat. Swae Lee'` tagged vs
+`'Skrillex & Swae Lee'` in MB; `'STRFKR'` vs `'Starfucker'`;
+`'Zedd feat. Hayley Williams'` vs `'... of Paramore'`. Either MB was
+edited after tagging or Picard versions differ; either way the search
+would miss or match the wrong span.
+
+So `audio_files.artist_credit` stops being the source of truth and
+becomes the **fallback**, used only where there are no parts.
+
+## Where the data comes from
+
+The catalog carries the decomposition; no user ever makes a
+per-recording call. Two sources were ruled out first, both cheaply:
+
+- **The canonical dump — which is what CI already pulls
+  (`dumpimport.go:84-85`) — does not have it.**
+  `canonical_musicbrainz_data.csv` gives `artist_mbids` (ordered list)
+  and `artist_credit_name`, but that last column is the *rendered*
+  string. Splitting it on CI needs the as-credited names, so CI would
+  fail exactly the way a local parse does.
+- **The JSON dumps do not cover the catalog.**
+  `json-dumps/recording.tar.xz` is 31 MB / 368 MB uncompressed and
+  holds **153,691 recordings**, not ~35M. Measured against the test
+  library's 24,885 recording MBIDs: **0.00% overlap, zero rows**. It is
+  some other subset and is not usable.
+
+That leaves the core dump, **`mbdump.tar.bz2`** (7.1 GB compressed at
+the 20260815 export), from
+`https://data.metabrainz.org/pub/musicbrainz/data/fullexport/`. Four
+members are needed:
+
+| member | why | approx rows |
+| --- | --- | --- |
+| `mbdump/artist_credit_name` | `(artist_credit, position, artist, name, join_phrase)` — the payload | ~4M |
+| `mbdump/artist` | `id -> gid`, since the above references artist *row ids* | ~2.6M |
+| `mbdump/recording` | `gid -> artist_credit`, to key credits by recording MBID | ~35M |
+| `mbdump/release_group` | same, for album credits | ~2M |
+
+### Coverage is not a concern
+
+Of 24,885 distinct recording MBIDs in the test library, **24,808
+(99.7%)** already have an `explore_index` recording row, measured
+against a database at 2,052,200 rows — i.e. shipped-artifact coverage,
+not a local build's. The popularity filter does not strand the long
+tail here.
+
+## Status
+
+- **Phase 1 — done.** `backend/explore/dumpcredits.go` +
+  `dumpcreditswrite.go`, wired into `dumpimport.go`'s `run` behind its
+  own `credits_import_done` marker.
+- **Phase 2 — done.** `cmd/indexexport` writes the two tables;
+  `artifactimport.go` reads them behind `artifactHasCredits()`.
+- **Phase 4 — done, and it does not need Phase 3.** `explore.GetCredits`
+  reads the catalog tables keyed on the *recording* MBID, which both
+  sides of the app already carry — a catalog row has one and so does a
+  local file (`library.Track.RecordingMBID`). So one binding serves the
+  Explore pages and the library's own lists, and all ten artist-link
+  call sites render credits today without a local table.
+- **Phase 3 (`file_artists`) — not started, and now an
+  offline-resilience task rather than a prerequisite.** The table is
+  deliberately *not* declared yet: nothing writes or reads it, and a
+  schema file plus a datamap note describing behaviour that does not
+  exist is a claim the code cannot back. Its remaining
+  value is that credits currently vanish when the catalog is absent or
+  still downloading, which is precisely the `no-index` state
+  `ShelfPage.State` exists to describe. Materialising into
+  `file_artists` is what makes a library stand on its own.
+
+**Nothing renders yet in practice**, because no published artifact
+carries credit tables — every credit falls back to its single link
+until an index build with Phase 1 runs and is exported.
+
+**Column layouts are verified against the real 20260815 export**, not
+taken from the schema docs — `artist(id, gid, …)`,
+`artist_credit(id, name, artist_count, …)`,
+`artist_credit_name(credit, position, artist, name, join_phrase)` and
+`recording(id, gid, name, artist_credit, …)` were each read out of the
+dump. `release_group` shares `recording`'s first four columns and is
+the one layout still taken on trust; `ErrDumpShape` turns a wrong guess
+into a loud failure rather than a quietly wrong catalog.
+
+**Still unrun: the ingest against the real 7.1 GB dump.** Everything is
+covered by tests over a synthetic tar, which cannot catch a surprise in
+the other ~35M rows.
+
+### Phase 1 — Ingest credits on CI
+
+New dump stage in `cmd/indexbuild`, behind the `indexbuild` tag with
+the rest of `dumpimport.go`'s stages.
+
+**Constraint from `b98840e`:** `cmd/indexbuild` is built
+`CGO_ENABLED=0` in a plain `golang` container and must not reach the
+Wails `application` package — `TestIndexToolsDoNotImportWails` walks
+`go list -deps -tags indexbuild`. Nothing here should need it, but a
+new `ServiceStartup` hook on a package this imports is how it comes
+back. Go's `compress/bzip2` is pure Go and decompress-only, which is
+all this needs.
+
+**Measured, 20260815 export.** Tar members are **alphabetical**, and
+that is favourable: `artist` (435 MB), `artist_credit` (414 MB) and
+`artist_credit_name` (237 MB) all fall inside the first ~900 MB
+compressed, while `recording` and `release_group` come later. So the
+maps are complete before the rows that consume them arrive, and no
+recording data is ever buffered.
+
+Pure-Go `compress/bzip2` decompresses at **26 MB/s uncompressed /
+8.7 MB/s compressed** (measured on a 250 MB prefix, 3.01x ratio) —
+**~13.7 min** for the whole file single-threaded, and less because the
+stream can stop after `release_group` rather than reading the
+`series`/`tag`/`track`/`url`/`work` tail. The 2 MB/s origin throttle
+dominates, as it already does for every other dump here.
+
+Do not, however, *depend* on the ordering: assert it and fall back to
+buffering if a future export reorders, rather than silently emitting
+nothing.
+
+- `artist` -> `map[int32]uuid16` (~2.6M x ~20 B = ~60 MB)
+- `artist_credit_name` -> `map[int32][]creditPart` (~4M x ~40 B =
+  ~200 MB)
+- `recording` / `release_group` -> emit `gid -> credit_id` **only for
+  MBIDs already in `explore_index`** (the kept set is ~1.4M x 16 B =
+  ~22 MB), which is what keeps 35M rows from being held
+
+Peak ~300 MB, one sequential pass.
+
+**Only multi-artist credits are stored.** A single-artist credit is
+`(name, "")` and is already fully described by `explore_index`'s
+`artist_name` / `artist_mbid`; storing it would triple the table for
+nothing. Post-filter after loading, once the row count per credit is
+known.
+
+New tables (and `datamap` entries, or `TestCatalogCoversSchema` fails
+the build — both are `Cache`, matching `explore_index`):
+
+```
+artist_credit_part(credit_id, position, artist_mbid, credited_name, join_phrase)
+```
+
+with `explore_index.artist_credit_id` as the link. Credits are
+**shared** — an album's twelve tracks by one artist share one credit
+row — which is the opposite of 013's local verdict, and correctly so:
+1:1 in a local library, genuinely many-to-one at 2M-row catalog scale.
+
+### Phase 2 — Ship them in the artifact
+
+`cmd/indexexport` currently creates exactly two tables in the artifact
+(`explore_index`, `artifact_meta`, at `cmd/indexexport/*.go:147,170`),
+so this is a structural addition, not a column.
+
+Estimated size: ~13% of 1.4M recordings, deduplicated by shared credit,
+at ~2.3 parts each — order 400k rows, ~18 MB uncompressed. Against a
+~0.6 GB install that is acceptable; it must be measured rather than
+assumed before merge.
+
+`artifactimport.go` must read it **only if present**, on the writer
+handle where `core` is attached — the `artifactHasTotals()` /
+`artifactStoresText()` pattern (`artifactimport.go:145-175`), one step
+up from a column to a table. An artifact published before this exists
+is still a perfectly good catalog and must import as one that declines
+to answer. Adding this to the importer's SELECT list without the probe
+is how every already-published artifact starts failing.
+
+`artifactCatalogColumns` gains `artist_credit_id`; it is kept in sync
+with the exporter by `TestArtifactColumnsMatchExporter`.
+
+### Phase 3 — Materialize locally
+
+```
+file_artists(audio_file_id, position, artist_id, credited_name, join_phrase)
+```
+
+`credited_name` is stored **per row**, not looked up from
+`artists.name` — that is the Snoop-Doggy-Dogg distinction, and it is
+the whole point.
+
+Filled at scan/import time by joining `audio_files.recording_mbid`
+against the catalog. **Materialized rather than resolved live**,
+because the catalog is a downloaded artifact that can be absent or
+still arriving — that is why `ShelfPage.State` has a `no-index` value —
+and a library whose track rows lose their artists when the catalog is
+missing is worse than today.
+
+That implies a backfill for the case where the catalog arrives *after*
+the library was scanned. It registers with `jobs` (progress, cancel)
+like every other long pass, and takes a **distinct kind** from
+`index-build`, since `job-controls.ts` keys its "you will discard hours
+of downloading" confirmation on that kind.
+
+`artists` gains rows for guests who own no files. **This changes what
+the artists grid shows** and is an open question below.
+
+### Phase 4 — Render
+
+`utils/explore-link.ts` gains a credit-rendering entry point taking
+ordered parts and returning a `TemplateResult`. Every row and detail
+view already renders artist names through it, so they inherit
+multi-artist links without individually knowing credits exist — the
+property that made centralising it worthwhile.
+
+Its existing fallback philosophy already covers the no-parts case: "a
+list where some rows are clickable and others silently are not reads as
+a bug, not as a statement about metadata." Where there are no parts
+(no recording MBID, or no catalog row — ~4% of the test library) render
+today's behaviour: the flat `artist_credit` string with one link to the
+primary artist. **Do not split the string there.** There is genuinely
+no information to split on, and that is the one place the temptation
+returns.
+
+`primaryArtist()` stays exactly as it is. It remains the fallback and
+is still what `artist_id` means.
+
+## Open questions
+
+1. **Catalog credit vs tagged credit, when they disagree** (~1 in 3
+   multi-artist files). Rendering the catalog's decomposition is what
+   makes names navigable; preserving the file's is what makes the app
+   reflect the user's files. Leaning toward: render the catalog
+   decomposition, keep `artist_credit` as the fallback string. Wants a
+   deliberate decision, not an accident.
+2. **Do guest artists appear in the artists grid?** Phase 3 creates
+   `artists` rows for people who own no files. The grid currently means
+   "artists in your library" and joins `audio_files`. A guest on one
+   track is arguably in the library and arguably not. Whichever way,
+   the ownership question stays "is there a file" — that rule does not
+   bend.
+3. **`release_group` credits** are ingested in the same pass for
+   nearly nothing, but album-artist rendering is a separate surface.
+   Ship the data in phase 1, render in a follow-up rather than widening
+   phase 4.
+4. **Our own `tagwriter`** does not write `ARTISTS` or multiple
+   `MUSICBRAINZ_ARTISTID` frames, so autotagging a folder degrades the
+   very field this rests on — the same shape as the existing
+   track-totals note. Out of scope here; worth recording.
+
+## Verification
+
+- Coverage: re-run the library probe and assert `file_artists` is
+  populated for ~13% of files, not ~0.9%.
+- `TestCatalogCoversSchema` / `TestLifetimesMatchSchema` for the new
+  tables.
+- `TestIndexToolsDoNotImportWails` still passes with the new stage.
+- An artifact **without** the credits table imports cleanly (the
+  `artifactHasTotals` regression shape).
+- Round-trip: a known multi-artist recording renders each name as a
+  separate link with the correct join phrases between them.

.planning/plans/completed/017-release-automation.md

@@ -0,0 +1,87 @@
+# 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.

.planning/plans/pending/016-android-feature-parity.md

@@ -0,0 +1,410 @@
+# 016 — What Android parity would actually take
+
+> **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
+> taken is **option 1, the full librarian**: `MANAGE_EXTERNAL_STORAGE`
+> plus an in-app folder browser, which keeps the path-keyed model
+> intact. B1/B2 remain, both awaiting a decision rather than work. The
+> sections below are kept as written, because they are the argument the
+> decision rests on — see "What is left" at the end for the current
+> state.
+
+Plan 015 shipped a *pipeline*: the app cross-compiles, is signed and
+versioned, and publishes from CI. This is the assessment of what stands
+between that and an Android app worth installing.
+
+**The headline: parity is the wrong target, and choosing it would be
+the expensive mistake.** Four of the blockers below are not porting work
+— they are the Android platform declining to support the model this app
+is built on. The decision to make first is in "The fork in the road" at
+the end; everything before it is evidence for that decision.
+
+Severity is what the app *does* today, verified against the source and
+the generated manifest, not guessed.
+
+## A. It cannot work at all until these are fixed
+
+### A1. The app can read no music. (deepest)
+
+`build/android/app/src/main/AndroidManifest.xml` requests INTERNET,
+VIBRATE, ACCESS_NETWORK_STATE, USE_BIOMETRIC, POST_NOTIFICATIONS, the
+two location permissions, CAMERA and the two FOREGROUND_SERVICE ones.
+**There is no storage or media permission of any kind.** At
+`targetSdk 35` that means the app can see its own private directory and
+nothing else.
+
+Adding `READ_MEDIA_AUDIO` is necessary and *not sufficient*, because it
+grants access through **MediaStore**, not through the filesystem. This
+app's entire model is absolute paths: `audio_files.file_path` is the
+primary key of ownership, `AddLibrary(path)` takes a directory, the
+scanner walks it with `os.ReadDir`, and every one of
+`GetFilePathsByAlbums` / `ByGenres` / `ByRecordingMBIDs` exists to hand
+paths to the player. Scoped storage does not offer a stable directory
+to walk.
+
+The honest options are three, and they are not close in cost:
+
+- **MediaStore as the library source.** Query the content resolver,
+  keep MediaStore IDs (or content URIs) beside or instead of paths, and
+  open audio through a `ContentResolver` file descriptor. This is the
+  Android-native answer and it touches the schema, the scanner, the
+  player's file opening and every path-keyed query.
+- **`MANAGE_EXTERNAL_STORAGE`.** Keeps the path model intact and is
+  effectively barred from Google Play except for genuine file managers.
+  Viable *only* because we distribute through Obtainium — which is a
+  real point in its favour here, and worth stating plainly rather than
+  dismissing.
+- **App-private storage only**, i.e. the user copies music into the
+  app's sandbox. Trivial to build, and nobody wants it.
+
+### A2. The first-run flow cannot complete.
+
+`first-run-wizard.ts` calls `DirectoryPicker()`, which is
+`frontendutil.DirectoryPicker` → `app.Dialog.OpenFile().
+CanChooseDirectories(true)`. Wails' own `ANDROID.md` lists open-directory
+dialogs as **"❌ Returns an error — SAF yields tree URIs, not filesystem
+paths"**. So the one action the wizard exists to perform fails, and
+`<first-run-wizard>` intercepts all pointer events until a library
+exists — so the app is not merely empty, it is inert.
+
+Whatever A1 resolves to decides this: a MediaStore library needs no
+picker at all, and a SAF tree needs the picker to return a URI the
+backend can use.
+
+### A3. MPRIS is compiled into the Android build.
+
+`mpris_linux.go` is `//go:build linux`, and **`android` implies
+`linux`** (documented, and the reason it is in the APK). It will look
+for a session bus that does not exist. It needs `//go:build linux &&
+!android`, and its Android counterpart is A4.
+
+This one is cheap and should be done regardless — it is a two-character
+build-tag change plus whatever `mediacontrols.New` returns instead.
+
+### A4. Playback will be killed the moment the screen locks.
+
+The scaffold's `WailsForegroundService` is typed **`dataSync`**
+(`foregroundServiceType="dataSync"`, `FOREGROUND_SERVICE_TYPE_DATA_SYNC`),
+and the manifest requests `FOREGROUND_SERVICE_DATA_SYNC`. A music player
+needs `mediaPlayback` and `FOREGROUND_SERVICE_MEDIA_PLAYBACK`, plus a
+`MediaSession` for lock-screen and notification transport controls,
+plus **audio focus** — pause on a phone call, duck for a notification,
+pause on headphone unplug. None of that exists today. `oto` will happily
+keep writing to a stream nobody can hear.
+
+This is the difference between "an app that plays audio" and "a music
+player", and it is Java-side work in the scaffold plus a Go-side bridge.
+
+## B. It works, but wrongly
+
+### B1. The x86_64 half of the APK cannot run on any Android.
+
+Established in plan 015: `modernc.org/libc`'s `Xlstat64` issues a raw
+`lstat` on linux/amd64, which Android's seccomp forbids, so the process
+takes `SIGSYS` the first time it touches the database. arm64 is
+structurally unaffected (no `lstat` syscall exists; it routes through
+`fstatat`).
+
+So ~31 MB of the artifact is dead weight on *every* Android device,
+including x86 Chromebooks. Options: drop `x86_64` from `abiFilters`
+(smaller APK, no emulator target — which does not work anyway), or
+carry it against a future modernc fix. **Dropping it is the honest
+default**; it is also the only item in this plan that is a five-minute
+change.
+
+### B2. The UI is a desktop shell.
+
+`MinWidth`/`MinHeight` are 800×600 and were *measured* — below ~780 the
+header subtitle wraps the title out of its bar. A phone is ~360–430 CSS
+px wide. The sidebar collapses to icons below 900px, which is a
+laptop-sized breakpoint, not a phone one. Beyond width: the app is built
+on hover (the marquee's `hover` mode, tooltips), right-click context
+menus, a keyboard shortcut layer with its own overlay and settings page,
+multi-select with ctrl/shift, and a resizable-column track list. None of
+those are gestures.
+
+This is not a stylesheet pass. It is a second front end for the views
+worth having on a phone, sharing the stores and bindings — which the
+architecture supports, since a view is already a lazily-loaded chunk
+behind `VIEW_LOADERS`.
+
+### B3. Tag writing cannot reach the user's files.
+
+`tagwriter` rewrites tags in place, and autotag's whole purpose is
+applying them to a folder. Under scoped storage that is impossible
+outside the sandbox without a SAF write grant per tree. If A1 lands on
+MediaStore, in-place tag writing needs `MediaStore` write requests and
+user confirmation per file on Android 11+.
+
+Autotagging is arguably a desktop-only feature and saying so is a
+legitimate answer.
+
+### B4. The Explore catalog is a ~0.6 GB download into app-private storage.
+
+It works — but with no awareness of a metered connection and no
+accounting for a device where that is a meaningful fraction of free
+space. At minimum it needs to be opt-in on mobile and to refuse a
+metered network by default. `Android.NetworkJSON()` reports
+`{connected,type}`, so the signal is available.
+
+## C. Inert, and fine
+
+Window geometry, menus and the system tray are documented no-ops on
+mobile. The keyboard shortcut layer is harmless but its Settings page
+is dead weight. `profiling` is already compiled out of production
+builds. These cost nothing and need no work.
+
+## D. Unknown until it runs on a device
+
+**Nothing in section A or B has been observed on Android**, because the
+x86_64 emulator cannot run the app (B1) and emulator 37 refuses arm64
+images on an x86_64 host. Everything above is read from the source, the
+generated manifest and Wails' own documentation. The first real device
+run will find things this list does not have, and the most likely
+places are audio latency and buffering under `oto`/oboe, and SQLite
+behaviour on app-private storage.
+
+## The fork in the road
+
+The four blockers in section A are all the same question wearing
+different clothes: **is the Android app a librarian, or a player?**
+
+YellowJacket on the desktop is a *librarian*. It scans folders,
+deduplicates covers, detects duplicate tracks, reconciles against
+MusicBrainz, rewrites tags on disk, and manages downloads. That model
+rests on owning a filesystem, which is precisely what Android declines
+to give.
+
+Three coherent products, and only the first is "parity":
+
+1. **Full librarian on Android.** Requires `MANAGE_EXTERNAL_STORAGE`
+   (Obtainium-only distribution, which we already have), a phone UI for
+   every view, and media-session playback. Largest scope by far; the
+   result is an app almost nobody has asked for on a phone.
+2. **A player for music already on the phone.** MediaStore as the
+   source, no scanner, no autotag, no downloads; the library, queue,
+   playlists, favourites and Explore-as-browsing all still make sense.
+   This is a genuinely good Android app and it is *not* parity — it is
+   a subset with a different data source.
+3. **A companion to the desktop app.** The phone browses and controls
+   the desktop's library over the network, or syncs a subset. Smallest
+   Android surface, and it leans on the thing that already works.
+
+**Option 2 is the recommendation** if the goal is an app people use;
+option 3 if the goal is the least work for the most value. Option 1 is
+the only one that answers "feature parity" literally, and it is the one
+worth arguing hardest against.
+
+> **Decided:** option 1's *data model* (the librarian keeps its
+> filesystem and its scanner — A1 shipped that) with option 2's
+> *surface*. The phone is a player over the library this app already
+> builds; it does not get every view. The list is below.
+
+## The phone gets a subset (decided)
+
+B2 is not a stylesheet pass and not a second front end either. A view
+is already a lazily-loaded chunk behind `VIEW_LOADERS` /
+`DETAIL_LOADERS` in `index.ts`, and the stores and bindings are shared,
+so the phone build is **a different loader table and a different
+chrome**, over the same stores.
+
+**In**, because each is something a person does with a phone in their
+hand:
+
+- **Home** — the shelves are already a phone-shaped surface.
+- **Library browse** — albums, artists, genres. The grids are already
+  virtualized and card-shaped.
+- **Now playing** — which on a phone is a *view*, not a 4em bar.
+- **The queue.**
+- **Search** — the header box, scoped as it already is.
+- **Playlists**, including smart ones, as lists to play rather than to
+  edit.
+
+**Out**, and each for a reason rather than by omission:
+
+- **Autotag** — the review UI is a wide table and the action rewrites
+  files on disk; B3 has not been verified even as *possible* yet.
+- **Downloads** — two tab panels of client configuration.
+- **Explore** — the catalog is a ~0.6 GB download (B4); browsing it is
+  the last thing to earn a phone's storage.
+- **Settings** — not the page. The phone needs a handful of settings
+  (theme, the library folder, playback) and not the 93 controls the
+  desktop page carries.
+- **Jobs**, **shortcuts overlay**, **column configuration** — a phone
+  has no keyboard and no resizable columns, and the jobs indicator is
+  enough.
+
+What the shell has to lose, from the audit at the top of this section:
+the 800×600 minimum, the 11-item sidebar (a phone wants a bottom tab
+bar over the five things above), hover as a route to anything,
+right-click as the only route to a context menu (long-press is the
+gesture), and ctrl/shift multi-select.
+
+One rule for the work: **no view forks.** A phone layout that copies a
+view's template is two templates to fix every bug in. Where a view
+cannot serve both, the split belongs at the chunk boundary that already
+exists.
+
+Phase 1 followed that rule and found its cost: reusing `<app-sidebar>`
+inside the drawer means reusing its `data-testid`s too, and a second
+copy standing by in the DOM broke 30 specs that had nothing to do with
+the phone. The rule holds — a second list of destinations would be
+worse — but a shared component must be rendered only when it is wanted,
+and the guard belongs in a test that names the reason.
+
+## What is worth doing regardless of that decision
+
+Cheap, independently useful, and each unblocks measurement:
+
+1. **Drop `x86_64` from `abiFilters`** (B1) — or keep it and document
+   why. Five minutes.
+2. **`//go:build linux && !android` on `mpris_linux.go`** (A3), so the
+   Android build stops carrying a D-Bus client. Small.
+3. **A device smoke run**, which needs someone's phone and the published
+   APK. Everything in D depends on it, and it is the single highest
+   information-per-minute action available.
+4. **Make the first-run wizard fail legibly** rather than inertly (A2)
+   — the picker's error already routes through `describeError`, but the
+   wizard still blocks pointer events, so an Android user sees a dead
+   screen rather than a sentence. Even under option 3 this is the right
+   behaviour.
+
+
+## What is left (updated after A4)
+
+**A4 is done.** `backend/mediacontrols/android.go` is a `Handler`
+beside the MPRIS one, and the Java half is
+`WailsForegroundService.java`: a `MediaSession`, a `MediaStyle`
+transport notification and audio focus. It needed no new JNI and no new
+Gradle dependency — `application.Android.StartForegroundService(json)`
+going out, `WailsBridge.emitEvent` → the application event bus coming
+back, and the platform `android.media.session` API rather than
+androidx.media, which minSdk 21 makes available anyway.
+
+Four decisions in it are worth keeping:
+
+- **Ducking is a player concept, not a volume change.**
+  `Player.SetDuck` re-applies the *user's* level with an attenuation
+  offset, so `getUserVolume` still reports what the user chose and
+  nothing is persisted or emitted. A duck that wrote through to the
+  volume would let one notification tone permanently turn the music
+  down.
+- **The duck path is pre-Oreo only.** From API 26 the framework ducks
+  the app itself and sends no `CAN_DUCK` focus change, so asking to be
+  told instead (`setWillPauseWhenDucked`) would mean pausing for every
+  notification tone, and doing both would attenuate twice.
+- **An unchanged payload is not an event here either.** Every push
+  crosses JNI and re-delivers an Intent, and the player pushes state on
+  several paths that can agree.
+- **After the first start, updates use `startService`.** From Android
+  12 an app in the background may not *start* a foreground service, but
+  it may keep delivering intents to one it already has — which is every
+  track change with the screen off.
+
+The contract with Java — the payload keys, the state words, the command
+names — is in `androidpayload.go`, deliberately *without* the `android`
+build tag, so `go test` exercises it on every platform. Everything left
+in `android.go` is untested by construction: it compiles only under a
+cross-compiler and runs only on a phone.
+
+**B1 is done: x86_64 is dropped.** 27.1 MB → 15.9 MB, measured. Three
+places had to agree — `abiFilters`, the Makefile's `android:package`
+(or Go still compiles a library Gradle then discards) and the
+`native-code: 'arm64-v8a'$` assertion in `android-apk.yml`, whose
+anchor is what stops it also matching the fat APK's line. Adding the
+ABI back, if modernc ever fixes `Xlstat64`, is those same three edits.
+
+**B2, the desktop shell.** Scope decided (below); **all four phases are
+done.**
+
+- *Phase 1, the shell.* Below 600px the sidebar column is gone,
+  `<bottom-nav>` is the primary navigation, and the shell fits 320px
+  exactly — measured, from 652px in a 360px viewport before.
+- *Phase 2, the full-screen now-playing view.* Where phase 1's seek bar
+  and volume went. A detail view, so Back pops the nav stack; it
+  composes the real transport components rather than copying them; and
+  it hides the bottom bar while it is up, so it carries its own queue
+  button.
+- *Phase 3, long-press.* `utils/long-press.ts`: one document-capture
+  listener, installed once from `index.ts`, which turns a 500 ms
+  stationary touch into a synthetic `contextmenu` at the touch point.
+  Every menu in the app opens from that event, so all six components
+  gained the gesture without one of them changing — which is the same
+  argument `ContextMenuController` rests on, one layer lower. The
+  details that are not obvious are in `NOTES.md` (2026-08-17); the one
+  worth repeating is that ours is told from the browser's own
+  long-press event by **identity**, not `isTrusted`, because a test
+  cannot dispatch a trusted event and that path would otherwise be the
+  only uncovered one.
+
+- *Phase 4, the track list.* A phone draws `titleArtist` (title over
+  artist) plus the duration, and drops the column headers and the resize
+  handles — a column set rather than a second row template, so the row
+  and everything delegated on it is unchanged. Verified at the device's
+  own 424x439: `24px 304px 80px`, 52 px rows, no truncation, no
+  overflow. The device also found the bug in it, which no browser
+  viewport would have: saved *desktop* column widths reached the phone
+  through an id-keyed store and gave the duration column 55% of the row.
+
+**B2 and B4 are complete.** B4 is `backend/explore/netpolicy.go`: the
+catalog download is skipped on a cellular connection unless
+`AllowMeteredCatalogDownload` is on, with the toggle in Settings' Search
+Index section. The policy and the JSON parsing are in `explore` (tested
+on every platform) and only the platform call is injected from `app.go`,
+because `cmd/indexbuild` imports `explore` and must not link Wails. Two
+things the plan got slightly wrong: the portable API is
+`application.Mobile.NetworkJSON()` rather than `Android`'s, and it
+reports no metered flag — so cellular is the signal and a metered Wi-Fi
+cannot be seen.
+
+What is left in this plan is B3 (tag writing, which needs a device) and
+the standing question of the Light Phone's Chrome 113 — which so far has
+cost nothing: menus, dialogs and long-press all work on it.
+
+**B3/B4** are unchanged, and B3 is now *possible* where it was not:
+with all-files access, `tagwriter` can write in place.
+
+### What the first device run answered (2026-08-17)
+
+A4 **works**: playback survives the screen locking, and the transport
+notification appears with cover art — which also settles the service's
+access to a `MANAGE_EXTERNAL_STORAGE` path, the permission grant and
+the lock-screen session in one observation. Everything below in "what
+none of section A answered" was written before this and is now answered
+except the OEM permission-flow variance.
+
+It also found two faults no browser tier can see, both fixed and both
+awaiting the next APK for confirmation (`NOTES.md`, same date):
+
+- **Back quit the app from any depth.** The scaffold asks
+  `webView.canGoBack()`; the frontend had never used `history`. A
+  navigation is a history entry now, and `navStack` is gone rather than
+  kept beside it.
+- **The transport was under the gesture bar** — or so the version
+  number said. `applyWindowInsets()` in `MainActivity` is right and
+  stays, but the phone is **Android 14**, where the system still insets
+  the window: the fix is pre-emptive and the symptom has another cause.
+  Still open, along with icons that do not appear at all. The phone's
+  WebView is **Chrome 113**, which is the lead (no Popover API, no
+  relaxed CSS nesting), and `make android-inspect` / `android-eval` are
+  how it gets asked.
+
+The standing item is unchanged in kind: **B3 (tag writing) and the
+permission flow still need a device**, and so does confirming these two.
+
+### What none of section A answered
+
+Nothing here has been observed on a device. The permission flow in
+particular is the kind of thing that behaves differently across OEM
+builds — `ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION` is
+implemented inconsistently, which is why there is a fallback to the
+global list, and neither path has been exercised.
+
+A4 adds its own list of things only a device can answer, and they are
+the likely first failures: whether the notification appears at all
+(POST_NOTIFICATIONS is requested from `startForegroundService`, so a
+user who declines gets a service with an invisible notification),
+whether audio focus arrives while `oto`/oboe holds the output, whether
+the lock screen picks up the session, and whether cover art decoded
+from a `MANAGE_EXTERNAL_STORAGE` path is readable by the service.

.releaserc.yml

@@ -1,6 +1,20 @@
-# semantic-release configuration
-# Runs on main branch pushes to auto-determine version from conventional commits.
-# Creates a git tag + GitHub Release draft; a separate workflow builds binaries.
+# semantic-release configuration.
+#
+# Runs on pushes to main from .gitea/workflows/release.yml: determine the
+# version from the Conventional Commits since the last tag, write the
+# changelog, commit it, push the tag, and create the Gitea release.
+#
+# **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
 
@@ -63,19 +77,41 @@ plugins:
             section: Build
             hidden: true
 
-  # Write CHANGELOG.md.
+  # Render the notes to a file.
+  #
+  # **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: CHANGELOG.md
+    - changelogFile: .release-notes.md
+      changelogTitle: "# Release notes"
 
-  # Commit the changelog back to the repo.
-  - - "@semantic-release/git"
-    - assets:
-        - CHANGELOG.md
-      message: "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+  # Create the Gitea release, whose body is that section.
+  # `publish` runs after `prepare`, so the tag already exists by here.
+  - - "@semantic-release/exec"
+    - publishCmd: "./scripts/gitea-release.sh ${nextRelease.version}"
+
+  # **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

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CHANGELOG.md

@@ -1,377 +1,21 @@
-## [1.3.0](https://github.com/onion-4-dinner/yellowjacket/compare/v1.2.3...v1.3.0) (2026-03-20)
+# Changelog
 
-### Features
+The changelog is the releases page:
 
-* **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))
+<https://git.ljones.me/yonlu/yellowjacket/releases>
 
-### Bug Fixes
+Every release there is generated from the Conventional Commits it
+contains, by `.gitea/workflows/release.yml` on merge to `main`. Each one
+carries its notes as its body, grouped by change type, with a link to the
+commit behind every line.
 
-* **09-05:** emit VolumeChanged event and persist state in ChangeVolume and MuteToggle ([bb3fd20](https://github.com/onion-4-dinner/yellowjacket/commit/bb3fd204f0895f357a14479b40754f397aae74c4))
-* **10-01:** move library_id index to migration 6 to fix existing DB startup ([75b2a34](https://github.com/onion-4-dinner/yellowjacket/commit/75b2a349ebd6fada5cbc92bfae9854cc2cd53c63))
-* **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
+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 the next
+merge would release.
 
-### Performance
-
-* **12-02:** increase scan batch size from 50 to 300 ([21ea71e](https://github.com/onion-4-dinner/yellowjacket/commit/21ea71e2575d76258bd81d89ab8ac883aa3bed36))
-* **12-02:** skip FTS5 rebuild during library removal ([30f4461](https://github.com/onion-4-dinner/yellowjacket/commit/30f4461e6957e20d3dc607fa0886a75b5c21b3cf))
-* **14-01:** add CSS containment to app shell layout boundaries ([efa06f7](https://github.com/onion-4-dinner/yellowjacket/commit/efa06f7edf1e4acdc3d8865cad264403257ae40d))
-* **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))
+History before `v0.0.1` is in `git log`. The versions before it were cut
+by hand and are not on the releases page; the entries this file used to
+hold were generated against a GitHub remote this project no longer has,
+and every link in them was dead.

CLAUDE.md

@@ -144,7 +144,7 @@ meaningless against the seed's one empty playlist, so it builds ten
 It wraps every bound Go method, so "did that refetch the library" is a
 fact rather than an inference. It is not a spec and does not run in CI.
 
-**The cheapest tier needs none of that.** `make ui-test` runs 757
+**The cheapest tier needs none of that.** `make ui-test` runs 776
 Vitest tests in a real Chromium with no Wails, no backend, no seeded
 library and no virtual display, because **v3 routes every runtime call
 — bindings, event emits, window, dialogs, clipboard — through one IPC
@@ -233,6 +233,87 @@ rather than renaming them.
   the drift it caused before — `sql/schemas/` and the migrations
   disagreed, and sqlc generated against the stale one.
 
+  **What that costs an existing database is repaired once, at open.**
+  `CREATE ... IF NOT EXISTS` reaches an existing table only if its shape
+  already matches and otherwise silently no-ops, so a *changed* table
+  never migrates. Plan 014 added `total_tracks` to `explore_index` and
+  to `indexRowFields` — the projection every explore read uses — and no
+  database that already existed grew the column: **every** Explore
+  search, browse, artist and album page on such an install failed with
+  `no such column: total_tracks`, while a fresh install was perfectly
+  healthy, which is exactly why no test saw it. Plan 013 was worse on
+  the same install: `applySchema` could not be applied at all over a
+  pre-013 `audio_files`, so the app did not open.
+
+  `backend/database/staleshape.go` runs before `applySchema` and
+  retires what is stale, so the create is a create. Five things about
+  it are load-bearing:
+  - **It parses `sql/schemas/` for the expectation** rather than
+    writing the column list down a second time, because a second list
+    is a second thing to forget — the fault it exists to repair.
+  - **It notices a changed *type*, not just a missing column.** 013
+    moved `mbid` from TEXT to BLOB, and SQLite does not coerce between
+    them: a comparison against 16 raw bytes returns no rows rather than
+    an error. `ALTER TABLE ADD COLUMN` would have handled
+    `total_tracks` alone and cannot express this at all, which is why
+    the repair drops rather than migrates.
+  - **`Authored` is never retired**, and that boundary is a test
+    (`TestAuthoredTablesAreNeverRetired`), not a comment. Everything
+    else is rebuildable: `Cache` by definition, `Owned` by a rescan —
+    plan 013's stated "delete and rescan" — and `Derived` from Owned.
+    A table the schema no longer describes at all goes too; 013 left
+    seven behind plus `schema_migrations`.
+  - **Whether a stale `Cache` table may be rebuilt is a build tag**, and
+    it is the most expensive thing in this file to get wrong. In the app
+    the catalog is *downloaded*, so a wrong shape costs a minute of
+    re-fetching the artifact and keeping it costs every Explore read. In
+    `cmd/indexbuild` the catalog is *derived*, and the only way back is
+    the ~205 GB dump stream the `/cache` volume exists to avoid — so
+    `retireStaleCache` is false there (`staleshape_policy_indexbuild.go`)
+    and `TestTheCatalogSurvivesAStaleShape` fails the moment it is not.
+    `TestNoCacheTableIsRetiredHere` is the same assertion made of *every*
+    `datamap` Cache table rather than one, because the risk is not that
+    shape recurring — it is the next destructive repair added to
+    `database.NewDB`, the chokepoint every binary here shares, without
+    asking which binary it is in.
+    This is written down because it already happened: the repair shipped
+    without the distinction and dropped the real CI catalog on its first
+    run, with `reason="column entity_type is TEXT, schema declares
+    INTEGER"`. The mismatch was genuine — that database is deliberately
+    kept in the older encoding, which `fix(indexexport): read an index
+    older than the binary` exists to tolerate — so it would have been
+    dropped on *every* run. The consequence is that a future
+    `explore_index` column fails the index job loudly on `applySchema`
+    rather than silently costing it a rebuild, which is the trade a
+    human should get to make.
+  - **The drops are one transaction with `defer_foreign_keys`.** Those
+    legacy tables reference each other, so dropping them in any order
+    fails on whichever goes first, and turning foreign keys *off*
+    instead would silently take `playlist_tracks.audio_file_id`'s
+    ON DELETE SET NULL with it — leaving playlist entries pointing at
+    ids a rescan reissues to *different songs*. Nulled entries are
+    empty; stale ones are wrong, and wrong quietly.
+  - **The order is sorted, so a failure reproduces.** Map order is
+    random, and the foreign-key bug above passed its own regression
+    test on two runs in three until the order was fixed.
+
+  Retiring `explore_index` takes its FTS and its meta with it, because
+  the `dump_import_done` marker is what would otherwise stop the
+  artifact ever being fetched again.
+
+  **What that costs an existing database is that it does not open**, and
+  "delete and rescan" is the answer (plan 013, open question 1) — free
+  for everyone except one machine. The index job's `/cache` volume is a
+  real `YJ_HOME` that survives between runs, and half of it is the
+  catalog: deleting it means re-downloading ~205 GB. So `cmd/indexbuild`
+  repairs it instead (`staleschema.go`), dropping every table `datamap`
+  does not classify as `Cache` **before** the schema is applied. Nothing
+  scans, plays or authors in that database, so its non-catalog half is
+  empty by construction and a shape left over from an older schema is
+  pure liability. 013's reshaped `audio_files` failed every run of that
+  job on `CREATE INDEX ... album_id` against the old table until this;
+  `TestRetireLibraryTables` reproduces exactly that, symptom first.
+
   **The local library is shaped like files, not like MusicBrainz.**
   `audio_files` carries its own tags — title, artist credit, track and
   disc numbers, year, composer, the recording MBID — and points at two
@@ -298,12 +379,15 @@ rather than renaming them.
     `DB.QueryContext`/`QueryContextWith`/`QueryRow` route to a
     *query-only* read pool (a second `sql.DB` over the same file), so
     an `INSERT ... RETURNING` issued through one fails at runtime with
-    "attempt to write a readonly database (8)". Use `ExecContext`, or
-    `QueryRowWriter` when the statement really does return a row.
-    Nothing caught this because `NewTestDB` shares one in-memory
-    connection and leaves `readDB` nil, so `reader()` returns the
-    *writer* under test. `TestNoWritesOnTheReadPool` walks the tree for
-    it, in the same spirit as `TestNoDirectRuntimeEmits`.
+    "attempt to write a readonly database (8)" — which is exactly what
+    `CreateSmartPlaylist` did, meaning no smart playlist could be
+    created at all. Use `ExecContext`, or `QueryRowWriter` when the
+    statement really does return a row. Nothing caught this because
+    `NewTestDB` shares one in-memory connection and leaves `readDB`
+    nil, so `reader()` returns the *writer* under test.
+    `TestNoWritesOnTheReadPool` walks the tree for it, in the same
+    spirit as `TestNoDirectRuntimeEmits` and for the same reason — a
+    lint pass only sees one build configuration.
   - **A new table has to say what kind of data it holds.**
     `backend/datamap` is a catalogue of every table's Kind and
     Lifetime, and `TestCatalogCoversSchema` fails on a table missing
@@ -327,7 +411,26 @@ rather than renaming them.
   came about.
 - `config` — TOML-based settings. Settings page uses HTMX + templ for server-rendered HTML fragments.
 - `playlist` / `smartplaylist` — Playlist CRUD and rule-based smart playlists.
-- `mediacontrols` — MPRIS integration on Linux via D-Bus.
+- `mediacontrols` — OS media controls behind one `Handler`: MPRIS over
+  D-Bus on desktop Linux, a MediaSession on Android, a no-op stub
+  elsewhere. The split is by build tag and `android` implies `linux`,
+  so the three files read `linux && !android`, `android` and `!linux`.
+  Its Android half needs no JNI beyond what Wails exports — a JSON
+  payload out through `application.Android.StartForegroundService`, a
+  command event back through `WailsBridge.emitEvent` — and the Java it
+  talks to is `build/android/.../WailsForegroundService.java`. That
+  contract (payload keys, state words, command names) is in
+  `androidpayload.go` **without** the build tag, because a tagged file
+  is compiled by nothing `make lint` or `make test` runs and is
+  untestable off a phone.
+
+  `OnDuck` is the one callback MPRIS does not use: Android asks for
+  attenuation rather than a pause when something short needs the
+  output. `Player.SetDuck` keeps it as an offset on top of the user's
+  level rather than writing through to the volume, so it cannot
+  accumulate and nothing persists or emits a level the user did not
+  choose — and it only ever fires below API 26, where the framework
+  does not already duck the app itself.
 - `system` — OS-specific paths (XDG on Linux, `%LOCALAPPDATA%` on Windows).
 - `explore` — Catalog search and browse over `explore_index`. See below.
   Its **shelves** (`shelves.go`) are the page Explore shows before
@@ -473,6 +576,81 @@ selected as a literal `0`. Adding the column to the importer's SELECT
 list without that is how a published artifact — which nobody can re-cut
 retroactively — starts failing with `no such column`.
 
+**A credit is ordered parts, and the string is derived from them.** A
+track credited to several artists had exactly one navigable artist and
+the rest were punctuation: `primaryArtist()` string-parses the credit,
+strips a " feat. " clause and discards the guest, and deliberately does
+not split on `&`, `with` or `,` because those live inside real artist
+names ("Simon & Garfunkel"). Measured on a real 26,069-file library,
+**13%** of recordings are multi-artist upstream while only **0.86%** of
+files carry a structured multi-artist tag — mp3 carries *zero* files
+with multiple `MUSICBRAINZ_ARTISTID` across 19,840 — so this cannot be
+a tag-parsing feature. (The "3 credits of 2,823" figure that justified
+plan 013's removal of the credit tables measured our own *writer*:
+`cachedLinkArtist` ran once per credit, so a collaboration could never
+have been recorded. Dropping the join table was still right on cost.)
+
+`artist_credit_part` / `artist_credit_ref` carry the decomposition for
+multi-artist credits only — a single-artist credit is already
+`explore_index`'s own `artist_name`, and storing those would triple the
+table to say nothing. Five things about it are load-bearing:
+
+- **Join phrases are assembly instructions, not disassembly ones.**
+  `creditLink` concatenates parts, so link boundaries are known by
+  construction. Locating a `credited_name` *inside* the stored credit
+  string would reintroduce the fault this exists to fix: that string may
+  come from the file's tags while the parts come from the catalog, and
+  the two disagree for ~1 in 3 multi-artist credits (`'Skrillex feat.
+  Swae Lee'` tagged against `'Skrillex & Swae Lee'` upstream).
+- **`credited_name` is stored per row**, never joined from `artists`:
+  MusicBrainz credits "Snoop Dogg" on a track by the artist called
+  "Snoop Doggy Dogg". Display follows the credit, navigation the MBID.
+- **The lookup is keyed on the recording MBID**, which the catalog and a
+  local file both carry (`library.Track.RecordingMBID`), so one binding
+  serves Explore and the library's own lists — which is why this needed
+  no local table. `file_artists` remains the offline-resilience step and
+  is deliberately *not* declared until something writes it.
+- **Absence is cached as an answer.** `credit-store.ts` stores `[]` for
+  a single-artist credit — *asked*, not *answered* — or the ~87% that
+  have nothing to decompose are re-requested on every render forever.
+  `request()` is per-row and coalesces into one call per frame, because
+  a virtualized list cannot hand over "the whole list": 50,000 rows is
+  100 queries for the ~30 on screen.
+- **The dump is a third source, and it had to be.** The canonical dump
+  CI already streams has no join phrases and no as-credited names, and
+  the JSON dumps cover 153,691 recordings of ~35M with *zero* overlap
+  against a real library. So `mbdump.tar.bz2` — 7.1 GB, ~13.7 min in
+  pure-Go bzip2, whose members are alphabetical, which is what lets one
+  pass resolve an entity's credit without buffering 35M recordings. The
+  pass runs on **every** mode, because a complete import means
+  `refresh`, which never enters the importer at all, and it reports
+  whether it populated anything so `changed` republishes the artifact.
+
+**A 0.6 GB download asks about the connection first.** `explore`'s
+catalog artifact had no network awareness at all, which on a phone is a
+month's data allowance spent without being asked (plan 016 B4).
+`netpolicy.go` is the gate, and its shape is dictated by one constraint:
+`explore` is imported by `cmd/indexbuild`, which is built with
+`CGO_ENABLED=0` and must not link Wails — so the *policy* and the
+*parsing* live here and are tested on every platform, while the platform
+call is a closure injected from `app.go`. It is
+`application.Mobile.NetworkJSON()`, not `application.Android`'s: the
+latter exists only under the `android` build tag, and `Mobile`'s desktop
+implementation is a stub returning `""`.
+
+Three rules in it are load-bearing. **An unknown answer is not a metered
+one** — only mobile answers at all, so treating silence as metered would
+refuse the download on every desktop. **Cellular is the only signal
+available**: the runtime reports `wifi|cellular|ethernet|none` and no
+metered flag, so a metered *Wi-Fi* (a hotspot, a hotel) cannot be
+detected and is not refused, which is a documented gap rather than an
+oversight. And **the gate runs before anything is staged**, so declining
+is a no-op rather than a job in the indicator and a status the user has
+to dismiss. The permission (`AllowMeteredCatalogDownload`, default
+false, so an existing config is careful without a migration) is read at
+the moment a download would start, so turning it on takes effect on the
+next attempt rather than the next launch.
+
 **Background work yields, and says so in the context.** The post-scan
 backfills share MusicBrainz's rate limiters with every page the user
 can open, and both were FIFO — so a thousand-artist enrichment put an
@@ -648,6 +826,27 @@ moment it is most needed is the likeliest moment loading one fails.
 `first-run-wizard` and the startup chrome are eager for the ordinary
 reason — they are the first paint.
 
+**A navigation is a history entry, and that is the whole back stack.**
+`index.ts` records each navigation with `pushState` (same URL — the app
+has no routes, and a path a reload cannot resolve is worse than none)
+and replays `popstate` with `_isBack`. It exists for Android, whose back
+button is not a key the page can bind: the scaffold's
+`MainActivity.onBackPressed` asks `webView.canGoBack()` and finishes the
+activity otherwise, so an app that never touched `history` quit from any
+depth — which is what a device reported. Hooking the platform's own
+mechanism rather than adding a JNI callback is also what makes it
+testable in a browser (`page.goBack()`), and the Java half needed no
+change at all.
+
+Two rules hold it up. The **first** navigation *replaces* the launch
+entry rather than pushing one, or every launch costs a back press before
+the app will close. And the in-app back buttons (`navigate-back`, fired
+by the detail views and `now-playing-view`) go through `history.back()`
+rather than a stack of their own: the old `navStack` is **deleted**, not
+kept beside it, because two stacks is precisely how a view's own back
+button and the phone's gesture come to disagree about what one press
+means.
+
 **A primary view is cached, not unmounted.** `index.ts` keeps every
 primary view in the DOM and toggles a `.view-hidden` class, because that
 is what preserves `scrollTop` across navigation — so
@@ -803,6 +1002,20 @@ against the real components:
   moving focus without setting it leaves the highlight on whichever
   item the mouse last touched.
 
+**And a menu opens from a finger, through the event it already has.**
+`utils/long-press.ts` is one document-capture listener installed once
+from `index.ts`: a touch that holds still for 500 ms dispatches a
+synthetic `contextmenu` at the touch point, so all six components that
+bind one — delegated on a virtualizer, per row, per card — gained the
+gesture without changing. The target is `composedPath()[0]` rather than
+`elementFromPoint`, which stops at the outermost shadow host and so
+reaches a delegated listener and no per-row one; a browser that fires
+its own long-press `contextmenu` (Chromium does, WebKit and the WebView
+vary) wins, ours being told from theirs by **identity** rather than
+`isTrusted`, since no test can dispatch a trusted event; and the click
+that ends the gesture is swallowed, keyed on the gesture rather than on
+a time window so the first tap on the menu it opened is not eaten too.
+
 Three lists had no focused row to open a menu *from* — the queue panel
 and both playlist detail views — and gained a roving tab stop through
 `utils/roving-rows.ts`. **`track-list` deliberately does not use it**:
@@ -973,6 +1186,65 @@ this app promises, no scrollbar appears. Note that `overflow: hidden`
 still permits *programmatic* scrolling, so a probe that sets
 `scrollLeft` passes on the broken build; the spec uses a wheel gesture.
 
+**Below 600px it reflows instead, and that is the phone.** The sideways
+scroll above was the concession available while the shell had one
+layout; plan 016 B2 gives it a second. Under 600px the grid drops its
+sidebar column, `<bottom-nav>` takes over as the primary navigation,
+the header's controls shrink or stand down, and the shell measures
+exactly 320px in a 320px viewport — so `layout-overflow.spec.ts` now
+asserts *nothing needs scrolling to*, which is what WCAG 1.4.10 wanted
+all along. 600 rather than the sidebar's 900 because 900 is a laptop:
+the answer there is a narrower sidebar, which is still a sidebar.
+
+Three rules in it are load-bearing, and the second cost 30 specs.
+
+**A grid item's implicit minimum is its content**, so one child that
+insists on 580px makes the *body* 580px wide inside a 360px viewport
+and `overflow-x: hidden` then hides a third of the app rather than
+fitting it. Every box between the viewport and the content that must
+shrink carries `min-width: 0`, and the things that cannot shrink say so
+in their own stylesheet — `search-bar`'s 200px floor, `job-indicator`'s
+label, `audio-player`'s seek bar and volume. A media query inside a
+shadow root is answered by the viewport, so a component states what it
+drops at phone width itself rather than the shell reaching in.
+
+**A duplicated component duplicates its handles.** `bottom-nav`'s
+"More" opens the *same* `<app-sidebar>` in a `wa-drawer` rather than
+listing the destinations again — but rendering it unconditionally put a
+second copy of every `data-testid="nav-*"` in the DOM, and 30 existing
+specs failed with "strict mode violation: resolved to 2 elements" on a
+desktop viewport where the element is not even visible. It renders only
+while the drawer is open, and `bottom-nav.test.ts` asserts its absence
+before that.
+
+**The tab bar is four destinations and a way to the rest.** Three to
+five is where touch targets stop being thumb-sized; eleven over 360px
+is 32px each. Which four is plan 016's committed subset, and everything
+else — Settings included, because a phone still needs it — is behind
+"More".
+
+**The phone section of `index.css` is last on purpose.** A media query
+adds no specificity, so a `@media (max-width: 599px)` block placed
+above the plain rules it overrides loses to them — which is how phase 1
+shipped a header that kept its 2em gutters and 24px title on a 390px
+phone with every declaration dead and nothing failing. The shell fitted
+anyway, because the fitting is done by `min-width: 0` and by each
+component's own media query, which live in their own stylesheets and
+have no later rule to lose to. Cosmetic declarations are exactly what
+no assertion sees; a screenshot found it.
+
+**`<now-playing-view>` is where the seek bar and volume went.** It is a
+*detail* view (`DETAIL_LOADERS`, so the nav stack carries the way out —
+a tab you cannot leave by pressing again is not a tab), reached from a
+phone-only button over the mini player's art, and it **composes the
+real `<seek-bar>`, `<player-controls>` and `<volume-control>`** rather
+than reimplementing them. While it is up, `index.css` hides the bottom
+bar through `body:has(#main-content[data-active-view="now-playing"])` —
+the active view is already published as an attribute, and a class
+toggled from `index.ts` would be a second expression of the same fact.
+The view therefore carries its own queue button, because that button
+lives in the bar it hides.
+
 **The playing row is a shape, not a hue.** `track-list` and
 `queue-panel` draw a `::before` triangle in each row's own left
 padding, plus `aria-current` — before, both rows were a background tint
@@ -1407,6 +1679,28 @@ by the three places that need them (the default widths, the
 normaliser, and the resize handles' positions), because they were
 written out separately and that is how they came to disagree.
 
+**A phone draws one column of two lines, and that is a column set
+rather than a second row template.** Measured on the device: at 424 px
+the four configured columns fit the row *exactly* (`--grid-cols` came
+out `24px 102px 101px 101px 80px`) and not one of them fit its content
+— "Duration" did not fit its own header. The columns were never too
+wide; there were too many of them. `PHONE_COLUMN_IDS` is `titleArtist`
+(title over artist, sharing the row's whole width) plus the duration, so
+the row, the delegated events, the selection semantics, the playing
+marker and the virtualizer are all untouched: from their side only the
+number of columns changed. Three rules come with it. **The row height
+lives in two places and they must agree** — `PHONE_ROW_HEIGHT` and the
+CSS rule — because the virtualizer positions rows from that number, so a
+taller row overlaps its neighbour. **What is drawn and what can be
+sorted are different questions**: the page header's sort list is built
+from `configuredColumns`, or a phone (which has no column headers
+either) could sort by nothing but title and duration. And **a phone's
+widths are neither loaded nor saved**: `loadColumnWidths` is keyed by
+column *id* and fills a gap with the minimum, so the stacked column —
+which nothing can ever have saved a width for — came out at 148 px
+beside a duration column of 236, and saving would have replaced the
+width the user dragged on a desktop for the same id.
+
 **The default columns are declared twice and must agree.**
 `tracklist.DefaultColumns` is what a fresh install persists;
 `DEFAULT_COLUMN_IDS` in `track-list/columns.ts` is what the list draws
@@ -1698,6 +1992,21 @@ frontend would receive (`backend/queue/emit_test.go` is the model).
 `events.Deliver` is the same call returning an error instead of
 dropping, and has one legitimate caller — `/__test/emit`.
 
+**Naming the Wails application costs cgo, so exactly two files may.**
+v3's `application` package is GTK/WebKit bindings on Linux, and
+`cmd/indexbuild` / `cmd/indexexport` are built in a plain `golang`
+container with `CGO_ENABLED=0` — the index workflow says so and it is
+the one job that must not fail, since it owns the ~205 GB checkpoint.
+So the single `app.Event.Emit` lives in `backend/events/runtime_wails.go`
+under `//go:build !indexbuild` (with `runtime_indexbuild.go` returning
+`ErrNoRuntime`, which is what the app itself returns before Run), and
+`explore`'s `ServiceStartup` — the only other thing in that dependency
+tree naming `application` — sits in `backend/explore/servicestartup.go`
+under the same tag. `TestIndexToolsDoNotImportWails` walks the dependency
+graph with `go list -deps -tags indexbuild` and is what keeps it that
+way; a `ServiceStartup` hook added to a package the index tools import
+is the way this comes back.
+
 ## Code Generation
 
 Two generators run via `go generate ./...` (or `make generate`):
@@ -1718,13 +2027,31 @@ Pre-commit hooks verify generated code is fresh — always run `make generate` a
   two in step or semantic-release will decline to release something the
   check accepted.
 
-  `.releaserc.yml` is a complete semantic-release config that **nothing
-  currently runs** — no workflow invokes it, and `CHANGELOG.md` is not
-  being written by it. That is deliberate for now (wiring it means pushing
-  tags, committing a changelog back, and interacting with the three
-  publish workflows); it is recorded here rather than implied, because
-  this file claimed for five phases that commitlint gated CI and that
-  semantic release ran, and neither was true.
+  `.releaserc.yml` **is** what runs now, from `release.yml`, and it is why
+  the commit grammar is load-bearing rather than decorative: a merge to
+  `main` whose commits are all `chore`/`ci`/`docs` releases nothing, and a
+  mistyped `feat` ships a minor version. `make release-dry` answers "what
+  would this merge release" without pushing.
+
+  **`@semantic-release/github` is not in that config and must not be.**
+  Gitea's API is `/api/v1` and is not GitHub's surface, so
+  `@semantic-release/exec` calls `scripts/gitea-release.sh` instead — one
+  `POST`, which is the whole of the Gitea-shaped work. The community
+  plugin (`@saithodev/semantic-release-gitea`) was considered and
+  rejected: last published 2022, on `got@10`, declaring no peer
+  dependency on semantic-release at all.
+
+  Two things in it fail *silently* and are therefore pinned with their
+  reasons. **The notes come from `CHANGELOG.md`, not from an argument**:
+  release notes are rendered commit messages — arbitrary text carrying
+  backticks, quotes and `$` — so templating `${nextRelease.notes}` into
+  `publishCmd` would be a shell injection whose input is the commit log.
+  And **`conventional-changelog-conventionalcommits` is held at 9**,
+  because at 10 it is quietly incompatible with the writer
+  `release-notes-generator@14` pulls in: every release note renders as a
+  bare `## 0.0.1 (date)` heading with no sections and no commits beneath
+  it, no step fails, and the release ships with an empty body. Check the
+  rendered notes, never the exit code.
 
 ## Testing
 
@@ -1733,14 +2060,97 @@ Tests use `database.NewTestDB(t)` for in-memory SQLite, built by the same
 
 ## Git Workflow
 
-Feature branches and PRs are the norm, but direct pushes to `main` are allowed. Pre-commit runs vet, lint, codegen check, and frontend typecheck in parallel. Pre-push runs the full test suite.
+Feature branches and PRs are the only way in: **`main` is a protected
+branch** (`enable_push: false`, an empty push whitelist, and `CI / check*`
++ `CI / e2e*` as required status checks), so a direct push is rejected by
+the pre-receive hook. This file said otherwise for a long time. Tags are
+*not* protected, which is what lets `release.yml` push one.
+
+Pre-commit runs vet, lint, codegen check, and frontend typecheck in parallel. Pre-push runs the full test suite.
 
 ## CI
 
-Four workflows in `.gitea/workflows/`. Three of them package and
-publish (`arch-package`, `homebrew-formula`, `index-artifact`); only
-`ci.yml` gates, and it is the one to look at when deciding whether a
-push was healthy.
+Seven workflows in `.gitea/workflows/`. Five of them package and
+publish (`arch-package`, `homebrew-formula`, `index-artifact`,
+`android-apk`, `desktop-assets`); `release.yml` decides *whether* four of
+those run at all; only `ci.yml` gates, and it is the one to look at when
+deciding whether a push was healthy.
+
+**`release.yml` is the entry point for all of it.** On every push to
+`main` it reads the Conventional Commits since the last tag and, if any
+is releasable, writes the changelog, pushes the tag and creates the Gitea
+release whose body is that changelog section. `arch-package`,
+`homebrew-formula`, `android-apk` and `desktop-assets` are all keyed on
+`v*`, so **the tag push is what starts them** — nothing is released by
+hand any more.
+
+Four things about it are load-bearing:
+
+- **The tag is pushed with a user PAT, 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,
+  so `PACKAGE_TOKEN` is handed to semantic-release as the
+  `repositoryUrl` credential and the push is attributed to a person.
+- **That same limitation is used deliberately, once.** semantic-release
+  calls the first release of a tagless repo `1.0.0` and offers no way to
+  say otherwise, so a `v0.0.0` floor tag is what makes the first release
+  `0.0.1` — and it is pushed with the *Actions* token precisely so it
+  triggers nothing. All four publishers additionally skip `v0.0.0`
+  explicitly, cleanly rather than by failing, because a floor is not a
+  shipment.
+- **The release page is the changelog, and that follows from the branch
+  protection.** `@semantic-release/git` would push a `chore(release):`
+  commit back to `main`, which the pre-receive hook rejects — *after* the
+  tag had been pushed, leaving a tagged release the run then reports as
+  failed. Whitelisting the CI user was the alternative and was declined:
+  it weakens a protection someone set on purpose and lets a bot push to
+  `main` without the checks every human PR passes. So the plugin is
+  absent, `@semantic-release/changelog` writes to a gitignored
+  `.release-notes.md` purely to carry the notes into
+  `scripts/gitea-release.sh`, and `CHANGELOG.md` is a signpost to the
+  releases page rather than a file that would silently stop updating.
+  The workflow keeps its `chore(release):` guard anyway, for the day
+  someone adds the plugin back.
+- **An asset upload waits for the release to exist.** semantic-release
+  pushes the tag in `prepare` and creates the release in `publish`, so
+  the tag push that starts these workflows happens *before* there is a
+  release id to attach to. `scripts/release-asset.sh` polls for it. The
+  capacity-1 runner serialises things enough that this would usually work
+  by accident, which is the worst kind of bug.
+
+**Releases restarted at `0.0.1`, which is a downgrade on every channel.**
+pacman and Homebrew both silently offer no upgrade from the old `1.x`,
+and Android refuses the install outright — its remedy is an uninstall
+that takes the user's library. This was chosen over pacman's `epoch` and
+over offsetting `versionCode`, on the grounds that both are permanent and
+a reinstall is once. `packaging/homebrew/README.md` and
+`docs/android-release.md` say so where a user would look.
+
+**`desktop-assets.yml` publishes Linux and nothing else, 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. Windows *does* cross-compile
+cleanly (`GOOS=windows CGO_ENABLED=0`, a couple of seconds — oto uses
+WinMM through `x/sys`, sqlite is modernc's pure-Go driver, WebView2 is
+COM syscalls, MPRIS is `linux && !android`-tagged) and is deliberately
+not published: no Windows build of this app has ever been *run*, and no
+tier here can exercise one.
+
+**`android-apk.yml` is the one that can lose something irrecoverable.** It builds the signed
+`arm64-v8a` APK (the only ABI Android can run this app on — see
+`app/build.gradle`) on every `v*` tag and publishes it to the *generic* registry, which is
+readable without credentials — the reason Obtainium can poll a plain
+URL. Android refuses to update an app whose signing certificate
+changed, and the only remedy is an uninstall that takes the user's
+library with it, so the job **refuses to build** without the keystore
+secret rather than falling through to Gradle's debug-key default, and
+**refuses to publish** an artifact whose certificate says `CN=Android
+Debug`. It is deliberately not a job in `ci.yml`: that workflow runs on
+every branch push, this one takes tens of minutes on a cold cache, and
+the runner has capacity 1. `docs/android-release.md` is the operating
+document.
 
 Two jobs, both in an `ubuntu:24.04` container:
 
@@ -1822,11 +2232,47 @@ four bit the packaging recipes:
 **`build/`'s platform metadata is generated from `build/config.yml`.**
 `wails3 task common:update:build-assets` rewrites `Info.plist`, the
 `.desktop` template, `nfpm.yaml` and the Windows manifest from that
-one file — so a hand edit to any of them is lost on the next refresh,
-and the two fields it does *not* own (nfpm's `homepage` and `license`)
-say so in place. That refresh also regenerates `build/ios/` and
-`build/android/`, which this repo does not carry: they are gitignored
-rather than deleted-and-rediscovered, and their `includes:` entries
-are dropped from `Taskfile.yml`. `build/config.yml`'s `version` is the
+one file — so a hand edit to any of them is lost on the next refresh.
+nfpm's `homepage` and `license` say in place that the refresh does not
+own them, and **that comment is wrong**: a refresh reset them to
+`https://wails.io` and `MIT`. Re-check those two after any refresh.
+
+**That refresh does not touch the mobile trees**, contrary to what this
+file said for five phases. `update build-assets` extracts only
+`updatable_build_assets` (darwin/ios/linux/windows); `build/android/`
+and `build/ios/` come from `generate build-assets`, which rewrites the
+whole of `build/`. So `build/android/` is **committed and hand-edited
+like source** — it was generated once into a scratch directory and
+copied across (plan 015), it carries one deliberate edit to its
+`Taskfile.yml`, and only its output is gitignored. `build/ios/` is
+still not carried and its `includes:` entry is still dropped.
+**Its `MainActivity` owns the safe area, because `targetSdk 35` does
+not leave that to the theme.** Android 15 lays every app out
+edge-to-edge and ignores the `statusBarColor`/`navigationBarColor` the
+scaffold's theme sets, and the WebView is `match_parent`, so the page's
+bottom band — the transport and, on a phone, the tab bar — would be
+drawn under the gesture bar. `applyWindowInsets()` pads the container by
+`systemBars | displayCutout | ime` and returns the insets rather than
+consuming them; the window background is black to match the app's own
+ramp, since that padding is what shows through. It is **pre-emptive**:
+the phone this was checked against is Android 14, where the system still
+insets the window, and the enforcement applies to an app *running on*
+15. No browser tier can see this class of fault either way — a viewport
+has no system bars.
+
+**And a device is an engine, not just a screen.** The phone this app was
+first run on renders in **Chrome 113** — two years behind every browser
+any other tier uses — at a 424x439 CSS px viewport. It has `:has()`,
+`color-mix()` and `dialog.showModal()`; it does **not** have relaxed CSS
+nesting (Chrome 120, so a nested rule beginning with a bare element
+selector is silently dropped), the Popover API (114, which Web Awesome's
+popups set `popover="manual"` for), `light-dark()` or relative colour
+syntax. So "it renders at that size in Chromium" is not evidence about
+the phone, and resizing a spec cannot recover the missing signal. `make
+android-inspect` forwards the WebView's devtools socket and `make
+android-eval` asks the real page — raw CDP, because `connectOverCDP`
+calls `Browser.setDownloadBehavior` and a WebView refuses it.
+
+`build/config.yml`'s `version` is the
 *metadata* version and is not what the app reports — `main.version` is
 stamped at link time from the packaging recipe's git-derived version.

Makefile

@@ -38,6 +38,64 @@ dev-stop: ## Stop the headless app (SIGTERM, so shutdown hooks run)
 dev-logs: ## Tail the headless app log
 	@tail -f .dev/app.log
 
+# ---------------------------------------------------------------- #
+# The Android tier.  See .pi/skills/yellowjacket-dev/references/     #
+# android-tier.md for which of these to reach for and why a failure  #
+# here looks like nothing at all.                                    #
+# ---------------------------------------------------------------- #
+
+# The NDK is pinned: r26d is what the pipeline is built and checked
+# against, and newer NDKs have broken Wails' Android build before.
+# ANDROID_HOME must carry a *platform*, which Arch's /opt/android-sdk
+# does not — hence the separate default.
+ANDROID_SDK ?= $(HOME)/Android/Sdk
+ANDROID_NDK ?= /opt/android-ndk
+ANDROID_ENV := ANDROID_HOME=$(ANDROID_SDK) ANDROID_SDK_ROOT=$(ANDROID_SDK) ANDROID_NDK_HOME=$(ANDROID_NDK)
+
+# `package`, not `package:fat`: x86_64 Android cannot run this app at
+# all (modernc's raw lstat vs Android's seccomp -- see
+# android-tier.md), so the second ABI was ~31 MB that could not run
+# anywhere.  app/build.gradle's abiFilters says the same thing to
+# Gradle; both have to agree or the .so is built and then dropped.
+android: build-frontend ## Build the arm64 APK into bin/
+	@$(ANDROID_ENV) PATH="$(TOOLBIN):$$PATH" go tool wails3 task android:package
+
+android-setup: ## Install the SDK pieces and create the AVD (once, ~3.5GB)
+	@$(ANDROID_ENV) ./scripts/android-emulator.sh setup
+
+android-emulator: ## Boot the emulator headless in the background and wait for it
+	@$(ANDROID_ENV) ./scripts/android-emulator.sh start
+
+android-emulator-stop: ## Shut the emulator down (console kill, then saved PID)
+	@$(ANDROID_ENV) ./scripts/android-emulator.sh stop
+
+android-install: ## Install bin/yellowjacket.apk onto the running emulator
+	@$(ANDROID_ENV) ./scripts/android-emulator.sh install
+
+android-launch: ## Force-stop, clear logcat, and start the app
+	@$(ANDROID_ENV) ./scripts/android-emulator.sh launch
+
+android-logs: ## Tail logcat, filtered to the app's own tags
+	@$(ANDROID_ENV) ./scripts/android-emulator.sh logs
+
+# The only tier that can see the platform is the one you can look at.
+android-screenshot: ## Grab the device screen (OUT=<path>)
+	@$(ANDROID_ENV) ./scripts/android-emulator.sh screenshot $(OUT)
+
+# The page's own answer, from the engine that is really rendering it.
+# Needs the debug build installed (it is a sibling id, so it does not
+# disturb the release app): see scripts/android-eval.mjs.
+android-inspect: ## Forward the device WebView's devtools socket
+	@$(ANDROID_ENV) ./scripts/android-emulator.sh inspect
+
+android-eval: ## Evaluate JS in the device WebView (EXPR='...')
+	@node ./scripts/android-eval.mjs $(if $(EXPR),'$(EXPR)',)
+
+# "Did it start" is the wrong question — a crash-looping app starts
+# several times a second.  This asserts the *same pid* is still there.
+android-smoke: ## Launch and assert the app is still alive (SECONDS=<n>)
+	@$(ANDROID_ENV) ./scripts/android-emulator.sh smoke $(if $(SECONDS),$(SECONDS),10)
+
 # Seeds are produced by *running the app* — driving the real AddLibrary
 # binding and waiting for the real scan — never by hand-writing a
 # config.toml and DB rows.  A hand-built seed is a second description
@@ -121,10 +179,12 @@ 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/ documents commands, and a skill that documents a command wrongly
-# is worse than no skill: an agent runs it confidently.  Every command
-# in there is a make target on purpose, so this is checkable.
-skill-check: ## Fail if .pi/ documents a make target that does not exist
+# .pi/ and CLAUDE.md document commands, and a doc that documents a
+# command wrongly is worse than no doc: an agent runs it confidently.
+# Every command in them is a make target on purpose, so this is
+# checkable.  It also asserts AGENTS.md is a symlink to CLAUDE.md, so the
+# 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
@@ -132,6 +192,24 @@ skill-check: ## Fail if .pi/ documents a make target that does not exist
 commit-check: ## Fail if a commit subject is not a Conventional Commit
 	@./scripts/commit-check.sh $(if $(RANGE),--range $(RANGE))
 
+# What a merge to main would release, without releasing 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.
+#
+# 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 merge to main would release
+	@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'.
@@ -147,7 +225,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
+	bindings bindings-check skill-check commit-check release-dry
 
 # Base directory for fresh-install sandboxes. Deliberately NOT $TMPDIR:
 # on most Linux distros /tmp is tmpfs (RAM-backed) and only a few GB, so

Taskfile.yml

@@ -15,6 +15,7 @@ includes:
   windows: ./build/windows/Taskfile.yml
   darwin: ./build/darwin/Taskfile.yml
   linux: ./build/linux/Taskfile.yml
+  android: ./build/android/Taskfile.yml
 
 tasks:
   build:

backend/app.go

@@ -191,6 +191,24 @@ func NewYellowJacketApp(
 	yjApp.library.SetJobRegistry(yjApp.jobs)
 	yjApp.explore.SetJobRegistry(yjApp.jobs)
 
+	// Whether this connection is one to spend ~0.6 GB of catalog on
+	// (plan 016 B4). The probe is injected from here because `explore` is
+	// imported by `cmd/indexbuild`, which must not link Wails: naming
+	// `application` there is what `TestIndexToolsDoNotImportWails`
+	// forbids.
+	//
+	// `application.Mobile`, not `application.Android`: the latter exists
+	// only under the `android` build tag, while `Mobile` is the portable
+	// name whose desktop implementation is a stub returning "" — which
+	// parses to "unknown" and refuses nothing. Plan 016 named the tagged
+	// one; this is the same call by the name every build has.
+	yjApp.explore.SetNetworkPolicy(
+		func() explore.Network {
+			return explore.ParseNetworkJSON(application.Mobile.NetworkJSON())
+		},
+		yjApp.appConfig.GetAllowMeteredCatalogDownload,
+	)
+
 	// Let the release prefetch skip albums the user already owns in
 	// full — those open with no catalog call at all, so warming their
 	// tracklists spends the most expensive request in the app on
@@ -484,20 +502,24 @@ func (yj *YellowJacketApp) OnStartup(ctx context.Context) {
 	// Register playback finished handler to drive queue auto-advance.
 	yj.player.SetPlaybackFinishedHandler(yj.queue.OnPlaybackFinished)
 
-	// Initialize OS media controls (MPRIS on Linux, no-op elsewhere).
+	// Initialize OS media controls (MPRIS on desktop Linux, a
+	// MediaSession on Android, no-op elsewhere). The callbacks are the
+	// same on every platform; only what delivers them differs.
 	yj.mediaControls = mediacontrols.NewHandler(yj.logger)
 
 	if err := yj.mediaControls.Init(mediacontrols.Callbacks{
 		OnPlay: yj.queue.Play,
 		OnPause: func() {
 			if err := yj.player.Pause(); err != nil {
-				yj.logger.Warn("MPRIS Pause failed", "err", err)
+				yj.logger.Warn("Media controls Pause failed", "err", err)
 			}
 		},
 		OnPlayPause: func() {
 			if yj.player.IsPlaying() {
 				if err := yj.player.Pause(); err != nil {
-					yj.logger.Warn("MPRIS PlayPause(pause) failed", "err", err)
+					yj.logger.Warn(
+						"Media controls PlayPause(pause) failed", "err", err,
+					)
 				}
 			} else {
 				yj.queue.Play()
@@ -505,14 +527,14 @@ func (yj *YellowJacketApp) OnStartup(ctx context.Context) {
 		},
 		OnStop: func() {
 			if err := yj.player.Pause(); err != nil {
-				yj.logger.Warn("MPRIS Stop failed", "err", err)
+				yj.logger.Warn("Media controls Stop failed", "err", err)
 			}
 		},
 		OnNext:     yj.queue.Next,
 		OnPrevious: yj.queue.Previous,
 		OnSeek: func(positionSec int) {
 			if err := yj.player.Seek(positionSec); err != nil {
-				yj.logger.Warn("MPRIS Seek failed", "err", err)
+				yj.logger.Warn("Media controls Seek failed", "err", err)
 			}
 		},
 		OnVolume: func(vol float64) {
@@ -522,6 +544,7 @@ func (yj *YellowJacketApp) OnStartup(ctx context.Context) {
 				),
 			)
 		},
+		OnDuck: yj.player.SetDuck,
 	}); err != nil {
 		yj.logger.Error(
 			"Failed to initialize media controls",

backend/config/config.go

@@ -411,9 +411,10 @@ func (c *Config) SetDownloadPreferences(prefs download.AutoDownloadPrefs) error
 		formats = append(formats, string(f))
 	}
 
-	c.Downloads.MinFileSizeMB = prefs.MinSizeMB
+	c.Downloads.MinKbps = prefs.MinKbps
+	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 {
@@ -620,6 +621,51 @@ func (c *Config) SetQueueFallback(mode string) error {
 	return nil
 }
 
+// GetAllowMeteredCatalogDownload reports whether the ~0.6 GB Explore
+// catalog may be fetched on a metered connection.
+func (c *Config) GetAllowMeteredCatalogDownload() bool {
+	if c.General == nil {
+		return false
+	}
+
+	return c.General.AllowMeteredCatalogDownload
+}
+
+// SetAllowMeteredCatalogDownload saves the metered-download permission.
+//
+// There is nothing to validate and nothing to restart: the policy is
+// read at the moment a download would start, so turning it on takes
+// effect on the next attempt rather than needing this launch to be over.
+func (c *Config) SetAllowMeteredCatalogDownload(allow bool) error {
+	if c.General == nil {
+		c.General = &GeneralConfig{}
+		c.General.ApplyDefaults()
+	}
+
+	c.General.AllowMeteredCatalogDownload = allow
+
+	if err := c.Save(); err != nil {
+		return fmt.Errorf(
+			"could not save config: %w", err,
+		)
+	}
+
+	events.Emit(
+		c.ctx,
+		events.GeneralConfigChanged,
+		map[string]any{
+			"AllowMeteredCatalogDownload": allow,
+		},
+	)
+
+	c.logger.Info(
+		"metered catalog download permission updated",
+		"allow", allow,
+	)
+
+	return nil
+}
+
 // GetTrackListColumns returns the configured track-list columns.
 func (c *Config) GetTrackListColumns() []tracklist.Column {
 	if c.TrackList == nil {

backend/config/general.go

@@ -48,6 +48,12 @@ var errUnknownQueueFallback = errors.New("unknown queue fallback")
 type GeneralConfig struct {
 	DefaultPage   DefaultPage   `toml:"DefaultPage"`
 	QueueFallback QueueFallback `toml:"QueueFallback"`
+	// 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"`
 }
 
 // ApplyDefaults fills zero-value fields with sensible defaults.

backend/database/database.go

@@ -89,6 +89,14 @@ func NewDB(logger *slog.Logger) (*DB, error) {
 		return nil, fmt.Errorf("could not apply PRAGMAs: %w", err)
 	}
 
+	// Before the schema is applied, not after: applySchema is
+	// CREATE ... IF NOT EXISTS, which no-ops against a table that
+	// already exists in an older shape.  Retiring the stale one first is
+	// what turns that no-op into a create.
+	if err := retireStaleTables(dbCtx, db, logger); err != nil {
+		return nil, err
+	}
+
 	if err := applySchema(dbCtx, db); err != nil {
 		return nil, err
 	}

backend/database/sql/schemas/artist_credit_part.sql

@@ -0,0 +1,56 @@
+-- The decomposition of a multi-artist credit, from the MusicBrainz
+-- dump.  One row per credited artist, in credit order.
+--
+-- A credit is ordered parts, and the credit *string* is derived from
+-- them -- MusicBrainz's own `artist_credit.name` is a cached render and
+-- nothing more.  Rendering is a concatenation:
+--
+--     for each part in position order:
+--         emit link(credited_name -> artist_mbid)
+--         emit text(join_phrase)
+--
+-- so the link boundaries are known by construction.  That is the whole
+-- reason this table exists, and it is why nothing may reconstruct a
+-- credit by *searching* for a name inside a credit string: the stored
+-- string may have come from a file's tags while the parts come from the
+-- catalog, and measured on a real library those disagree for about one
+-- in three multi-artist credits ("Skrillex feat. Swae Lee" tagged
+-- against "Skrillex & Swae Lee" upstream).  A search would miss, or
+-- match the wrong span.
+--
+-- `credited_name` is the name *as credited*, which is not the artist's
+-- canonical name: MusicBrainz credits "Snoop Dogg" on a track by the
+-- artist whose name is "Snoop Doggy Dogg".  It is stored per row rather
+-- than joined from an artist table for exactly that reason.
+--
+-- Only *multi-artist* credits are stored.  A single-artist credit is
+-- (name, "") and is already fully described by explore_index's
+-- artist_name and artist_mbid; storing those would roughly triple the
+-- table to say nothing new.
+--
+-- Credits are shared: an album's twelve tracks by one artist reference
+-- one credit_id.  That is the opposite of the local library's verdict
+-- in plan 013, and correctly so -- credit sharing is 1:1 in one
+-- person's files and genuinely many-to-one across a 2M-row catalog.
+--
+-- MBIDs are the same 16 raw bytes explore_index stores, for the same
+-- size reason and with the same CHECK, so a stringly write fails at the
+-- insert that made it rather than reading back as no rows at all.  See
+-- backend/explore/mbid.go.
+CREATE TABLE IF NOT EXISTS artist_credit_part (
+    credit_id     INTEGER NOT NULL,
+    position      INTEGER NOT NULL,
+    artist_mbid   BLOB NOT NULL CHECK(length(artist_mbid) = 16),
+
+    -- The name as credited on this release, which may differ from the
+    -- artist's canonical name.  Display uses this; navigation uses the
+    -- MBID above.
+    credited_name TEXT NOT NULL,
+
+    -- The literal connector that follows this part -- " feat. ", " & ",
+    -- ", ", or "" on the last part.  Rendered as plain text between two
+    -- links.
+    join_phrase   TEXT NOT NULL DEFAULT '',
+
+    PRIMARY KEY (credit_id, position)
+) WITHOUT ROWID;

backend/database/sql/schemas/artist_credit_ref.sql

@@ -0,0 +1,30 @@
+-- Which credit a catalog entity is credited to.  One row per recording
+-- or release group whose credit names more than one artist.
+--
+-- This is a table rather than an `explore_index.artist_credit_id`
+-- column, and that is a deliberate consequence of how this app applies
+-- its schema.  `applySchema` is CREATE ... IF NOT EXISTS and there is
+-- no migration chain (plan 013), so a *column* added to an existing
+-- table never reaches a database that already has it -- while a new
+-- *table* is created on every install, old or new, for free.
+-- explore_index is the one table nobody can afford to drop and rebuild
+-- on a schema change: it is the artifact users download rather than
+-- derive.
+--
+-- Only multi-artist credits are referenced here, matching
+-- artist_credit_part.  An entity with no row is credited to exactly one
+-- artist, which explore_index's own artist_name and artist_mbid already
+-- describe -- so absence is the common case and means "nothing to
+-- decompose", not "unknown".
+--
+-- `credit_id` is opaque and is only meaningful against the
+-- artist_credit_part rows built or imported alongside it.  The two are
+-- always written together; nothing persists a credit_id anywhere else.
+-- The local library stores resolved parts, never this id.
+CREATE TABLE IF NOT EXISTS artist_credit_ref (
+    mbid      BLOB NOT NULL PRIMARY KEY CHECK(length(mbid) = 16),
+    credit_id INTEGER NOT NULL
+) WITHOUT ROWID;
+
+CREATE INDEX IF NOT EXISTS idx_artist_credit_ref_credit
+    ON artist_credit_ref(credit_id);

backend/database/sql/sqlcgen/models.go

@@ -27,6 +27,19 @@ type Artist struct {
 	Mbid sql.NullString
 }
 
+type ArtistCreditPart struct {
+	CreditID     int64
+	Position     int64
+	ArtistMbid   []byte
+	CreditedName string
+	JoinPhrase   string
+}
+
+type ArtistCreditRef struct {
+	Mbid     []byte
+	CreditID int64
+}
+
 type ArtistEnrichment struct {
 	ArtistMbid string
 	BrowsedAt  sql.NullTime

backend/database/staleshape.go

@@ -0,0 +1,560 @@
+package database
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"maps"
+	"path"
+	"slices"
+	"strings"
+
+	"yellowjacket/backend/datamap"
+)
+
+// This file repairs the one thing `CREATE TABLE IF NOT EXISTS` cannot.
+//
+// `sql/schemas/` is the single description of the schema and there is no
+// migration chain (plan 013): a schema change is one edit to one file.
+// That works perfectly for a *new* table, which every install then
+// creates, and not at all for a changed one -- `IF NOT EXISTS` reaches
+// an existing table only if its shape already matches, and otherwise
+// silently no-ops.  The user's answer to that is "delete and rescan"
+// (plan 013, open question 1), which is free for everything a rescan
+// rebuilds.
+//
+// It is not free for the catalog.  explore_index is a *downloaded
+// artifact*, not something derived from the user's files, and it is the
+// largest thing this app stores.  So it went stale instead: plan 014
+// added `total_tracks` to the schema and to `indexRowFields` -- the one
+// projection every explore read uses -- and no database that already
+// existed ever grew the column.  Every Explore search, browse, artist
+// page and album page on such an install fails with
+// "no such column: total_tracks", while a fresh install is perfectly
+// healthy, which is why the tests did not see it.  The same databases
+// are stale a second way, from the same plan: their `mbid` columns are
+// still TEXT where the schema now declares BLOB, and SQLite does not
+// coerce between the two -- a comparison against 16 raw bytes simply
+// returns no rows.
+//
+// The repair is to notice and drop, not to migrate.  A dropped catalog
+// costs one artifact download (about a minute); the alternative --
+// ALTER TABLE ADD COLUMN, which would handle `total_tracks` alone
+// cheaply -- cannot express the TEXT-to-BLOB half at all, and would
+// leave those installs quietly broken while reporting success.
+//
+// Everything except `Authored` is eligible.  `Cache` is rebuildable by
+// definition; `Owned` is a projection of the user's files and a rescan
+// rebuilds it, which is plan 013's stated answer to exactly this
+// situation ("delete and rescan", open question 1); `Derived` is
+// computed from Owned.  No `Authored` table is ever dropped here --
+// that is the whole point of the datamap, and it is asserted by
+// TestAuthoredTablesAreNeverRetired rather than only stated.
+//
+// What that does *not* buy is immunity for authored rows that reference
+// a retired table.  `audio_files` is MIXED KIND: `play_count`,
+// `last_played` and `tag_status` are authored columns on an Owned
+// table, and they go with it.  Playlists survive as playlists, and
+// their entries survive pointing at nothing.  That cost was weighed and
+// accepted rather than overlooked -- the alternative is to carry the
+// authored columns across the rebuild keyed on file_path, which stays a
+// real option if this ever bites harder than it is worth.
+//
+// **This relies on foreign_keys being ON**, which applyPRAGMAs has
+// already done by the time NewDB calls it, and the dependency is not
+// cosmetic.  SQLite performs an implicit DELETE before dropping a table
+// when foreign keys are enabled, so `playlist_tracks.audio_file_id` --
+// declared ON DELETE SET NULL -- is nulled.  With foreign keys off, no
+// action fires and those rows keep the ids they had, which a rescan
+// then reissues starting from 1: every playlist would silently fill
+// with *different songs*.  Nulled entries are merely empty; stale ones
+// are wrong, and wrong quietly.  TestRetiringOwnedTablesDoesNotDangle
+// is what stops a future reordering turning one into the other.
+
+// retireGroups are tables that must be retired together.  A catalog
+// whose rows are gone must not keep the full-text index built over
+// them, nor the metadata claiming the import that produced them
+// finished -- that marker is exactly what stops the artifact being
+// fetched again.  applySchema recreates all three empty immediately
+// afterwards, and the ordinary "no index yet" path takes over.
+var retireGroups = [][]string{
+	{
+		"explore_index",
+		"explore_index_fts",
+		"explore_index_meta",
+		"explore_champion_fts",
+	},
+}
+
+// schemaColumn is one column as the schema file declares it.
+type schemaColumn struct {
+	name string
+	typ  string
+}
+
+// retireStaleTables drops every non-authored table whose live shape no
+// longer matches what sql/schemas/ declares, plus any table the schema
+// no longer describes at all, so applySchema can create the current
+// shape afresh.  It runs before applySchema and is a no-op on a new
+// database, where the tables do not exist yet.
+func retireStaleTables(
+	ctx context.Context, db *sql.DB, logger *slog.Logger,
+) error {
+	declared, err := declaredTables()
+	if err != nil {
+		return err
+	}
+
+	stale := make(map[string]string)
+
+	for table, columns := range declared {
+		entry, ok := datamap.Lookup(table)
+		if !ok || entry.Kind == datamap.Authored || entry.FTS {
+			continue
+		}
+
+		// Whether a stale Cache table may be rebuilt is decided per
+		// binary, at compile time: the app re-downloads its catalog in
+		// about a minute, cmd/indexbuild would re-derive it from ~205 GB
+		// of dumps.  See staleshape_policy.go.
+		if entry.Kind == datamap.Cache && !retireStaleCache {
+			continue
+		}
+
+		reason, err := staleReason(ctx, db, table, columns)
+		if err != nil {
+			return err
+		}
+
+		if reason != "" {
+			stale[table] = reason
+		}
+	}
+
+	obsolete, err := obsoleteTables(ctx, db)
+	if err != nil {
+		return err
+	}
+
+	maps.Copy(stale, obsolete)
+
+	if len(stale) == 0 {
+		return nil
+	}
+
+	return retireGroupsFor(ctx, db, logger, stale)
+}
+
+// obsoleteTables are live tables the schema no longer describes at all.
+// TestCatalogCoversSchema makes the datamap a complete description of
+// the current schema, so a table it does not know is one a past version
+// created and this one does not -- plan 013 alone left seven behind
+// (recordings, release_groups, artist_credit, artist_credit_artist,
+// release_group_recordings, recording_genres) plus the
+// schema_migrations table that squashing the chain retired.  They are
+// dead weight, and one of them holding a foreign key into a table being
+// rebuilt is worse than dead weight.
+//
+// SQLite's own bookkeeping and FTS shadow tables are not obsolete:
+// datamap.Lookup resolves a shadow table to its parent, and IsInternal
+// covers the rest.
+func obsoleteTables(ctx context.Context, db *sql.DB) (map[string]string, error) {
+	rows, err := db.QueryContext(
+		ctx, "SELECT name FROM sqlite_master WHERE type = 'table'",
+	)
+	if err != nil {
+		return nil, fmt.Errorf("could not list tables: %w", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	out := make(map[string]string)
+
+	for rows.Next() {
+		var name string
+
+		if err := rows.Scan(&name); err != nil {
+			return nil, fmt.Errorf("could not scan table name: %w", err)
+		}
+
+		if datamap.IsInternal(name) {
+			continue
+		}
+
+		if _, known := datamap.Lookup(name); !known {
+			out[name] = "the schema no longer describes this table"
+		}
+	}
+
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("could not read table list: %w", err)
+	}
+
+	return out, nil
+}
+
+// retireGroupsFor drops each stale table along with everything its
+// retire group says must go with it.
+func retireGroupsFor(
+	ctx context.Context, db *sql.DB, logger *slog.Logger,
+	stale map[string]string,
+) error {
+	drop := make(map[string]string)
+
+	for table, reason := range stale {
+		drop[table] = reason
+
+		for _, group := range retireGroups {
+			if !slices.Contains(group, table) {
+				continue
+			}
+
+			for _, member := range group {
+				if _, already := drop[member]; !already {
+					drop[member] = "retired with " + table
+				}
+			}
+		}
+	}
+
+	return dropDeferred(ctx, db, logger, drop)
+}
+
+// dropDeferred drops every named table in one transaction with foreign
+// key enforcement deferred to the commit.
+//
+// The deferral is required and the two obvious alternatives are both
+// wrong.  These tables reference each other -- pre-013 `audio_files`
+// has a foreign key into `recordings`, which is itself being retired --
+// so dropping them one at a time in an arbitrary order fails with
+// "FOREIGN KEY constraint failed" on whichever is unlucky enough to go
+// first, and there is no order that is safe in general.  Turning
+// foreign keys *off* for the duration would fix that and silently take
+// the ON DELETE SET NULL on `playlist_tracks.audio_file_id` with it,
+// leaving playlist entries pointing at ids a rescan reissues to
+// different songs -- the exact failure
+// TestRetiringOwnedTablesDoesNotDangle exists to prevent.
+//
+// Deferring keeps the actions firing while tolerating the inconsistency
+// in the middle, and the commit then checks that the end state is
+// sound.  It is set inside the transaction because SQLite resets it at
+// every commit.
+func dropDeferred(
+	ctx context.Context, db *sql.DB, logger *slog.Logger,
+	drop map[string]string,
+) error {
+	tx, err := db.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("could not begin the retire transaction: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	if _, err := tx.ExecContext(ctx, "PRAGMA defer_foreign_keys = ON"); err != nil {
+		return fmt.Errorf("could not defer foreign keys: %w", err)
+	}
+
+	// Sorted, so a failure is reproducible.  Map order is random, and a
+	// bug that depends on which table happens to go first reproduces on
+	// one run in three and passes review on the other two -- which is
+	// exactly how the foreign-key ordering above reached a real
+	// database.  Sorting does not make any order *safe*; the deferral
+	// does that.
+	for _, table := range slices.Sorted(maps.Keys(drop)) {
+		logger.Warn(
+			"retiring a table the schema no longer describes",
+			"table", table,
+			"reason", drop[table],
+		)
+
+		if _, err := tx.ExecContext(
+			ctx, "DROP TABLE IF EXISTS "+quoteIdent(table),
+		); err != nil {
+			return fmt.Errorf("could not retire stale table %s: %w", table, err)
+		}
+	}
+
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("could not commit the retire: %w", err)
+	}
+
+	return nil
+}
+
+// staleReason reports why a live table disagrees with its declaration,
+// or "" when it agrees.  A column the live table does not have is the
+// additive case; a column whose declared type changed is the one an
+// ALTER could not fix anyway.  Columns the live table has and the
+// schema no longer declares are ignored: they cost nothing and dropping
+// the table over one would retire a healthy catalog.
+func staleReason(
+	ctx context.Context, db *sql.DB, table string, columns []schemaColumn,
+) (string, error) {
+	live, err := liveColumns(ctx, db, table)
+	if err != nil {
+		return "", err
+	}
+
+	if len(live) == 0 {
+		// Not present at all: applySchema is about to create it.
+		return "", nil
+	}
+
+	for _, col := range columns {
+		liveType, present := live[col.name]
+		if !present {
+			return "missing column " + col.name, nil
+		}
+
+		if !sameDeclaredType(col.typ, liveType) {
+			return fmt.Sprintf(
+				"column %s is %s, schema declares %s",
+				col.name, liveType, col.typ,
+			), nil
+		}
+	}
+
+	return "", nil
+}
+
+// liveColumns returns the live table's columns and their declared types,
+// empty when the table does not exist.
+func liveColumns(
+	ctx context.Context, db *sql.DB, table string,
+) (map[string]string, error) {
+	rows, err := db.QueryContext(
+		ctx, "SELECT name, type FROM pragma_table_info(?)", table,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("could not inspect table %s: %w", table, err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	out := make(map[string]string)
+
+	for rows.Next() {
+		var name, typ string
+
+		if err := rows.Scan(&name, &typ); err != nil {
+			return nil, fmt.Errorf("could not scan column of %s: %w", table, err)
+		}
+
+		out[name] = typ
+	}
+
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("could not read columns of %s: %w", table, err)
+	}
+
+	return out, nil
+}
+
+// sameDeclaredType compares two SQLite type names.  They are compared
+// case-insensitively and only on the leading word, so INTEGER matches
+// INTEGER and VARCHAR(20) matches VARCHAR -- SQLite's affinity rules
+// make finer distinctions meaningless, and a difference that fine is
+// not worth retiring a catalog over.  An empty declared type matches
+// anything, which is what a column declared with only constraints has.
+func sameDeclaredType(declared, live string) bool {
+	d := strings.ToUpper(strings.Fields(declared + " ")[0])
+	l := strings.ToUpper(strings.Fields(live + " ")[0])
+
+	if d == "" || l == "" {
+		return true
+	}
+
+	if i := strings.IndexByte(d, '('); i >= 0 {
+		d = d[:i]
+	}
+
+	if i := strings.IndexByte(l, '('); i >= 0 {
+		l = l[:i]
+	}
+
+	return d == l
+}
+
+// declaredTables parses every CREATE TABLE in sql/schemas/ into its
+// column list.  Parsing the schema rather than writing the expectation
+// down a second time is the point: a second list is a second thing to
+// forget, which is the fault this whole file exists to repair.
+func declaredTables() (map[string][]schemaColumn, error) {
+	dirEntries, err := schemas.ReadDir("sql/schemas")
+	if err != nil {
+		return nil, fmt.Errorf("could not read schemas directory: %w", err)
+	}
+
+	out := make(map[string][]schemaColumn)
+
+	for _, dirEntry := range dirEntries {
+		if dirEntry.IsDir() {
+			continue
+		}
+
+		content, err := fs.ReadFile(schemas, path.Join("sql/schemas", dirEntry.Name()))
+		if err != nil {
+			return nil, fmt.Errorf("could not read %s: %w", dirEntry.Name(), err)
+		}
+
+		maps.Copy(out, parseCreateTables(string(content)))
+	}
+
+	return out, nil
+}
+
+// constraintKeywords begin a table constraint rather than a column.
+var constraintKeywords = map[string]bool{
+	"PRIMARY": true, "FOREIGN": true, "UNIQUE": true,
+	"CHECK": true, "CONSTRAINT": true,
+}
+
+// parseCreateTables extracts the column names and declared types of
+// every non-virtual CREATE TABLE in one schema file.
+func parseCreateTables(content string) map[string][]schemaColumn {
+	out := make(map[string][]schemaColumn)
+	rest := stripLineComments(content)
+
+	for {
+		idx := indexFold(rest, "CREATE TABLE ")
+		if idx < 0 {
+			return out
+		}
+
+		rest = rest[idx+len("CREATE TABLE "):]
+
+		head, body, ok := splitTableBody(rest)
+		if !ok {
+			return out
+		}
+
+		if name := tableName(head); name != "" {
+			out[name] = parseColumns(body)
+		}
+	}
+}
+
+// tableName pulls the table name out of the text between "CREATE TABLE"
+// and its opening parenthesis, dropping an IF NOT EXISTS and any
+// quoting.
+func tableName(head string) string {
+	head = strings.TrimSpace(head)
+	head = strings.TrimPrefix(head, "IF NOT EXISTS ")
+	head = strings.TrimPrefix(head, "if not exists ")
+
+	fields := strings.Fields(head)
+	if len(fields) == 0 {
+		return ""
+	}
+
+	return strings.Trim(fields[len(fields)-1], `"'`+"`")
+}
+
+// splitTableBody returns the text before the table's opening paren and
+// the balanced text inside it.
+func splitTableBody(s string) (head, body string, ok bool) {
+	open := strings.IndexByte(s, '(')
+	if open < 0 {
+		return "", "", false
+	}
+
+	depth := 0
+
+	for i := open; i < len(s); i++ {
+		switch s[i] {
+		case '(':
+			depth++
+		case ')':
+			depth--
+
+			if depth == 0 {
+				return s[:open], s[open+1 : i], true
+			}
+		}
+	}
+
+	return "", "", false
+}
+
+// parseColumns splits a table body on its top-level commas and keeps
+// the parts that are columns rather than table constraints.
+func parseColumns(body string) []schemaColumn {
+	var (
+		out   []schemaColumn
+		depth int
+		start int
+	)
+
+	parts := make([]string, 0, 8)
+
+	for i := range len(body) {
+		switch body[i] {
+		case '(':
+			depth++
+		case ')':
+			depth--
+		case ',':
+			if depth == 0 {
+				parts = append(parts, body[start:i])
+				start = i + 1
+			}
+		}
+	}
+
+	parts = append(parts, body[start:])
+
+	for _, part := range parts {
+		fields := strings.Fields(part)
+		if len(fields) == 0 {
+			continue
+		}
+
+		// A table constraint need not be followed by a space --
+		// "UNIQUE(mbid)" is one field, and reading it as a column name
+		// makes an entirely healthy table look stale, which retires a
+		// catalog nobody asked to lose.
+		head := fields[0]
+		if i := strings.IndexByte(head, '('); i >= 0 {
+			head = head[:i]
+		}
+
+		if constraintKeywords[strings.ToUpper(head)] {
+			continue
+		}
+
+		col := schemaColumn{name: strings.Trim(head, `"'`+"`")}
+		if len(fields) > 1 {
+			col.typ = fields[1]
+		}
+
+		out = append(out, col)
+	}
+
+	return out
+}
+
+// stripLineComments removes -- comments, which otherwise contribute
+// stray parentheses and commas to the parse.
+func stripLineComments(s string) string {
+	lines := strings.Split(s, "\n")
+	for i, line := range lines {
+		if idx := strings.Index(line, "--"); idx >= 0 {
+			lines[i] = line[:idx]
+		}
+	}
+
+	return strings.Join(lines, "\n")
+}
+
+// indexFold is a case-insensitive strings.Index.
+func indexFold(s, substr string) int {
+	return strings.Index(strings.ToUpper(s), strings.ToUpper(substr))
+}
+
+// quoteIdent quotes a table name for interpolation into DDL, which
+// cannot take a bound parameter.
+func quoteIdent(name string) string {
+	return `"` + strings.ReplaceAll(name, `"`, `""`) + `"`
+}

backend/database/staleshape_policy.go

@@ -0,0 +1,15 @@
+//go:build !indexbuild
+
+package database
+
+// retireStaleCache reports whether a Cache table whose shape no longer
+// matches the schema may be dropped and rebuilt.
+//
+// In the app: yes.  The only Cache table large enough to care about is
+// the catalog, and the app does not derive it — it downloads it.  A
+// stale one costs about a minute of re-fetching the artifact, and
+// keeping it costs every Explore read on the install, because a
+// projection naming a column the table does not have fails outright.
+//
+// In cmd/indexbuild: no, and the file next to this one says why.
+const retireStaleCache = true

backend/database/staleshape_policy_indexbuild.go

@@ -0,0 +1,37 @@
+//go:build indexbuild
+
+package database
+
+// retireStaleCache is false here, and this is the whole reason the
+// policy is a build tag rather than a rule inside retireStaleTables.
+//
+// The index database is the one place in this project where the catalog
+// is *derived* rather than downloaded.  Rebuilding it is a ~205 GB dump
+// stream over hours, resumed across runs from a checkpoint on a
+// persistent volume; that volume exists for no other purpose.  The app's
+// answer to a stale catalog — drop it, fetch the artifact again — is
+// not available here, because this database *is* what the artifact is
+// cut from.
+//
+// This was not hypothetical.  The repair shipped without it and dropped
+// the CI catalog on its first run:
+//
+//	retiring a table ... table=explore_index
+//	  reason="column entity_type is TEXT, schema declares INTEGER"
+//	index maintenance mode=build reason="no completed import yet"
+//
+// The shape mismatch was real and the drop was correct by the app's
+// rule.  It was still wrong here: that database is deliberately kept in
+// the older encoding, which is what `fix(indexexport): read an index
+// older than the binary` exists to tolerate.  A rule that is right for
+// every install and catastrophic for one database has to be told which
+// one it is in, and a build tag is how this project already tells the
+// index tools apart (backend/events/runtime_indexbuild.go,
+// backend/explore/servicestartup.go, dumpbuild_stub.go).
+//
+// cmd/indexbuild has its own repair for the half it *can* safely
+// discard: retireLibraryTables drops every table the datamap does not
+// classify as Cache, which is empty by construction in that database.
+// Between the two, the library half is repaired and the catalog is
+// never touched.
+const retireStaleCache = false

backend/database/staleshape_test.go

@@ -0,0 +1,499 @@
+package database
+
+import (
+	"context"
+	"database/sql"
+	"log/slog"
+	"path"
+	"testing"
+
+	_ "modernc.org/sqlite"
+)
+
+// testLogger discards the repair's warnings; the tests assert on the
+// database, not on the log.
+func testLogger() *slog.Logger {
+	return slog.New(slog.DiscardHandler)
+}
+
+// openRaw opens a scratch database file with no schema applied, so a
+// test can build an *old* shape and then let NewDB's repair meet it.
+func openRaw(t *testing.T, dir string) *sql.DB {
+	t.Helper()
+
+	db, err := sql.Open("sqlite", path.Join(dir, "yj.db"))
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+
+	t.Cleanup(func() { _ = db.Close() })
+
+	return db
+}
+
+// TestRetiresIndexMissingAColumn is plan 014's bug, symptom first: an
+// explore_index created before `total_tracks` existed, met by the
+// projection every explore read uses.  Before the repair this failed
+// with "no such column: total_tracks" on every install that already had
+// a catalog, while a fresh one was perfectly healthy.
+func TestRetiresIndexMissingAColumn(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	db := openRaw(t, dir)
+
+	// The pre-014 shape: the columns the projection needs, minus the
+	// one the plan added.
+	if _, err := db.ExecContext(ctx, `
+		CREATE TABLE explore_index (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			entity_type INTEGER NOT NULL,
+			mbid BLOB NOT NULL,
+			title TEXT NOT NULL,
+			artist_name TEXT NOT NULL,
+			artist_mbid BLOB NOT NULL
+		);
+		INSERT INTO explore_index (entity_type, mbid, title, artist_name, artist_mbid)
+			VALUES (1, x'00112233445566778899aabbccddeeff', 'x', 'y', x'');
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf("retire: %v", err)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	// The column the projection needs is there now.
+	var n int
+	if err := db.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM pragma_table_info('explore_index')
+		 WHERE name = 'total_tracks'`,
+	).Scan(&n); err != nil {
+		t.Fatalf("inspect: %v", err)
+	}
+
+	if n != 1 {
+		t.Fatalf("explore_index still has no total_tracks column")
+	}
+
+	// And the catalog really was retired rather than patched, so the
+	// artifact is fetched again instead of half a catalog being served.
+	if err := db.QueryRowContext(ctx,
+		"SELECT COUNT(*) FROM explore_index",
+	).Scan(&n); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+
+	if n != 0 {
+		t.Fatalf("stale rows survived the retire: %d", n)
+	}
+}
+
+// TestRetiresIndexWithTextMBIDs is the half an ALTER could not have
+// repaired: plan 013 changed mbid from TEXT to BLOB, and SQLite does not
+// coerce between them, so a query against 16 raw bytes returns no rows
+// rather than an error.
+func TestRetiresIndexWithTextMBIDs(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	db := openRaw(t, dir)
+
+	if _, err := db.ExecContext(ctx, `
+		CREATE TABLE explore_index (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			entity_type TEXT NOT NULL,
+			mbid TEXT NOT NULL,
+			title TEXT NOT NULL,
+			artist_name TEXT NOT NULL,
+			artist_mbid TEXT NOT NULL,
+			total_tracks INTEGER NOT NULL DEFAULT 0
+		);
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf("retire: %v", err)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	var typ string
+	if err := db.QueryRowContext(ctx,
+		`SELECT type FROM pragma_table_info('explore_index') WHERE name = 'mbid'`,
+	).Scan(&typ); err != nil {
+		t.Fatalf("inspect: %v", err)
+	}
+
+	if typ != "BLOB" {
+		t.Fatalf("mbid is still %s, want BLOB", typ)
+	}
+}
+
+// TestRetiringTheIndexTakesItsMetaWithIt guards the thing that makes the
+// repair actually repair: the marker saying the import finished is what
+// stops the artifact being fetched again, so a catalog dropped without
+// it would stay empty forever.
+func TestRetiringTheIndexTakesItsMetaWithIt(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	db := openRaw(t, dir)
+
+	if _, err := db.ExecContext(ctx, `
+		CREATE TABLE explore_index (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			entity_type INTEGER NOT NULL,
+			mbid BLOB NOT NULL
+		);
+		CREATE TABLE explore_index_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+		INSERT INTO explore_index_meta VALUES ('dump_import_done', '1');
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf("retire: %v", err)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	var n int
+	if err := db.QueryRowContext(ctx,
+		"SELECT COUNT(*) FROM explore_index_meta WHERE key = 'dump_import_done'",
+	).Scan(&n); err != nil {
+		t.Fatalf("meta: %v", err)
+	}
+
+	if n != 0 {
+		t.Fatalf("the import-done marker survived a retired catalog")
+	}
+}
+
+// TestHealthyDatabaseIsUntouched is the other half, and the one that
+// would make this dangerous if it failed: a current schema must survive
+// a launch with its catalog intact.  A repair that retires a healthy
+// catalog costs every user an artifact download on every start.
+func TestHealthyDatabaseIsUntouched(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	db := openRaw(t, dir)
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	if _, err := db.ExecContext(ctx, `
+		INSERT INTO explore_index (entity_type, mbid, title, artist_name, artist_mbid)
+			VALUES (1, x'00112233445566778899aabbccddeeff', 'x', 'y', x'')
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf("retire: %v", err)
+	}
+
+	var n int
+	if err := db.QueryRowContext(ctx,
+		"SELECT COUNT(*) FROM explore_index",
+	).Scan(&n); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+
+	if n != 1 {
+		t.Fatalf("a healthy catalog was retired: %d rows left", n)
+	}
+}
+
+// TestAuthoredTablesAreNeverRetired states the boundary in a test rather
+// than only in a comment: this mechanism deletes data, and the only
+// thing standing between it and a user's playlists is the Kind filter.
+func TestAuthoredTablesAreNeverRetired(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	db := openRaw(t, dir)
+
+	// A playlists table missing most of its current columns.
+	if _, err := db.ExecContext(ctx, `
+		CREATE TABLE playlists (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
+		INSERT INTO playlists (name) VALUES ('irreplaceable');
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf("retire: %v", err)
+	}
+
+	var n int
+	if err := db.QueryRowContext(ctx,
+		"SELECT COUNT(*) FROM playlists",
+	).Scan(&n); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+
+	if n != 1 {
+		t.Fatalf("an authored table was retired; rows left: %d", n)
+	}
+}
+
+// TestRetiresTablesTheSchemaNoLongerDescribes covers what plan 013 left
+// behind on every database that predates it: seven tables the schema
+// stopped describing, plus the schema_migrations table that squashing
+// the chain retired.  They are not stale in shape — they are simply not
+// ours any more.
+func TestRetiresTablesTheSchemaNoLongerDescribes(t *testing.T) {
+	ctx := context.Background()
+	db := openRaw(t, t.TempDir())
+
+	if _, err := db.ExecContext(ctx, `
+		CREATE TABLE recordings (id INTEGER PRIMARY KEY, name TEXT);
+		CREATE TABLE artist_credit (id INTEGER PRIMARY KEY, text TEXT);
+		CREATE TABLE schema_migrations (version INTEGER PRIMARY KEY);
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf("retire: %v", err)
+	}
+
+	for _, table := range []string{"recordings", "artist_credit", "schema_migrations"} {
+		var n int
+
+		if err := db.QueryRowContext(ctx,
+			"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name = ?",
+			table,
+		).Scan(&n); err != nil {
+			t.Fatalf("inspect %s: %v", table, err)
+		}
+
+		if n != 0 {
+			t.Errorf("%s survived; the schema no longer describes it", table)
+		}
+	}
+}
+
+// TestFTSShadowTablesAreNotObsolete is the sweep's sharp edge: an FTS5
+// virtual table is backed by four shadow tables that appear in
+// sqlite_master under their own names and are in no schema file.
+// Dropping one destroys the index it belongs to.
+func TestFTSShadowTablesAreNotObsolete(t *testing.T) {
+	ctx := context.Background()
+	db := openRaw(t, t.TempDir())
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	obsolete, err := obsoleteTables(ctx, db)
+	if err != nil {
+		t.Fatalf("obsoleteTables: %v", err)
+	}
+
+	if len(obsolete) != 0 {
+		t.Fatalf("a freshly created schema reported obsolete tables: %v", obsolete)
+	}
+}
+
+// TestRetiringOwnedTablesDoesNotDangle pins the one behaviour that is
+// silently wrong rather than loudly broken.
+//
+// Retiring audio_files leaves playlist entries behind.  With
+// foreign_keys ON — which applyPRAGMAs has done before NewDB gets here —
+// SET NULL fires and they point at nothing.  With it OFF they keep ids
+// that the rescan reissues from 1, so every playlist quietly fills with
+// different songs.  Nothing about the schema makes that ordering
+// obvious, so it is asserted rather than assumed.
+func TestRetiringOwnedTablesDoesNotDangle(t *testing.T) {
+	ctx := context.Background()
+	db := openRaw(t, t.TempDir())
+
+	if _, err := db.ExecContext(ctx, "PRAGMA foreign_keys = ON"); err != nil {
+		t.Fatalf("pragma: %v", err)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	// Break audio_files' shape so it is retired, keeping a playlist
+	// entry that references it.
+	if _, err := db.ExecContext(ctx, `
+		INSERT INTO playlists (id, name) VALUES (1, 'keepme');
+		INSERT INTO libraries (id, name, path) VALUES (0, 'test', '/music');
+		INSERT INTO audio_files (id, file_path, file_type_id, length_milliseconds)
+			VALUES (7, '/music/a.flac', 1, 1000);
+		INSERT INTO playlist_tracks (playlist_id, audio_file_id, position)
+			VALUES (1, 7, 0);
+		DROP VIEW IF EXISTS track_metadata;
+		ALTER TABLE audio_files DROP COLUMN artist_credit;
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf("retire: %v", err)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	var dangling int
+	if err := db.QueryRowContext(ctx,
+		"SELECT COUNT(*) FROM playlist_tracks WHERE audio_file_id IS NOT NULL",
+	).Scan(&dangling); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+
+	if dangling != 0 {
+		t.Fatalf(
+			"%d playlist entries still point at retired audio_files ids; "+
+				"a rescan will reissue those ids to different tracks",
+			dangling,
+		)
+	}
+
+	// The playlist itself is authored and must be untouched.
+	var playlists int
+	if err := db.QueryRowContext(ctx,
+		"SELECT COUNT(*) FROM playlists",
+	).Scan(&playlists); err != nil {
+		t.Fatalf("playlists: %v", err)
+	}
+
+	if playlists != 1 {
+		t.Fatalf("authored playlist lost: %d", playlists)
+	}
+}
+
+// TestRetiringInterlinkedLegacyTables is the bug the unit tests missed
+// and a real database found.
+//
+// The tables plan 013 retired reference each other -- pre-013
+// audio_files has a foreign key into recordings -- so with foreign keys
+// ON, dropping them one at a time fails with "FOREIGN KEY constraint
+// failed" on whichever goes first, and map iteration order decides
+// which that is.  Every other test in this file ran with foreign keys
+// off and passed happily; the app enables them in applyPRAGMAs before
+// the repair runs, so only the real launch path showed it.
+func TestRetiringInterlinkedLegacyTables(t *testing.T) {
+	ctx := context.Background()
+	db := openRaw(t, t.TempDir())
+
+	if _, err := db.ExecContext(ctx, "PRAGMA foreign_keys = ON"); err != nil {
+		t.Fatalf("pragma: %v", err)
+	}
+
+	// The pre-013 shape, with the reference that makes ordering matter.
+	// release_group_recordings sorts *after* recordings and references
+	// it, so the deterministic order retires the parent while the child
+	// still holds rows pointing at it -- which is the case that fails
+	// without the deferral, rather than one that fails on some runs.
+	if _, err := db.ExecContext(ctx, `
+		CREATE TABLE recordings (id INTEGER PRIMARY KEY, name TEXT);
+		CREATE TABLE artist_credit (id INTEGER PRIMARY KEY, text TEXT);
+		CREATE TABLE release_group_recordings (
+			id           INTEGER PRIMARY KEY,
+			recording_id INTEGER NOT NULL,
+			FOREIGN KEY(recording_id) REFERENCES recordings(id)
+		);
+		CREATE TABLE audio_files (
+			id           INTEGER PRIMARY KEY,
+			file_path    TEXT NOT NULL UNIQUE,
+			recording_id INTEGER,
+			FOREIGN KEY(recording_id) REFERENCES recordings(id)
+		);
+		INSERT INTO recordings (id, name) VALUES (1, 'x');
+		INSERT INTO release_group_recordings (id, recording_id) VALUES (1, 1);
+		INSERT INTO audio_files (id, file_path, recording_id)
+			VALUES (1, '/music/a.flac', 1);
+	`); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+
+	if err := retireStaleTables(ctx, db, testLogger()); err != nil {
+		t.Fatalf("retire: %v", err)
+	}
+
+	if err := applySchema(ctx, db); err != nil {
+		t.Fatalf("applySchema: %v", err)
+	}
+
+	for _, table := range []string{"recordings", "artist_credit"} {
+		var n int
+
+		if err := db.QueryRowContext(ctx,
+			"SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name = ?",
+			table,
+		).Scan(&n); err != nil {
+			t.Fatalf("inspect %s: %v", table, err)
+		}
+
+		if n != 0 {
+			t.Errorf("%s survived the retire", table)
+		}
+	}
+
+	// And the rebuilt audio_files is the current shape, which is the
+	// whole reason the old one had to go.
+	var n int
+	if err := db.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM pragma_table_info('audio_files')
+		 WHERE name = 'artist_credit'`,
+	).Scan(&n); err != nil {
+		t.Fatalf("inspect audio_files: %v", err)
+	}
+
+	if n != 1 {
+		t.Fatal("audio_files was not rebuilt in the current shape")
+	}
+}
+
+// TestParseCreateTablesReadsTheRealSchema keeps the parser honest
+// against the files it actually runs on: a parser that silently found
+// no columns would report every table healthy and repair nothing.
+func TestParseCreateTablesReadsTheRealSchema(t *testing.T) {
+	declared, err := declaredTables()
+	if err != nil {
+		t.Fatalf("declaredTables: %v", err)
+	}
+
+	cols, ok := declared["explore_index"]
+	if !ok {
+		t.Fatal("explore_index was not parsed out of the schema files")
+	}
+
+	want := map[string]string{
+		"mbid":         "BLOB",
+		"total_tracks": "INTEGER",
+		"artist_name":  "TEXT",
+	}
+
+	got := make(map[string]string, len(cols))
+	for _, c := range cols {
+		got[c.name] = c.typ
+	}
+
+	for name, typ := range want {
+		if got[name] != typ {
+			t.Errorf("explore_index.%s parsed as %q, want %q", name, got[name], typ)
+		}
+	}
+
+	// A table constraint must not be mistaken for a column.
+	for _, c := range cols {
+		switch c.name {
+		case "PRIMARY", "FOREIGN", "UNIQUE", "CHECK", "CONSTRAINT":
+			t.Errorf("parsed table constraint %q as a column", c.name)
+		}
+	}
+}

backend/datamap/datamap.go

@@ -185,6 +185,21 @@ var tables = []Table{
 		Note: "Full-text index over the champion entities of the " +
 			"MusicBrainz dump. Rebuilt only by a full index build.",
 	},
+	{
+		Name: "artist_credit_part", Kind: Cache, Lifetime: Retained,
+		Note: "The decomposition of a multi-artist credit, from the " +
+			"MusicBrainz dump: one row per credited artist, with the " +
+			"name as credited and the join phrase that follows it. " +
+			"Arrives with the downloaded artifact, so rebuilding it " +
+			"costs a dump stream and it is never swept.",
+	},
+	{
+		Name: "artist_credit_ref", Kind: Cache, Lifetime: Retained,
+		Note: "Which credit a catalog recording or release group is " +
+			"credited to. Present only for multi-artist credits; " +
+			"absence means one artist, which explore_index already " +
+			"describes. Ships and dies with artist_credit_part.",
+	},
 	{
 		Name: "explore_index", Kind: Cache, Lifetime: Retained,
 		Note: "The offline MusicBrainz search index. Rebuilding costs a " +

backend/download/config.go

@@ -34,13 +34,29 @@ type UserConfig struct {
 	// in one burst that every provider sees as a flood.
 	WantedBatch int `toml:"WantedBatch"`
 
-	// MinFileSizeMB, MaxFileSizeMB and PreferredFileSizeMB bound and
-	// nudge what auto-pick (interactive or via the request list) may
-	// grab without asking.  Zero on any of them is permissive: see
-	// AutoDownloadPrefs.
-	MinFileSizeMB       int `toml:"MinFileSizeMB"`
-	MaxFileSizeMB       int `toml:"MaxFileSizeMB"`
-	PreferredFileSizeMB int `toml:"PreferredFileSizeMB"`
+	// MinKbps, MaxKbps and PreferredKbps bound and nudge what auto-pick
+	// (interactive or via the request list) may grab without asking.
+	// Zero on any of them is permissive: see AutoDownloadPrefs.
+	//
+	// They replaced MinFileSizeMB / MaxFileSizeMB /
+	// PreferredFileSizeMB, which were megabytes and so said nothing
+	// without knowing how long the release was.  The old keys are
+	// 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", ...).
@@ -56,10 +72,11 @@ func (c *UserConfig) AutoDownloadPrefs() AutoDownloadPrefs {
 	}
 
 	return AutoDownloadPrefs{
-		MinSizeMB:       c.MinFileSizeMB,
-		MaxSizeMB:       c.MaxFileSizeMB,
-		PreferredSizeMB: c.PreferredFileSizeMB,
-		AllowedFormats:  formats,
+		MinKbps:        c.MinKbps,
+		MaxKbps:        c.MaxKbps,
+		PreferredKbps:  c.PreferredKbps,
+		MaxSizeMB:      c.MaxFileSizeMB,
+		AllowedFormats: formats,
 	}
 }
 

backend/download/manager.go

@@ -236,6 +236,12 @@ 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.
 //
@@ -612,16 +618,8 @@ func (m *Manager) Attempt(
 		return false, "", err
 	}
 
-	if !m.AutoPickable(dl, ranked) {
-		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 veto := m.AutoPickVeto(dl, ranked); veto != "" {
+		return false, veto, nil
 	}
 
 	if err := m.store.CreateDownload(ctx, dl); err != nil {

backend/download/manager_test.go

@@ -199,28 +199,36 @@ func TestManagerEndToEndAutoPick(t *testing.T) {
 		t.Errorf("expected imported file at %s: %v", want, err)
 	}
 
-	// Staging was released only after a successful import.
-	entries, err := os.ReadDir(f.staging.Root())
-	if err != nil {
-		t.Fatalf("read staging root: %v", err)
-	}
+	// Staging release and the rescan happen *after* the state is
+	// recorded (manager.go sets StateComplete, then releases, then
+	// scans), so waiting on the state is not waiting on these.  Under
+	// load the worker is descheduled in between and asserting straight
+	// away reads the world one step too early -- which is exactly how
+	// this test failed on a busy machine while passing alone.
+	waitFor(t, func() bool {
+		entries, err := os.ReadDir(f.staging.Root())
+		if err != nil || len(entries) != 0 {
+			return false
+		}
 
-	if len(entries) != 0 {
-		t.Errorf("staging not released: %d dirs remain", len(entries))
-	}
+		f.lib.mu.Lock()
+		defer f.lib.mu.Unlock()
 
-	// The library was told to rescan.
-	f.lib.mu.Lock()
-	scanned := len(f.lib.scanned)
-	f.lib.mu.Unlock()
-
-	if scanned != 1 {
-		t.Errorf("library scans = %d, want 1", scanned)
-	}
+		return len(f.lib.scanned) == 1
+	}, "staging was never released, or the library was never rescanned")
 }
 
-// An ambiguous result set must park for the user rather than guess.
-func TestManagerWaitsWhenAmbiguous(t *testing.T) {
+// Two equally good copies are not an ambiguity — they are a spare.
+//
+// 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)
@@ -238,11 +246,41 @@ func TestManagerWaitsWhenAmbiguous(t *testing.T) {
 		t.Fatalf("Start: %v", err)
 	}
 
-	if f.manager.AutoPickable(dl, ranked) {
-		t.Fatal("two equivalent candidates must not auto-pick")
+	if veto := f.manager.AutoPickVeto(dl, ranked); veto != "" {
+		t.Fatalf("two equally good copies must auto-pick, got veto: %s", veto)
+	}
+
+	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",
@@ -259,7 +297,6 @@ func TestManagerWaitsWhenAmbiguous(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 {

backend/download/rank.go

@@ -1,6 +1,7 @@
 package download
 
 import (
+	"fmt"
 	"math"
 	"sort"
 	"strings"
@@ -34,38 +35,102 @@ const (
 	weightArtistFit    = 0.12
 )
 
-// Quality sub-weights.  They sum to 1.0 along with weightSizeFit below.
+// Quality sub-weights.  Each set sums to 1.0.
+//
+// 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
-	weightBitrate  = 0.23
-	weightHealth   = 0.20
-	weightPriority = 0.10
-	weightSizeFit  = 0.05
+	weightFormat     = 0.42
+	weightBitrate    = 0.23
+	weightHealth     = 0.20
+	weightPriority   = 0.10
+	weightBitrateFit = 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 size window and no
-// format restriction.
+// without asking.  Zero values are permissive: no bitrate window, no
+// size ceiling and no 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 {
-	// MinSizeMB and MaxSizeMB bound what auto-pick will grab.  Zero
-	// means no bound on that side.  A candidate outside the window is
-	// filtered out of auto-pick entirely, not merely scored down — a
-	// tiny "sampler" torrent or a boxset ten times the expected size is
-	// usually the wrong thing entirely, not a worse copy of the right
-	// thing.
-	MinSizeMB int `json:"minSizeMb"`
-	MaxSizeMB int `json:"maxSizeMb"`
+	// MinKbps and MaxKbps bound the average bitrate auto-pick will
+	// grab.  Zero means no bound on that side.  A candidate outside the
+	// window is filtered out of auto-pick entirely, not merely scored
+	// down — a 96 kbps rip of the right album is not a worse copy the
+	// user might accept, it is one they said not to take unattended.
+	//
+	// For reference: 320 is the top of MP3, ~500–1000 is FLAC depending
+	// on the material, and anything under ~128 is a transcode.
+	MinKbps int `json:"minKbps"`
+	MaxKbps int `json:"maxKbps"`
 
-	// 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"`
+	// 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"`
 
 	// AllowedFormats restricts auto-pick to candidates whose audio
 	// files are all in one of these formats.  Empty means no
@@ -74,19 +139,33 @@ type AutoDownloadPrefs struct {
 }
 
 // eligible reports whether a candidate may be auto-picked under these
-// preferences: within the size window (when set) and, when a format
-// list is given, every audio file in an allowed format.
-func (p AutoDownloadPrefs) eligible(c Candidate) bool {
+// preferences: inside the bitrate window and the size ceiling (when
+// set) and, when a format list is given, every audio file in an
+// allowed format.
+//
+// `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.MinSizeMB > 0 && c.TotalSize < int64(p.MinSizeMB)*bytesPerMB {
-		return false
-	}
-
 	if p.MaxSizeMB > 0 && c.TotalSize > int64(p.MaxSizeMB)*bytesPerMB {
 		return false
 	}
 
+	if kbps := candidateKbps(c, runtimeMillis); kbps > 0 {
+		if p.MinKbps > 0 && kbps < float64(p.MinKbps) {
+			return false
+		}
+
+		if p.MaxKbps > 0 && kbps > float64(p.MaxKbps) {
+			return false
+		}
+	}
+
 	if len(p.AllowedFormats) == 0 {
 		return true
 	}
@@ -107,11 +186,14 @@ func (p AutoDownloadPrefs) eligible(c Candidate) bool {
 
 // filter returns only the candidates these preferences allow to be
 // auto-picked, in the same (already ranked) order.
-func (p AutoDownloadPrefs) filter(ranked []Candidate) []Candidate {
+func (p AutoDownloadPrefs) filter(
+	ranked []Candidate,
+	runtimeMillis int64,
+) []Candidate {
 	out := make([]Candidate, 0, len(ranked))
 
 	for _, c := range ranked {
-		if p.eligible(c) {
+		if p.eligible(c, runtimeMillis) {
 			out = append(out, c)
 		}
 	}
@@ -119,32 +201,116 @@ func (p AutoDownloadPrefs) filter(ranked []Candidate) []Candidate {
 	return out
 }
 
-// sizeFit scores how close totalSize is to PreferredSizeMB, 0..1,
-// falling off linearly as the size doubles or halves away from it.
-// Returns a neutral 0.5 when no preference is set, so the absence of a
-// preference does not bias ranking.
-func (p AutoDownloadPrefs) sizeFit(totalSize int64) float64 {
+// bitrateFit scores how close a candidate's average bitrate is to
+// PreferredKbps, falling off linearly as it doubles or halves away
+// from it.
+//
+// The range is **0.5 to 1.0, not 0 to 1**, and the floor is the point.
+// 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 (
-		bytesPerMB = 1 << 20
-		neutral    = 0.5
+		neutral = 0.5
+		span    = 0.5
 	)
 
-	if p.PreferredSizeMB <= 0 || totalSize <= 0 {
+	if p.PreferredKbps <= 0 {
 		return neutral
 	}
 
-	preferred := float64(p.PreferredSizeMB) * bytesPerMB
-	ratio := float64(totalSize) / preferred
+	kbps := candidateKbps(c, runtimeMillis)
+	if kbps <= 0 {
+		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 size.  Falls to 0 at 2x away and beyond.
-	fit := 1 - (ratio - 1)
+	// the preferred rate, where the closeness term reaches 0.
+	return neutral + span*clamp01(1-(ratio-1))
+}
 
-	return clamp01(fit)
+// candidateKbps is a candidate's average audio bitrate, or 0 when it
+// 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.
@@ -160,7 +326,9 @@ 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, audio, priority, prefs)
+	c.Quality = scoreQuality(
+		c, audio, priority, prefs, dl.runtimeMillis(),
+	)
 
 	c.Score = weightMatch*c.Match.Overall + weightQuality*c.Quality.Overall
 
@@ -279,11 +447,12 @@ func scoreQuality(
 	audio []CandidateFile,
 	priority int,
 	prefs AutoDownloadPrefs,
+	runtimeMillis int64,
 ) QualityScore {
 	q := QualityScore{
-		Health:   clamp01(c.Health),
-		Priority: clamp01(float64(priority) / 100.0),
-		SizeFit:  prefs.sizeFit(c.TotalSize),
+		Health:     clamp01(c.Health),
+		Priority:   clamp01(float64(priority) / 100.0),
+		BitrateFit: prefs.bitrateFit(c, runtimeMillis),
 	}
 
 	if len(audio) == 0 {
@@ -310,11 +479,13 @@ func scoreQuality(
 	q.FormatRank = worst
 	q.Bitrate = bitrateScore(audio)
 
-	q.Overall = weightFormat*q.FormatRank +
-		weightBitrate*q.Bitrate +
-		weightHealth*q.Health +
-		weightPriority*q.Priority +
-		weightSizeFit*q.SizeFit
+	wFormat, wBitrate, wHealth, wPriority, wFit := qualityWeights(prefs)
+
+	q.Overall = wFormat*q.FormatRank +
+		wBitrate*q.Bitrate +
+		wHealth*q.Health +
+		wPriority*q.Priority +
+		wFit*q.BitrateFit
 
 	if q.Mixed {
 		q.Overall *= 0.9
@@ -444,6 +615,19 @@ 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
 		}
@@ -454,19 +638,58 @@ func Rank(
 	return out
 }
 
-// AutoPickable reports whether a ranked list has a clear enough winner
-// to grab without asking.  It demands an anchored request, a high match,
-// decent quality, and daylight between first and second place — if two
-// candidates are close, the choice is the user's.
-func AutoPickable(dl Download, ranked []Candidate, prefs AutoDownloadPrefs) bool {
-	const (
-		minMatch   = 0.85
-		minQuality = 0.5
-		minLead    = 0.08
-	)
+// Auto-pick gates.  Named rather than inlined because AutoPickVeto
+// reports which of them refused, and a number in a sentence the user
+// reads should be the same number the decision used.
+const (
+	minMatch   = 0.85
+	minQuality = 0.5
+)
 
-	if !dl.Anchored() || len(ranked) == 0 {
-		return false
+// 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) == ""
+}
+
+// AutoPickVeto returns the reason auto-pick declined, or "" when it
+// would go ahead.
+//
+// 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:
@@ -474,29 +697,42 @@ func AutoPickable(dl Download, ranked []Candidate, prefs AutoDownloadPrefs) bool
 	// 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 false
+		return "no tracklist for this release is known yet, so a candidate cannot be checked against it"
 	}
 
-	// The guardrails apply before the match/quality/lead checks: a
-	// candidate outside the allowed size or format is not a worse
-	// choice, it is not a choice auto-pick may make at all, so it must
-	// not count as "the winner" nor as "second place" for the lead
-	// check below.
-	eligible := prefs.filter(ranked)
+	// The guardrails apply before the match and quality checks: a
+	// candidate outside the allowed bitrate, size or format is not a
+	// worse choice, it is not a choice auto-pick may make at all, so it
+	// must not count as "the winner" either.
+	eligible := prefs.filter(ranked, dl.runtimeMillis())
 	if len(eligible) == 0 {
-		return false
+		return fmt.Sprintf(
+			"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 {
-		return false
+
+	if best.Match.Overall < minMatch {
+		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 len(eligible) > 1 && best.Score-eligible[1].Score < minLead {
-		return false
+	if best.Quality.Overall < minQuality {
+		return fmt.Sprintf(
+			"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 true
+	return ""
 }
 
 // mergeMatched copies MatchedTo assignments from the audio-only slice

backend/download/rank_test.go

@@ -1,6 +1,34 @@
 package download
 
-import "testing"
+import (
+	"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 {
@@ -8,11 +36,15 @@ 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"},
-			{Position: 2, Title: "Paranoid Android"},
-			{Position: 3, Title: "Subterranean Homesick Alien"},
-			{Position: 4, Title: "Exit Music (For a Film)"},
+			{Position: 1, Title: "Airbag", LengthMillis: trackMillis},
+			{Position: 2, Title: "Paranoid Android", LengthMillis: trackMillis},
+			{Position: 3, Title: "Subterranean Homesick Alien", LengthMillis: trackMillis},
+			{Position: 4, Title: "Exit Music (For a Film)", LengthMillis: trackMillis},
 		},
 	}
 }
@@ -187,7 +219,7 @@ func TestUnanchoredMatchIsCapped(t *testing.T) {
 	}
 }
 
-func TestAutoPickableRequiresAnchorAndLead(t *testing.T) {
+func TestAutoPickableRequiresAnchorAndTracklist(t *testing.T) {
 	t.Parallel()
 
 	dl := okComputer()
@@ -211,14 +243,18 @@ func TestAutoPickableRequiresAnchorAndLead(t *testing.T) {
 		}
 	})
 
-	t.Run("two close candidates are not", func(t *testing.T) {
+	// Two identical copies are a spare, not an ambiguity. This
+	// 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{}) {
-			t.Error("identical candidates must not auto-pick")
+		if !AutoPickable(dl, []Candidate{best, twin}, AutoDownloadPrefs{}) {
+			t.Error("identical good candidates must auto-pick")
 		}
 	})
 
@@ -300,18 +336,11 @@ func TestProviderPriorityBreaksTies(t *testing.T) {
 	}
 }
 
-const mb = 1 << 20
-
 func TestAutoDownloadPrefsEligible(t *testing.T) {
 	t.Parallel()
 
-	flacCandidate := candidateFor("c", allTitles(), ".flac", 30_000_000)
-	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
+	flacCandidate := kbpsCandidate("c", ".flac", 900)
+	mp3Candidate := kbpsCandidate("c", ".mp3", 128)
 
 	tests := []struct {
 		name  string
@@ -321,18 +350,25 @@ func TestAutoDownloadPrefsEligible(t *testing.T) {
 	}{
 		{"zero value is permissive", AutoDownloadPrefs{}, flacCandidate, true},
 		{
-			"within min/max window",
-			AutoDownloadPrefs{MinSizeMB: 100, MaxSizeMB: 500},
+			"within the bitrate window",
+			AutoDownloadPrefs{MinKbps: 320, MaxKbps: 1200},
 			flacCandidate, true,
 		},
 		{
-			"below minimum",
-			AutoDownloadPrefs{MinSizeMB: 400},
+			"below the minimum bitrate",
+			AutoDownloadPrefs{MinKbps: 500},
+			mp3Candidate, false,
+		},
+		{
+			"above the maximum bitrate",
+			AutoDownloadPrefs{MaxKbps: 500},
 			flacCandidate, false,
 		},
 		{
-			"above maximum",
-			AutoDownloadPrefs{MaxSizeMB: 200},
+			// The ceiling is bytes, not a rate, and it is the guard
+			// that still works when the bitrate cannot be worked out.
+			"above the hard size ceiling",
+			AutoDownloadPrefs{MaxSizeMB: 50},
 			flacCandidate, false,
 		},
 		{
@@ -351,57 +387,131 @@ func TestAutoDownloadPrefsEligible(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			if got := tt.prefs.eligible(tt.c); got != tt.want {
+			got := tt.prefs.eligible(tt.c, okComputerRuntime)
+			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()
 
-	small := candidateFor("small", allTitles(), ".flac", 10_000_000)
-	small.TotalSize = 50 * mb
+	lossy := kbpsCandidate("lossy", ".mp3", 128)
+	lossless := kbpsCandidate("lossless", ".flac", 900)
 
-	big := candidateFor("big", allTitles(), ".flac", 30_000_000)
-	big.TotalSize = 500 * mb
+	prefs := AutoDownloadPrefs{MinKbps: 500}
 
-	prefs := AutoDownloadPrefs{MinSizeMB: 100, MaxSizeMB: 600}
+	filtered := prefs.filter(
+		[]Candidate{lossy, lossless}, okComputerRuntime,
+	)
 
-	filtered := prefs.filter([]Candidate{small, big})
-
-	if len(filtered) != 1 || filtered[0].ID != "big" {
+	if len(filtered) != 1 || filtered[0].ID != "lossless" {
 		t.Errorf("filter() = %v, want only the in-window candidate", filtered)
 	}
 }
 
-func TestAutoDownloadPrefsSizeFit(t *testing.T) {
+func TestAutoDownloadPrefsBitrateFit(t *testing.T) {
 	t.Parallel()
 
 	const neutral = 0.5
 
 	tests := []struct {
-		name      string
-		prefs     AutoDownloadPrefs
-		totalSize int64
-		want      float64
+		name  string
+		prefs AutoDownloadPrefs
+		c     Candidate
+		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{PreferredSizeMB: 300},
-			300 * mb, 1.0,
+			AutoDownloadPrefs{PreferredKbps: 320},
+			kbpsCandidate("c", ".mp3", 320), 1.0,
 		},
 		{
-			"double the preferred size scores 0",
-			AutoDownloadPrefs{PreferredSizeMB: 300},
-			600 * mb, 0.0,
+			// The floor is neutral, not zero: this term carries 0.40
+			// of the quality score once a preference is set, and a
+			// span to zero would let "I like 320" quietly disqualify
+			// 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 size scores 0",
-			AutoDownloadPrefs{PreferredSizeMB: 300},
-			150 * mb, 0.0,
+			"half the preferred rate falls to the neutral floor",
+			AutoDownloadPrefs{PreferredKbps: 320},
+			kbpsCandidate("c", ".mp3", 160), neutral,
+		},
+		{
+			"an unknowable rate is neutral",
+			AutoDownloadPrefs{PreferredKbps: 320},
+			kbpsCandidate("c", ".mp3", 320), neutral,
 		},
 	}
 
@@ -409,30 +519,223 @@ func TestAutoDownloadPrefsSizeFit(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			if got := tt.prefs.sizeFit(tt.totalSize); got != tt.want {
-				t.Errorf("sizeFit(%d) = %f, want %f", tt.totalSize, got, tt.want)
+			// The last case deliberately withholds the runtime.
+			runtime := int64(okComputerRuntime)
+			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 size guard: the guardrail applies before the
-// match/quality/lead checks, not as one more input averaged into them.
-func TestAutoPickableRejectsCandidateOutsideSizeGuard(t *testing.T) {
+// outside the configured guardrails: they apply before the match and
+// quality checks, not as one more input averaged into them.
+func TestAutoPickableRejectsCandidateOutsideTheGuardrails(t *testing.T) {
 	t.Parallel()
 
 	dl := okComputer()
-	best := Score(dl, candidateFor("a", allTitles(), ".flac", 30_000_000), 50, AutoDownloadPrefs{})
-	best.TotalSize = 500 * mb
+	best := Score(dl, kbpsCandidate("a", ".flac", 900), 50, AutoDownloadPrefs{})
 
 	if !AutoPickable(dl, []Candidate{best}, AutoDownloadPrefs{}) {
 		t.Fatal("expected this candidate to be auto-pickable with no guardrails")
 	}
 
-	tight := AutoDownloadPrefs{MinSizeMB: 10, MaxSizeMB: 100}
+	if AutoPickable(dl, []Candidate{best}, AutoDownloadPrefs{MaxKbps: 320}) {
+		t.Error("candidate above the bitrate window must not auto-pick")
+	}
 
-	if AutoPickable(dl, []Candidate{best}, tight) {
-		t.Error("candidate outside the size guard must not auto-pick")
+	if AutoPickable(dl, []Candidate{best}, AutoDownloadPrefs{MaxSizeMB: 1}) {
+		t.Error("candidate above the size ceiling 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)
 	}
 }

backend/download/service_test.go

@@ -20,6 +20,41 @@ 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}
 }
 
@@ -158,6 +193,11 @@ 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)
 

backend/download/types.go

@@ -302,7 +302,12 @@ type QualityScore struct {
 	Bitrate    float64 `json:"bitrate"`
 	Health     float64 `json:"health"`   // seeders, free slots
 	Priority   float64 `json:"priority"` // user's per-provider preference
-	SizeFit    float64 `json:"sizeFit"`  // closeness to the preferred download size
+	// BitrateFit is closeness to the preferred *rate*, which is what
+	// 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.

backend/events/emit.go

@@ -4,8 +4,6 @@ import (
 	"context"
 	"errors"
 	"log/slog"
-
-	"github.com/wailsapp/wails/v3/pkg/application"
 )
 
 // ErrNoRuntime is returned by Deliver when there is neither a test Sink
@@ -82,16 +80,7 @@ func Deliver(ctx context.Context, name string, data ...any) error {
 		}
 	}
 
-	// application.Get() returns nil when no app is running — under test,
-	// before Run, and after shutdown.  It does not terminate the
-	// process, which is what the v2 probe of the private "events"
-	// context key existed to avoid.
-	app := application.Get()
-	if app == nil {
-		return ErrNoRuntime
-	}
-
-	app.Event.Emit(name, data...)
-
-	return nil
+	// emitRuntime is the only place the Wails application is touched,
+	// and it is behind a build tag: see runtime_wails.go.
+	return emitRuntime(name, data...)
 }

backend/events/noemit_test.go

@@ -8,9 +8,12 @@ import (
 )
 
 // allowedEmitters are the only files permitted to call the Wails
-// runtime's event emitter directly.
+// runtime's event emitter directly.  There is one call and it lives in
+// runtime_wails.go rather than emit.go because naming the application
+// package is what forces cgo, and cmd/indexbuild builds this package
+// without it.
 var allowedEmitters = map[string]bool{
-	filepath.Join("backend", "events", "emit.go"): true,
+	filepath.Join("backend", "events", "runtime_wails.go"): true,
 }
 
 // TestNoDirectRuntimeEmits fails if anything outside backend/events

backend/events/runtime_indexbuild.go

@@ -0,0 +1,18 @@
+//go:build indexbuild
+
+package events
+
+// emitRuntime is the index tools' half of the split described in
+// runtime_wails.go: under the indexbuild tag there is no Wails
+// application to emit through, and importing the one that would be
+// there costs cgo and a GTK/WebKit toolchain the index build container
+// deliberately does not have.
+//
+// Returning ErrNoRuntime is the same answer the app gives before Run
+// and after shutdown, so Emit's callers need no second code path: an
+// event emitted by cmd/indexbuild is logged and dropped.  A test that
+// wants to observe one installs a Sink with WithSink, which Deliver
+// consults first and which works under either tag.
+func emitRuntime(_ string, _ ...any) error {
+	return ErrNoRuntime
+}

backend/events/runtime_wails.go

@@ -0,0 +1,32 @@
+//go:build !indexbuild
+
+package events
+
+import (
+	"github.com/wailsapp/wails/v3/pkg/application"
+)
+
+// emitRuntime pushes an event through the running Wails application.
+//
+// It is the app's half of a two-file split, and the split exists for a
+// build constraint rather than a design one: v3's application package
+// is cgo on Linux, so anything importing it needs GTK and WebKit
+// headers to compile.  cmd/indexbuild and cmd/indexexport reach this
+// package through backend/explore and are built in a plain golang
+// container with CGO_ENABLED=0 (.gitea/workflows/index-artifact.yml),
+// where that is not available and not wanted.  See
+// runtime_indexbuild.go for the other half.
+func emitRuntime(name string, data ...any) error {
+	// application.Get() returns nil when no app is running — under
+	// test, before Run, and after shutdown.  It does not terminate the
+	// process, which is what the v2 probe of the private "events"
+	// context key existed to avoid.
+	app := application.Get()
+	if app == nil {
+		return ErrNoRuntime
+	}
+
+	app.Event.Emit(name, data...)
+
+	return nil
+}

backend/explore/artifactbuild.go

@@ -27,6 +27,20 @@ var artifactStageNames = [...]string{
 // failure path is non-fatal by design: the caller falls back, and a
 // fresh install with no network still gets its own library in Explore.
 func (si *SearchIndex) tryCoreArtifact(ctx context.Context) error {
+	// Before anything is staged: ~0.6 GB is not a download to start on
+	// someone's cellular allowance without being asked (plan 016 B4).
+	// This is checked first so no job appears and no status changes --
+	// declining is a no-op, not a failure the user has to dismiss.
+	if si.netPolicy.refuses() {
+		si.logIndexJob(
+			jobs.LevelInfo,
+			"Skipping the catalog download on a metered connection. "+
+				"Enable it in Settings to download anyway.",
+		)
+
+		return ErrMeteredNetwork
+	}
+
 	si.mu.Lock()
 	si.buildStatus = IndexStatus{
 		Building: true,

backend/explore/artifactimport.go

@@ -283,6 +283,9 @@ func (si *SearchIndex) importCoreArtifact(ctx context.Context, path string) erro
 	}
 
 	merged, mergeErr := si.mergeArtifactRows(ctx, info.rows)
+	if mergeErr == nil {
+		si.mergeArtifactCredits(ctx)
+	}
 
 	if ftsSuspended {
 		start := time.Now()
@@ -473,3 +476,75 @@ func (si *SearchIndex) removeArtifactFile(path string) {
 		si.logger.Warn("core artifact: cleanup failed", "path", path, "error", err)
 	}
 }
+
+// artifactHasCredits reports whether the attached artifact carries the
+// multi-artist credit tables.
+//
+// The same shape, and the same handle, as artifactHasTotals above: an
+// artifact published before credits existed is still a perfectly good
+// catalog, and there is one already out there.  Selecting from a table
+// that is not in it would fail an import that should have succeeded, so
+// it is asked rather than assumed -- on the *writer*, because `core` is
+// attached to that one connection and the read pool cannot see it.
+func (si *SearchIndex) artifactHasCredits() bool {
+	var n int
+
+	err := si.db.QueryRowWriter(
+		`SELECT COUNT(*) FROM core.sqlite_master
+		 WHERE type = 'table' AND name IN ('artist_credit_part', 'artist_credit_ref')`,
+	).Scan(&n)
+
+	return err == nil && n == 2
+}
+
+// mergeArtifactCredits copies the credit decomposition out of the
+// attached artifact.
+//
+// Credits are replaced wholesale rather than merged: they are derived
+// entirely from one dump build, they are keyed by ids that are only
+// meaningful within the artifact that carried them, and a half-updated
+// credit renders as the wrong artists rather than as missing ones.
+//
+// A failure here is logged and not returned.  The catalog has already
+// merged at this point, and a catalog without credits is the catalog
+// this app had before them -- every credit falls back to its single
+// artist, which is the same fallback an untagged file already gets.
+func (si *SearchIndex) mergeArtifactCredits(ctx context.Context) {
+	if !si.artifactHasCredits() {
+		si.logger.Info("core artifact: no credit tables, keeping single-artist credits")
+
+		return
+	}
+
+	start := time.Now()
+
+	for _, stmt := range []string{
+		"DELETE FROM artist_credit_part",
+		"DELETE FROM artist_credit_ref",
+		`INSERT OR REPLACE INTO artist_credit_part
+			(credit_id, position, artist_mbid, credited_name, join_phrase)
+		 SELECT credit_id, position, artist_mbid, credited_name, join_phrase
+		 FROM core.artist_credit_part`,
+		`INSERT OR REPLACE INTO artist_credit_ref (mbid, credit_id)
+		 SELECT mbid, credit_id FROM core.artist_credit_ref`,
+	} {
+		if err := ctx.Err(); err != nil {
+			return
+		}
+
+		if _, err := si.db.ExecContext(stmt); err != nil {
+			si.logger.Warn("core artifact: credit merge failed", "error", err)
+
+			return
+		}
+	}
+
+	var refs int
+
+	_ = si.db.QueryRowWriter("SELECT COUNT(*) FROM artist_credit_ref").Scan(&refs)
+
+	si.logger.Info("core artifact: credits merged",
+		"entities", refs,
+		"elapsed", time.Since(start).Round(time.Millisecond),
+	)
+}

backend/explore/artifactimport_test.go

@@ -3,6 +3,7 @@ package explore
 import (
 	"context"
 	"database/sql"
+	"encoding/hex"
 	"os"
 	"path/filepath"
 	"strings"
@@ -597,3 +598,153 @@ func TestImportCoreArtifactReadsTotalsWhenPresent(t *testing.T) {
 		t.Errorf("TotalTracks = %d, want 0 (the catalog does not say)", old.TotalTracks)
 	}
 }
+
+// addArtifactCredits gives an artifact file the credit tables the
+// exporter now writes, so the import path can be exercised against one
+// that has them.
+func addArtifactCredits(t *testing.T, path string) {
+	t.Helper()
+
+	db, err := sql.Open("sqlite", "file:"+path)
+	if err != nil {
+		t.Fatalf("open artifact: %v", err)
+	}
+
+	defer func() { _ = db.Close() }()
+
+	for _, stmt := range []string{
+		`CREATE TABLE artist_credit_part (
+			credit_id     INTEGER NOT NULL,
+			position      INTEGER NOT NULL,
+			artist_mbid   BLOB NOT NULL,
+			credited_name TEXT NOT NULL,
+			join_phrase   TEXT NOT NULL DEFAULT '',
+			PRIMARY KEY (credit_id, position)
+		) WITHOUT ROWID`,
+		`CREATE TABLE artist_credit_ref (
+			mbid      BLOB NOT NULL PRIMARY KEY,
+			credit_id INTEGER NOT NULL
+		) WITHOUT ROWID`,
+	} {
+		if _, err := db.Exec(stmt); err != nil {
+			t.Fatalf("create credit tables: %v", err)
+		}
+	}
+
+	// The packed form the catalog stores.  uuid16/parseUUID live behind
+	// the indexbuild tag, so this file decodes for itself.
+	pack := func(mbid string) []byte {
+		raw, err := hex.DecodeString(strings.ReplaceAll(mbid, "-", ""))
+		if err != nil || len(raw) != 16 {
+			t.Fatalf("fixture MBID %q is not a UUID: %v", mbid, err)
+		}
+
+		return raw
+	}
+
+	a, b, rec := pack(artA), pack(artB), pack(recA)
+
+	for _, part := range [][]any{
+		{7, 0, a, "Artist A", " feat. "},
+		{7, 1, b, "Artist B", ""},
+	} {
+		if _, err := db.Exec(`INSERT INTO artist_credit_part
+			(credit_id, position, artist_mbid, credited_name, join_phrase)
+			VALUES (?, ?, ?, ?, ?)`, part...); err != nil {
+			t.Fatalf("insert part: %v", err)
+		}
+	}
+
+	if _, err := db.Exec(
+		"INSERT INTO artist_credit_ref (mbid, credit_id) VALUES (?, ?)", rec, 7,
+	); err != nil {
+		t.Fatalf("insert ref: %v", err)
+	}
+}
+
+// TestImportCoreArtifactMergesCredits is the positive half of the
+// compatibility pair: an artifact that carries credits delivers them,
+// rendering back to the credit string they decompose.
+func TestImportCoreArtifactMergesCredits(t *testing.T) {
+	db := database.NewTestDB(t)
+	si := NewSearchIndex(db, nil, nil, testLogger())
+
+	path := writeTestArtifact(t, validMeta(), []artifactRow{
+		{"recording", recA, "Song A", "Artist A feat. Artist B", artA, 2000},
+	})
+
+	addArtifactCredits(t, path)
+
+	if err := si.importCoreArtifact(context.Background(), path); err != nil {
+		t.Fatalf("importCoreArtifact: %v", err)
+	}
+
+	rows, err := db.QueryContext(
+		`SELECT p.credited_name, p.join_phrase
+		 FROM artist_credit_ref r
+		 JOIN artist_credit_part p ON p.credit_id = r.credit_id
+		 ORDER BY p.position`,
+	)
+	if err != nil {
+		t.Fatalf("query credits: %v", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var rendered strings.Builder
+
+	for rows.Next() {
+		var name, join string
+
+		if err := rows.Scan(&name, &join); err != nil {
+			t.Fatalf("scan: %v", err)
+		}
+
+		rendered.WriteString(name)
+		rendered.WriteString(join)
+	}
+
+	if got := rendered.String(); got != "Artist A feat. Artist B" {
+		t.Errorf("rendered credit = %q, want %q", got, "Artist A feat. Artist B")
+	}
+}
+
+// TestImportCoreArtifactWithoutCredits is the regression that matters
+// most here: an artifact published before credits existed cannot be
+// re-cut retroactively, so it must import as a catalog that declines to
+// answer rather than failing outright.  writeTestArtifact deliberately
+// builds one without the tables.
+func TestImportCoreArtifactWithoutCredits(t *testing.T) {
+	db := database.NewTestDB(t)
+	si := NewSearchIndex(db, nil, nil, testLogger())
+
+	path := writeTestArtifact(t, validMeta(), []artifactRow{
+		{"recording", recA, "Song A", "Artist A", artA, 2000},
+	})
+
+	if err := si.importCoreArtifact(context.Background(), path); err != nil {
+		t.Fatalf("an artifact without credit tables must still import: %v", err)
+	}
+
+	var rows int
+	if err := db.QueryRowWriter(
+		"SELECT COUNT(*) FROM explore_index",
+	).Scan(&rows); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+
+	if rows != 1 {
+		t.Errorf("catalog rows = %d, want 1", rows)
+	}
+
+	var refs int
+	if err := db.QueryRowWriter(
+		"SELECT COUNT(*) FROM artist_credit_ref",
+	).Scan(&refs); err != nil {
+		t.Fatalf("count refs: %v", err)
+	}
+
+	if refs != 0 {
+		t.Errorf("credit refs = %d, want 0", refs)
+	}
+}

backend/explore/cache_test.go

@@ -46,23 +46,42 @@ 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-test-key", data, 1*time.Second, "", "")
+	c.Set("ttl-live-key", data, time.Hour, "", "")
+	c.Set("ttl-expiring-key", data, 1*time.Second, "", "")
 
-	// Verify it's there immediately.
-	if _, ok := c.Get("ttl-test-key"); !ok {
-		t.Fatal("expected cache hit immediately after set")
+	if _, ok := c.Get("ttl-live-key"); !ok {
+		t.Fatal("expected a cache hit on an entry with an hour to live")
 	}
 
-	// Wait for expiry.
+	// Wait for the short one to expire.
 	time.Sleep(2 * time.Second)
 
-	if _, ok := c.Get("ttl-test-key"); ok {
+	if _, ok := c.Get("ttl-expiring-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) {

backend/explore/coverartproxy.go

@@ -25,8 +25,26 @@ const (
 	// where cached cover art thumbnails are stored.
 	thumbnailDir = CoverArtCacheDirName
 
-	// thumbnailTimeout is the HTTP timeout for fetching a thumbnail.
-	thumbnailTimeout = 10 * time.Second
+	// thumbnailTimeout is the HTTP timeout for fetching a thumbnail,
+	// and it has to cover a redirect the Cover Art Archive does not
+	// 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
@@ -97,6 +115,20 @@ 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)
@@ -177,8 +209,9 @@ func (p *CoverArtProxy) GetCandidateThumbnail(
 		}
 	}
 
-	// Network fetch on release group.
-	if releaseGroupMBID != "" {
+	// Network fetch on release group — unless a previous one was told
+	// there is none. See `knownMissing`.
+	if releaseGroupMBID != "" && !p.knownMissing(releaseGroupMBID) {
 		url := CoverArtGroupURL(releaseGroupMBID)
 		data, cacheable, err := p.fetch(url)
 
@@ -194,7 +227,7 @@ func (p *CoverArtProxy) GetCandidateThumbnail(
 	}
 
 	// Network fetch on release (fallback).
-	if releaseMBID != "" {
+	if releaseMBID != "" && !p.knownMissing(releaseMBID) {
 		url := CoverArtURL(releaseMBID)
 		data, cacheable, err := p.fetch(url)
 
@@ -285,6 +318,17 @@ 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)
 

backend/explore/credits.go

@@ -0,0 +1,132 @@
+package explore
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Reading multi-artist credits back out of the catalog.
+//
+// The tables are filled centrally (backend/explore/dumpcredits.go, and
+// the artifact import) and hold only credits naming more than one
+// artist: an entity with no rows here is credited to one artist, which
+// explore_index's own artist_name and artist_mbid already describe.
+// Absence is the common case and means "nothing to decompose", never
+// "unknown".
+//
+// The lookup is keyed on the *recording* MBID, which both sides of the
+// app already have -- a catalog row carries it and so does a local
+// file (library.Track.RecordingMBID) -- so one query serves the Explore
+// pages and the library's own lists without either needing to know
+// where the other gets its rows.
+
+// CreditPart is one credited artist within a credit, in credit order.
+//
+// CreditedName is the name *as credited*, which is not the artist's own
+// name: MusicBrainz credits "Snoop Dogg" on a track by the artist
+// called "Snoop Doggy Dogg".  Display uses it; navigation uses
+// ArtistMBID.  JoinPhrase is the literal connector that follows this
+// part, so a credit renders by concatenation and never by searching a
+// name inside a credit string.
+type CreditPart struct {
+	Position     int    `json:"position"`
+	ArtistMBID   string `json:"artistMbid"`
+	CreditedName string `json:"creditedName"`
+	JoinPhrase   string `json:"joinPhrase"`
+}
+
+// creditLookupBatch bounds how many MBIDs go into one IN clause.  A
+// tracklist is the caller here, so the realistic ceiling is a few
+// hundred; the bound exists so a 50,000-row selection cannot build a
+// statement SQLite refuses to parse.
+const creditLookupBatch = 500
+
+// GetCredits returns the decomposition of every multi-artist credit
+// among the given entity MBIDs, keyed by MBID.
+//
+// MBIDs with a single-artist credit are simply absent from the result,
+// which is what the caller wants: it renders its existing single link
+// for those, and that is the same answer it would have rendered anyway.
+func (si *SearchIndex) GetCredits(mbids []string) (map[string][]CreditPart, error) {
+	out := make(map[string][]CreditPart)
+
+	for start := 0; start < len(mbids); start += creditLookupBatch {
+		end := min(start+creditLookupBatch, len(mbids))
+
+		if err := si.appendCredits(mbids[start:end], out); err != nil {
+			return nil, err
+		}
+	}
+
+	return out, nil
+}
+
+// appendCredits runs one batch into the accumulating result.
+func (si *SearchIndex) appendCredits(
+	mbids []string, out map[string][]CreditPart,
+) error {
+	args := make([]any, 0, len(mbids))
+	holders := make([]string, 0, len(mbids))
+
+	for _, mbid := range mbids {
+		if mbid == "" {
+			continue
+		}
+
+		args = append(args, dbMBID(mbid))
+		holders = append(holders, "?")
+	}
+
+	if len(args) == 0 {
+		return nil
+	}
+
+	// Ordered by position because that ordering *is* the credit's
+	// meaning; the caller concatenates in the order it receives.
+	rows, err := si.db.QueryContext(
+		`SELECT r.mbid, p.position, p.artist_mbid, p.credited_name, p.join_phrase
+		 FROM artist_credit_ref r
+		 JOIN artist_credit_part p ON p.credit_id = r.credit_id
+		 WHERE r.mbid IN (`+strings.Join(holders, ",")+`)
+		 ORDER BY r.mbid, p.position`,
+		args...,
+	)
+	if err != nil {
+		return fmt.Errorf("read artist credits: %w", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	for rows.Next() {
+		var (
+			entity dbMBID
+			artist dbMBID
+			part   CreditPart
+		)
+
+		if err := rows.Scan(
+			&entity, &part.Position, &artist, &part.CreditedName, &part.JoinPhrase,
+		); err != nil {
+			return fmt.Errorf("scan artist credit: %w", err)
+		}
+
+		part.ArtistMBID = string(artist)
+		out[string(entity)] = append(out[string(entity)], part)
+	}
+
+	if err := rows.Err(); err != nil {
+		return fmt.Errorf("read artist credits: %w", err)
+	}
+
+	return nil
+}
+
+// GetCredits is the bound form: the frontend asks for a tracklist's
+// worth of MBIDs at once rather than one per row.
+//
+// Batched for the reason every other per-row backend question here is:
+// asking on hover or on render turns a list into N IPC round trips, and
+// this one is asked about every row of every list in the app.
+func (e *Service) GetCredits(mbids []string) (map[string][]CreditPart, error) {
+	return e.index.GetCredits(mbids)
+}

backend/explore/credits_test.go

@@ -0,0 +1,128 @@
+package explore
+
+import (
+	"encoding/hex"
+	"fmt"
+	"strings"
+	"testing"
+
+	"yellowjacket/backend/database"
+)
+
+// seedCredit writes one multi-artist credit and points an entity at it,
+// the way the dump import and the artifact import both do.
+func seedCredit(t *testing.T, db *database.DB, entity string, id int, parts []CreditPart) {
+	t.Helper()
+
+	pack := func(mbid string) []byte {
+		raw, err := hex.DecodeString(strings.ReplaceAll(mbid, "-", ""))
+		if err != nil || len(raw) != 16 {
+			t.Fatalf("bad fixture mbid %q: %v", mbid, err)
+		}
+
+		return raw
+	}
+
+	if _, err := db.ExecContext(
+		"INSERT INTO artist_credit_ref (mbid, credit_id) VALUES (?, ?)",
+		pack(entity), id,
+	); err != nil {
+		t.Fatalf("seed ref: %v", err)
+	}
+
+	for _, p := range parts {
+		if _, err := db.ExecContext(
+			`INSERT INTO artist_credit_part
+				(credit_id, position, artist_mbid, credited_name, join_phrase)
+			 VALUES (?, ?, ?, ?, ?)`,
+			id, p.Position, pack(p.ArtistMBID), p.CreditedName, p.JoinPhrase,
+		); err != nil {
+			t.Fatalf("seed part: %v", err)
+		}
+	}
+}
+
+// TestGetCreditsDecomposes: the parts come back in position order and
+// concatenate to the credit they describe.
+func TestGetCreditsDecomposes(t *testing.T) {
+	db := database.NewTestDB(t)
+	si := NewSearchIndex(db, nil, nil, testLogger())
+
+	rec := testMBID("rec-1")
+	a, b := testMBID("artist-a"), testMBID("artist-b")
+
+	seedCredit(t, db, rec, 7, []CreditPart{
+		{Position: 0, ArtistMBID: a, CreditedName: "2Pac", JoinPhrase: " feat. "},
+		{Position: 1, ArtistMBID: b, CreditedName: "Snoop Dogg"},
+	})
+
+	got, err := si.GetCredits([]string{rec})
+	if err != nil {
+		t.Fatalf("GetCredits: %v", err)
+	}
+
+	parts := got[rec]
+	if len(parts) != 2 {
+		t.Fatalf("parts = %d, want 2", len(parts))
+	}
+
+	var rendered strings.Builder
+	for _, p := range parts {
+		rendered.WriteString(p.CreditedName)
+		rendered.WriteString(p.JoinPhrase)
+	}
+
+	if rendered.String() != "2Pac feat. Snoop Dogg" {
+		t.Errorf("rendered = %q, want %q", rendered.String(), "2Pac feat. Snoop Dogg")
+	}
+
+	// Dashed on the way out: a blob reaching the frontend is sixteen
+	// bytes of mojibake, and nothing above mbid.go speaks that.
+	if parts[0].ArtistMBID != a {
+		t.Errorf("artist mbid = %q, want %q", parts[0].ArtistMBID, a)
+	}
+}
+
+// TestGetCreditsOmitsSingleArtist: absence is the common case and means
+// "nothing to decompose", so the caller renders its existing one link.
+func TestGetCreditsOmitsSingleArtist(t *testing.T) {
+	db := database.NewTestDB(t)
+	si := NewSearchIndex(db, nil, nil, testLogger())
+
+	got, err := si.GetCredits([]string{testMBID("untagged"), ""})
+	if err != nil {
+		t.Fatalf("GetCredits: %v", err)
+	}
+
+	if len(got) != 0 {
+		t.Errorf("got %d credits, want none", len(got))
+	}
+}
+
+// TestGetCreditsBatches: the lookup is asked about whole tracklists, so
+// it must not build one statement per row or one SQLite refuses to
+// parse.
+func TestGetCreditsBatches(t *testing.T) {
+	db := database.NewTestDB(t)
+	si := NewSearchIndex(db, nil, nil, testLogger())
+
+	mbids := make([]string, 0, creditLookupBatch*2+7)
+	for i := range creditLookupBatch*2 + 7 {
+		mbids = append(mbids, testMBID(fmt.Sprintf("batch-%d", i)))
+	}
+
+	// One real credit somewhere past the first batch boundary.
+	seedCredit(t, db, mbids[creditLookupBatch+3], 9, []CreditPart{
+		{Position: 0, ArtistMBID: testMBID("a"), CreditedName: "A", JoinPhrase: " & "},
+		{Position: 1, ArtistMBID: testMBID("b"), CreditedName: "B"},
+	})
+
+	got, err := si.GetCredits(mbids)
+	if err != nil {
+		t.Fatalf("GetCredits: %v", err)
+	}
+
+	if len(got[mbids[creditLookupBatch+3]]) != 2 {
+		t.Errorf("a credit past the first batch boundary was not returned")
+	}
+}

backend/explore/dumpcredits.go

@@ -0,0 +1,637 @@
+//go:build indexbuild
+
+package explore
+
+import (
+	"archive/tar"
+	"bufio"
+	"compress/bzip2"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"path"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+// Multi-artist credits, from the core MusicBrainz dump.
+//
+// A credit is ordered parts and the credit *string* is derived from
+// them; MusicBrainz's own artist_credit.name is a cached render.  What
+// this pass extracts is the decomposition: for each catalog recording
+// and release group whose credit names more than one artist, the
+// credited artists in order, each with the name *as credited* and the
+// join phrase that follows it.  See artist_credit_part.sql for why that
+// is stored rather than derived, and why nothing may reconstruct a
+// credit by searching a name inside a credit string.
+//
+// It is a separate dump from everything else here, and it has to be.
+// The canonical dump this importer already streams gives artist_mbids
+// (an ordered list) and artist_credit_name (the *rendered* string) --
+// no join phrases, and no per-artist as-credited names.  Splitting the
+// rendered string using canonical artist names fails on exactly the
+// credits that matter: measured on a real library, 21% of multi-artist
+// credits name an artist differently from the artist's own name
+// ("Snoop Dogg" credited on a track by "Snoop Doggy Dogg"), so the
+// substring is simply not there.  The JSON dumps were checked too and
+// cover 153,691 recordings of ~35M, with zero overlap against a real
+// library.  This dump is the only source.
+//
+// Cost, measured on the 20260815 export: 7.1 GB compressed, decompressed
+// by pure-Go compress/bzip2 at ~26 MB/s uncompressed (~13.7 min for the
+// whole file, single-threaded).  cmd/indexbuild is built CGO_ENABLED=0,
+// so the stdlib decompressor is what there is -- and it is fine, because
+// the 2 MB/s origin throttle dominates, as it does for every other dump
+// here.
+
+const (
+	// defaultMBDumpBaseURL is the core MusicBrainz export.  Only
+	// mbdump.tar.bz2 is fetched; the other tarballs there hold data this
+	// app has no use for.
+	defaultMBDumpBaseURL = "https://data.metabrainz.org/pub/musicbrainz/data/fullexport/"
+)
+
+var (
+	mbdumpDirRe  = regexp.MustCompile(`^\d{8}-\d+$`)
+	mbdumpFileRe = regexp.MustCompile(`^mbdump\.tar\.bz2$`)
+
+	// ErrDumpShape is returned when a dump member does not have the
+	// columns this code was written against.  It is deliberately fatal:
+	// reading the wrong column silently produces a catalog whose credits
+	// are subtly wrong, which is far worse than a failed build.
+	ErrDumpShape = errors.New("musicbrainz dump member has an unexpected shape")
+)
+
+// Column positions in the Postgres COPY output, verified against the
+// 20260815 export.  There is no header row to read them from, so they
+// are asserted instead -- see checkShape.
+const (
+	artistColID  = 0
+	artistColGID = 1
+	artistColMin = 2
+
+	creditColID          = 0
+	creditColArtistCount = 2
+	creditColMin         = 3
+
+	partColCredit   = 0
+	partColPosition = 1
+	partColArtist   = 2
+	partColName     = 3
+	partColJoin     = 4
+	partColMin      = 5
+
+	// recording and release_group share a layout in the columns this
+	// pass reads: id, gid, name, artist_credit, ...
+	entityColGID    = 1
+	entityColCredit = 3
+	entityColMin    = 4
+)
+
+// creditPart is one credited artist within a credit.
+type creditPart struct {
+	position int
+	artistID int32
+	name     string
+	join     string
+}
+
+// creditScan is what one pass over the dump collects.
+type creditScan struct {
+	// artistGIDs maps an artist row id to its MBID.  artist_credit_name
+	// references artists by row id, and the tar orders `artist` before
+	// it, so this is complete by the time it is read.
+	artistGIDs map[int32]uuid16
+
+	// multiCredits are the credit ids naming more than one artist, from
+	// artist_credit.artist_count.  Taking the count from the dump rather
+	// than counting parts means a credit can be rejected before its
+	// parts are stored.
+	multiCredits map[int32]struct{}
+
+	// parts are the decompositions of multiCredits, keyed by credit id.
+	parts map[int32][]creditPart
+
+	// refs maps a kept catalog entity to its credit.  Only entities in
+	// explore_index and only multi-artist credits: everything else is
+	// already described by explore_index's own artist_name/artist_mbid.
+	refs map[uuid16]int32
+
+	// used are the credits some ref actually points at, which is a small
+	// fraction of multiCredits -- the catalog keeps ~1.8M entities of
+	// MusicBrainz's tens of millions.
+	used map[int32]struct{}
+
+	skippedUnknownArtist int
+}
+
+// creditsImportDoneKey marks in explore_index_meta that the credit pass
+// has run against the current catalog.
+//
+// It is its own marker rather than part of the import's stage state for
+// a resume reason: the credit pass runs *after* the catalog is
+// assembled, and a failure in it must not send the next run back
+// through the ~205 GB it just finished.  Marking separately means a
+// retry retries only this.
+const creditsImportDoneKey = "credits_import_done"
+
+// ensureArtistCredits runs the credit pass unless it has already run
+// against this catalog, reporting whether it newly populated them.
+//
+// Called from both of run's paths -- the full import and the resume
+// that finds the rows already assembled -- and from the maintenance
+// entry point below, since a catalog built before credits existed is
+// otherwise never offered a chance to gain them: the index job picks
+// its mode from the index's own state, and a complete import means
+// "refresh", which never enters run() at all.
+//
+// The return value is what tells the job there is something new worth
+// publishing.  A refresh otherwise reports "changed" only when the
+// listens series advanced, so credits would sit in the CI database and
+// never reach an artifact.
+func (imp *dumpImporter) ensureArtistCredits(ctx context.Context) bool {
+	if imp.si.hasMeta(creditsImportDoneKey) {
+		return false
+	}
+
+	url, err := discoverDumpFile(
+		ctx, imp.httpClient, imp.mbdumpBaseURL, mbdumpDirRe, mbdumpFileRe,
+	)
+	if err != nil {
+		imp.logger.Warn("credit import: could not find the dump", "error", err)
+
+		return false
+	}
+
+	if err := imp.importArtistCredits(ctx, url); err != nil {
+		// A catalog without credits is the catalog this app shipped
+		// before them: every credit falls back to its single artist.
+		// That is worth far less than failing an import that otherwise
+		// succeeded.
+		imp.logger.Warn("credit import: failed", "error", err)
+
+		return false
+	}
+
+	imp.si.setMeta(creditsImportDoneKey, "1")
+
+	return true
+}
+
+// EnsureArtistCredits tops up the credit tables outside a full import.
+//
+// It exists because the index job's modes are decided from the index's
+// own state: a cache holding a completed import chooses `refresh`,
+// which folds in incremental listens and never enters the dump
+// importer.  Without this, a catalog built before the credit pass
+// existed could only gain credits from a `rebuild` -- and a rebuild
+// re-downloads ~205 GB to reproduce rows it already has, to add
+// something that costs 7 GB on its own.
+//
+// Reports whether credits were newly populated, so the caller knows
+// there is a new artifact worth publishing.
+func (e *Service) EnsureArtistCredits(ctx context.Context) bool {
+	imp, err := newDumpImporter(e.index, e.lb)
+	if err != nil {
+		e.index.logger.Warn("credit import: could not start", "error", err)
+
+		return false
+	}
+
+	return imp.ensureArtistCredits(ctx)
+}
+
+// importArtistCredits streams the core MusicBrainz dump and fills
+// artist_credit_part and artist_credit_ref for the entities the catalog
+// kept.
+//
+// It runs after assembleIndex because it asks explore_index which
+// entities those are: the popularity filter decides what is worth
+// carrying credits for, and asking the table rather than the kept sets
+// means this stays correct if that filter changes.
+func (imp *dumpImporter) importArtistCredits(ctx context.Context, url string) error {
+	kept, err := imp.keptEntityMBIDs(ctx)
+	if err != nil {
+		return err
+	}
+
+	if len(kept) == 0 {
+		imp.logger.Warn("credit import: no catalog entities, skipping")
+
+		return nil
+	}
+
+	imp.logger.Info("credit import: starting", "url", url, "entities", len(kept))
+	imp.logJob("Streaming MusicBrainz dump for artist credits")
+
+	scan, err := imp.scanCreditDump(ctx, url, kept)
+	if err != nil {
+		return err
+	}
+
+	imp.logger.Info("credit import: scanned",
+		"multiArtistCredits", len(scan.multiCredits),
+		"entitiesWithMultiArtistCredit", len(scan.refs),
+		"creditsUsed", len(scan.used),
+	)
+
+	return imp.writeCredits(ctx, scan)
+}
+
+// keptEntityMBIDs is every recording and release group in the catalog.
+// Artists are excluded: an artist is not credited to a credit.
+func (imp *dumpImporter) keptEntityMBIDs(ctx context.Context) (map[uuid16]struct{}, error) {
+	rows, err := imp.si.db.QueryContextWith(ctx,
+		`SELECT mbid FROM explore_index
+		 WHERE entity_type IN (2 /* release_group */, 3 /* recording */)`,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("credit import: read catalog entities: %w", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	out := make(map[uuid16]struct{})
+
+	for rows.Next() {
+		var raw []byte
+
+		if err := rows.Scan(&raw); err != nil {
+			return nil, fmt.Errorf("credit import: scan mbid: %w", err)
+		}
+
+		if len(raw) != len(uuid16{}) {
+			continue
+		}
+
+		var id uuid16
+
+		copy(id[:], raw)
+
+		out[id] = struct{}{}
+	}
+
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("credit import: read catalog entities: %w", err)
+	}
+
+	return out, nil
+}
+
+// scanCreditDump makes one sequential pass over mbdump.tar.bz2.
+//
+// The tar's members are alphabetical, which is what makes a single pass
+// possible without buffering the big ones: `artist` and
+// `artist_credit_name` both arrive before `recording` and
+// `release_group`, so by the time an entity names a credit, that
+// credit's parts and their artists' MBIDs are already known and the
+// entity can be resolved and dropped.  35M recording rows are never
+// held.
+//
+// The order is not depended on blindly: an entity naming a credit that
+// has not been seen is counted and reported rather than silently
+// producing an empty catalog, which is what a reordered export would
+// otherwise look like.
+func (imp *dumpImporter) scanCreditDump(
+	ctx context.Context, url string, kept map[uuid16]struct{},
+) (*creditScan, error) {
+	stream := imp.openDumpStream(ctx, url, 0)
+
+	defer func() { _ = stream.Close() }()
+
+	return imp.scanCreditTar(
+		ctx,
+		tar.NewReader(bzip2.NewReader(bufio.NewReaderSize(stream, 1<<20))),
+		kept,
+	)
+}
+
+// scanCreditTar is the parse, separated from the fetch so it can be
+// driven by a tar built in a test.  compress/bzip2 is decompress-only,
+// so a test cannot produce the real container.
+func (imp *dumpImporter) scanCreditTar(
+	ctx context.Context, tr *tar.Reader, kept map[uuid16]struct{},
+) (*creditScan, error) {
+	scan := &creditScan{
+		artistGIDs:   make(map[int32]uuid16),
+		multiCredits: make(map[int32]struct{}),
+		parts:        make(map[int32][]creditPart),
+		refs:         make(map[uuid16]int32),
+		used:         make(map[int32]struct{}),
+	}
+
+	for {
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
+
+		hdr, err := tr.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+
+		if err != nil {
+			return nil, fmt.Errorf("credit import: tar: %w", err)
+		}
+
+		if hdr.Typeflag != tar.TypeReg {
+			continue
+		}
+
+		done, err := imp.scanCreditMember(ctx, hdr.Name, tr, kept, scan)
+		if err != nil {
+			return nil, err
+		}
+
+		if done {
+			// Everything this pass needs has been read; the rest of the
+			// tarball is other entities' data and decompressing it would
+			// cost minutes for nothing.
+			break
+		}
+	}
+
+	if scan.skippedUnknownArtist > 0 {
+		imp.logger.Warn("credit import: credits dropped for unknown artists",
+			"count", scan.skippedUnknownArtist,
+		)
+	}
+
+	return scan, nil
+}
+
+// scanCreditMember dispatches one tar member, reporting whether the
+// pass has everything it needs.
+func (imp *dumpImporter) scanCreditMember(
+	ctx context.Context, name string, r io.Reader,
+	kept map[uuid16]struct{}, scan *creditScan,
+) (bool, error) {
+	switch path.Base(name) {
+	case "artist":
+		return false, imp.scanArtists(ctx, r, scan)
+	case "artist_credit":
+		return false, imp.scanCredits(ctx, r, scan)
+	case "artist_credit_name":
+		return false, imp.scanCreditParts(ctx, r, scan)
+	case "recording", "release_group":
+		if err := imp.scanCreditedEntities(ctx, r, kept, scan); err != nil {
+			return false, err
+		}
+
+		// release_group sorts after recording, so the pass is complete
+		// once it has been read.
+		return path.Base(name) == "release_group", nil
+	default:
+		return false, nil
+	}
+}
+
+// scanArtists records every artist's MBID by row id.
+func (imp *dumpImporter) scanArtists(
+	ctx context.Context, r io.Reader, scan *creditScan,
+) error {
+	return scanTSV(ctx, r, artistColMin, "artist", func(fields []string) error {
+		id, ok := parseInt32(fields[artistColID])
+		if !ok {
+			return nil
+		}
+
+		var gid uuid16
+
+		if !parseUUID(fields[artistColGID], gid[:]) {
+			return fmt.Errorf("%w: artist.gid is not a UUID: %q",
+				ErrDumpShape, truncate(fields[artistColGID]))
+		}
+
+		scan.artistGIDs[id] = gid
+
+		return nil
+	})
+}
+
+// scanCredits records which credits name more than one artist.
+func (imp *dumpImporter) scanCredits(
+	ctx context.Context, r io.Reader, scan *creditScan,
+) error {
+	return scanTSV(ctx, r, creditColMin, "artist_credit", func(fields []string) error {
+		id, ok := parseInt32(fields[creditColID])
+		if !ok {
+			return nil
+		}
+
+		count, ok := parseInt32(fields[creditColArtistCount])
+		if !ok {
+			return fmt.Errorf("%w: artist_credit.artist_count is not a number: %q",
+				ErrDumpShape, truncate(fields[creditColArtistCount]))
+		}
+
+		if count > 1 {
+			scan.multiCredits[id] = struct{}{}
+		}
+
+		return nil
+	})
+}
+
+// scanCreditParts records the decomposition of every multi-artist
+// credit.
+func (imp *dumpImporter) scanCreditParts(
+	ctx context.Context, r io.Reader, scan *creditScan,
+) error {
+	return scanTSV(ctx, r, partColMin, "artist_credit_name", func(fields []string) error {
+		credit, ok := parseInt32(fields[partColCredit])
+		if !ok {
+			return nil
+		}
+
+		if _, multi := scan.multiCredits[credit]; !multi {
+			return nil
+		}
+
+		position, ok := parseInt32(fields[partColPosition])
+		if !ok {
+			return nil
+		}
+
+		artist, ok := parseInt32(fields[partColArtist])
+		if !ok {
+			return nil
+		}
+
+		scan.parts[credit] = append(scan.parts[credit], creditPart{
+			position: int(position),
+			artistID: artist,
+			name:     fields[partColName],
+			join:     fields[partColJoin],
+		})
+
+		return nil
+	})
+}
+
+// scanCreditedEntities resolves recordings and release groups against
+// the catalog, keeping only those the catalog holds and whose credit
+// names more than one artist.
+func (imp *dumpImporter) scanCreditedEntities(
+	ctx context.Context, r io.Reader, kept map[uuid16]struct{}, scan *creditScan,
+) error {
+	return scanTSV(ctx, r, entityColMin, "recording/release_group",
+		func(fields []string) error {
+			var gid uuid16
+
+			if !parseUUID(fields[entityColGID], gid[:]) {
+				return fmt.Errorf("%w: entity gid is not a UUID: %q",
+					ErrDumpShape, truncate(fields[entityColGID]))
+			}
+
+			if _, want := kept[gid]; !want {
+				return nil
+			}
+
+			credit, ok := parseInt32(fields[entityColCredit])
+			if !ok {
+				return fmt.Errorf("%w: entity artist_credit is not a number: %q",
+					ErrDumpShape, truncate(fields[entityColCredit]))
+			}
+
+			if _, multi := scan.multiCredits[credit]; !multi {
+				return nil
+			}
+
+			scan.refs[gid] = credit
+			scan.used[credit] = struct{}{}
+
+			return nil
+		})
+}
+
+// scanTSV reads Postgres COPY output a line at a time, unescaping each
+// field and handing the row to fn.
+//
+// The shape is asserted on the first row rather than trusted: this dump
+// has no header, so a column that moved would otherwise be read as a
+// neighbouring one and produce a catalog that is quietly wrong.
+func scanTSV(
+	ctx context.Context, r io.Reader, minCols int, member string,
+	fn func(fields []string) error,
+) error {
+	sc := bufio.NewScanner(r)
+	sc.Buffer(make([]byte, 0, 1<<20), 1<<24)
+
+	checked := false
+	rows := 0
+
+	for sc.Scan() {
+		rows++
+
+		if rows%(1<<20) == 0 {
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+		}
+
+		line := sc.Text()
+		if line == "" {
+			continue
+		}
+
+		fields := strings.Split(line, "\t")
+		if len(fields) < minCols {
+			if !checked {
+				return fmt.Errorf("%w: %s has %d columns, need at least %d",
+					ErrDumpShape, member, len(fields), minCols)
+			}
+
+			continue
+		}
+
+		checked = true
+
+		for i := range fields {
+			fields[i] = unescapeCopy(fields[i])
+		}
+
+		if err := fn(fields); err != nil {
+			return err
+		}
+	}
+
+	if err := sc.Err(); err != nil {
+		return fmt.Errorf("credit import: read %s: %w", member, err)
+	}
+
+	return nil
+}
+
+// unescapeCopy undoes Postgres COPY's text escaping.  A NULL (\N) is
+// returned as an empty string: every field this pass reads is either a
+// number it will reject or a name whose absence means the same as
+// empty.
+func unescapeCopy(s string) string {
+	if s == `\N` {
+		return ""
+	}
+
+	if !strings.ContainsRune(s, '\\') {
+		return s
+	}
+
+	var b strings.Builder
+
+	b.Grow(len(s))
+
+	for i := 0; i < len(s); i++ {
+		if s[i] != '\\' || i+1 >= len(s) {
+			b.WriteByte(s[i])
+
+			continue
+		}
+
+		i++
+
+		switch s[i] {
+		case 'n':
+			b.WriteByte('\n')
+		case 't':
+			b.WriteByte('\t')
+		case 'r':
+			b.WriteByte('\r')
+		case 'b':
+			b.WriteByte('\b')
+		case 'f':
+			b.WriteByte('\f')
+		case 'v':
+			b.WriteByte('\v')
+		case '\\':
+			b.WriteByte('\\')
+		default:
+			b.WriteByte('\\')
+			b.WriteByte(s[i])
+		}
+	}
+
+	return b.String()
+}
+
+func parseInt32(s string) (int32, bool) {
+	n, err := strconv.ParseInt(s, 10, 32)
+	if err != nil {
+		return 0, false
+	}
+
+	return int32(n), true
+}
+
+// truncate bounds an error message built from dump data, which is
+// attacker-free but can be long.
+func truncate(s string) string {
+	const limit = 64
+
+	if len(s) <= limit {
+		return s
+	}
+
+	return s[:limit] + "..."
+}

backend/explore/dumpcredits_test.go

@@ -0,0 +1,406 @@
+//go:build indexbuild
+
+package explore
+
+import (
+	"archive/tar"
+	"bytes"
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"yellowjacket/backend/database"
+)
+
+// tarOf builds an uncompressed tar of the named members, in the order
+// given.  Order is the point of several of these tests: the real dump's
+// members are alphabetical, which is what lets one pass resolve an
+// entity's credit without buffering 35M recordings.
+func tarOf(t *testing.T, members ...[2]string) *tar.Reader {
+	t.Helper()
+
+	var buf bytes.Buffer
+
+	tw := tar.NewWriter(&buf)
+
+	for _, m := range members {
+		body := []byte(m[1])
+
+		if err := tw.WriteHeader(&tar.Header{
+			Name:     "mbdump/" + m[0],
+			Mode:     0o644,
+			Size:     int64(len(body)),
+			Typeflag: tar.TypeReg,
+		}); err != nil {
+			t.Fatalf("tar header: %v", err)
+		}
+
+		if _, err := tw.Write(body); err != nil {
+			t.Fatalf("tar write: %v", err)
+		}
+	}
+
+	if err := tw.Close(); err != nil {
+		t.Fatalf("tar close: %v", err)
+	}
+
+	return tar.NewReader(&buf)
+}
+
+func tsv(rows ...[]string) string {
+	var b strings.Builder
+
+	for _, r := range rows {
+		b.WriteString(strings.Join(r, "\t"))
+		b.WriteByte('\n')
+	}
+
+	return b.String()
+}
+
+// mustMBID is testMBID in the packed form the catalog stores.
+func mustMBID(label string) uuid16 {
+	var u uuid16
+
+	if !parseUUID(testMBID(label), u[:]) {
+		panic("testMBID did not produce a UUID for " + label)
+	}
+
+	return u
+}
+
+// The two artists of the worked example, and the entities they credit.
+var (
+	creditRecMBID = mustMBID("recording-1")
+	creditRGMBID  = mustMBID("release-group-1")
+)
+
+// sampleDump is the shape verified against the 20260815 export:
+// artist(id, gid, ...), artist_credit(id, name, artist_count, ...),
+// artist_credit_name(credit, position, artist, name, join_phrase),
+// recording/release_group(id, gid, name, artist_credit, ...).
+func sampleDump(t *testing.T) *tar.Reader {
+	t.Helper()
+
+	return tarOf(t,
+		[2]string{"artist", tsv(
+			[]string{"11", testMBID("artist-a"), "Snoop Doggy Dogg", "Snoop Doggy Dogg"},
+			[]string{"22", testMBID("artist-b"), "2Pac", "2Pac"},
+		)},
+		[2]string{"artist_credit", tsv(
+			[]string{"900", "2Pac feat. Snoop Dogg", "2", "1", "", "0", ""},
+			[]string{"901", "Solo Artist", "1", "1", "", "0", ""},
+		)},
+		[2]string{"artist_credit_name", tsv(
+			// Deliberately out of position order: the dump is not
+			// obliged to emit them sorted and the credit's meaning is
+			// the order, not the file's.
+			[]string{"900", "1", "11", "Snoop Dogg", ""},
+			[]string{"900", "0", "22", "2Pac", " feat. "},
+			[]string{"901", "0", "11", "Solo Artist", ""},
+		)},
+		[2]string{"recording", tsv(
+			[]string{"1", testMBID("recording-1"), "Some Song", "900", "180000"},
+			[]string{"2", testMBID("not-kept"), "Other", "900", "1"},
+			[]string{"3", testMBID("solo"), "Solo", "901", "1"},
+		)},
+		[2]string{"release_group", tsv(
+			[]string{"5", testMBID("release-group-1"), "Some Album", "900", "1"},
+		)},
+	)
+}
+
+func creditTestImporter(t *testing.T) *dumpImporter {
+	t.Helper()
+
+	db := database.NewTestDB(t)
+
+	return &dumpImporter{
+		si:     NewSearchIndex(db, nil, nil, testLogger()),
+		logger: testLogger(),
+	}
+}
+
+// TestScanCreditDumpDecomposes is the worked example end to end: the
+// credit's parts come back in position order, with the *credited*
+// names and the join phrase between them.
+func TestScanCreditDumpDecomposes(t *testing.T) {
+	imp := creditTestImporter(t)
+
+	kept := map[uuid16]struct{}{
+		creditRecMBID: {},
+		creditRGMBID:  {},
+	}
+
+	scan, err := imp.scanCreditTar(context.Background(), sampleDump(t), kept)
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	if got := len(scan.refs); got != 2 {
+		t.Fatalf("refs = %d, want 2 (the recording and the release group)", got)
+	}
+
+	if scan.refs[creditRecMBID] != 900 {
+		t.Errorf("recording credit = %d, want 900", scan.refs[creditRecMBID])
+	}
+
+	parts := scan.parts[900]
+	if len(parts) != 2 {
+		t.Fatalf("parts = %d, want 2", len(parts))
+	}
+
+	// Sorting happens on write, so assert the pieces are all present
+	// and let the render test below check the order.
+	byPos := map[int]creditPart{}
+	for _, p := range parts {
+		byPos[p.position] = p
+	}
+
+	if byPos[0].name != "2Pac" || byPos[0].join != " feat. " {
+		t.Errorf("position 0 = %q/%q, want \"2Pac\"/\" feat. \"",
+			byPos[0].name, byPos[0].join)
+	}
+
+	// The credited name, not the artist's own name: this is the whole
+	// reason credited_name is stored per row.
+	if byPos[1].name != "Snoop Dogg" {
+		t.Errorf("position 1 credited name = %q, want \"Snoop Dogg\"", byPos[1].name)
+	}
+}
+
+// TestSingleArtistCreditsAreNotStored: a one-artist credit is already
+// described by explore_index's artist_name/artist_mbid, and storing it
+// would roughly triple the table to say nothing new.
+func TestSingleArtistCreditsAreNotStored(t *testing.T) {
+	imp := creditTestImporter(t)
+
+	solo := mustMBID("solo")
+	kept := map[uuid16]struct{}{solo: {}}
+
+	scan, err := imp.scanCreditTar(context.Background(), sampleDump(t), kept)
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	if len(scan.refs) != 0 {
+		t.Fatalf("a single-artist credit was referenced: %v", scan.refs)
+	}
+
+	if _, ok := scan.multiCredits[901]; ok {
+		t.Error("credit 901 has artist_count 1 and should not be multi")
+	}
+}
+
+// TestOnlyKeptEntitiesAreReferenced: the catalog's popularity filter
+// decides what is worth carrying credits for, and an entity outside it
+// must not produce a row pointing at nothing.
+func TestOnlyKeptEntitiesAreReferenced(t *testing.T) {
+	imp := creditTestImporter(t)
+
+	kept := map[uuid16]struct{}{creditRecMBID: {}}
+
+	scan, err := imp.scanCreditTar(context.Background(), sampleDump(t), kept)
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	if _, ok := scan.refs[mustMBID("not-kept")]; ok {
+		t.Error("an entity outside the catalog was referenced")
+	}
+
+	if len(scan.used) != 1 {
+		t.Errorf("used credits = %d, want 1", len(scan.used))
+	}
+}
+
+// TestWriteCreditsRoundTrips checks what the frontend will actually
+// read: parts in position order, dashed MBIDs out of the 16 raw bytes,
+// and a rendered credit that reassembles to the tagged string.
+func TestWriteCreditsRoundTrips(t *testing.T) {
+	imp := creditTestImporter(t)
+
+	kept := map[uuid16]struct{}{creditRecMBID: {}, creditRGMBID: {}}
+
+	scan, err := imp.scanCreditTar(context.Background(), sampleDump(t), kept)
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	if err := imp.writeCredits(context.Background(), scan); err != nil {
+		t.Fatalf("writeCredits: %v", err)
+	}
+
+	rows, err := imp.si.db.QueryContext(
+		`SELECT p.position, p.artist_mbid, p.credited_name, p.join_phrase
+		 FROM artist_credit_ref r
+		 JOIN artist_credit_part p ON p.credit_id = r.credit_id
+		 WHERE r.mbid = ?
+		 ORDER BY p.position`,
+		creditRecMBID[:],
+	)
+	if err != nil {
+		t.Fatalf("query: %v", err)
+	}
+
+	defer func() { _ = rows.Close() }()
+
+	var rendered strings.Builder
+
+	names := []string{}
+
+	for rows.Next() {
+		var (
+			pos  int
+			mbid []byte
+			name string
+			join string
+		)
+
+		if err := rows.Scan(&pos, &mbid, &name, &join); err != nil {
+			t.Fatalf("scan row: %v", err)
+		}
+
+		if len(mbid) != 16 {
+			t.Fatalf("artist_mbid is %d bytes, want 16", len(mbid))
+		}
+
+		names = append(names, name)
+
+		rendered.WriteString(name)
+		rendered.WriteString(join)
+	}
+
+	if err := rows.Err(); err != nil {
+		t.Fatalf("rows: %v", err)
+	}
+
+	// Concatenation is the contract: names in order, join phrases
+	// between them, and no searching a name inside a credit string.
+	if got := rendered.String(); got != "2Pac feat. Snoop Dogg" {
+		t.Errorf("rendered credit = %q, want %q", got, "2Pac feat. Snoop Dogg")
+	}
+
+	if len(names) != 2 || names[0] != "2Pac" {
+		t.Errorf("parts came back out of position order: %v", names)
+	}
+}
+
+// TestCreditRefsNeverDangle: a ref whose parts were not stored renders
+// as a credit with no artists at all, which is worse than the
+// single-artist fallback it replaced.
+func TestCreditRefsNeverDangle(t *testing.T) {
+	imp := creditTestImporter(t)
+
+	kept := map[uuid16]struct{}{creditRecMBID: {}}
+
+	scan, err := imp.scanCreditTar(context.Background(), sampleDump(t), kept)
+	if err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	// An artist the dump never named: the credit cannot be navigated to
+	// and must be dropped whole, taking its ref with it.
+	scan.artistGIDs = map[int32]uuid16{}
+
+	if err := imp.writeCredits(context.Background(), scan); err != nil {
+		t.Fatalf("writeCredits: %v", err)
+	}
+
+	var refs, parts int
+
+	if err := imp.si.db.QueryRowWriter(
+		"SELECT COUNT(*) FROM artist_credit_ref",
+	).Scan(&refs); err != nil {
+		t.Fatalf("count refs: %v", err)
+	}
+
+	if err := imp.si.db.QueryRowWriter(
+		"SELECT COUNT(*) FROM artist_credit_part",
+	).Scan(&parts); err != nil {
+		t.Fatalf("count parts: %v", err)
+	}
+
+	if refs != 0 || parts != 0 {
+		t.Fatalf("refs=%d parts=%d, want 0/0 when the artists are unknown", refs, parts)
+	}
+}
+
+// TestCreditDumpShapeIsAsserted: the dump has no header row, so a
+// column that moved would be read as its neighbour and produce a
+// catalog that is quietly wrong.  Loud is the requirement.
+func TestCreditDumpShapeIsAsserted(t *testing.T) {
+	imp := creditTestImporter(t)
+
+	short := tarOf(t, [2]string{"artist", tsv([]string{"11", "only-two-columns"})})
+
+	_, err := imp.scanCreditTar(context.Background(), short, map[uuid16]struct{}{})
+	if err == nil {
+		t.Fatal("a member with a non-UUID gid was accepted")
+	}
+
+	if !errors.Is(err, ErrDumpShape) {
+		t.Errorf("error = %v, want ErrDumpShape", err)
+	}
+}
+
+// TestUnescapeCopy covers Postgres COPY's text escaping, which reaches
+// artist names routinely -- a tab or backslash in a name would
+// otherwise shift every field after it.
+func TestUnescapeCopy(t *testing.T) {
+	tests := []struct{ in, want string }{
+		{`plain`, `plain`},
+		{`\N`, ``},
+		{`a\tb`, "a\tb"},
+		{`a\nb`, "a\nb"},
+		{`back\\slash`, `back\slash`},
+		{`AC\/DC`, `AC\/DC`},
+		{`trailing\`, `trailing\`},
+	}
+
+	for _, tt := range tests {
+		if got := unescapeCopy(tt.in); got != tt.want {
+			t.Errorf("unescapeCopy(%q) = %q, want %q", tt.in, got, tt.want)
+		}
+	}
+}
+
+// TestEnsureArtistCreditsIsIdempotent pins what the index job depends
+// on to decide whether to publish.
+//
+// The pass runs on every mode, including the `refresh` that a complete
+// catalog always chooses — so it must be free when there is nothing to
+// do, and it must say so.  A `true` here republishes the artifact; a
+// `true` on every run would republish an identical one weekly, and a
+// permanent `false` would mean a catalog that never gains credits at
+// all.
+func TestEnsureArtistCreditsIsIdempotent(t *testing.T) {
+	imp := creditTestImporter(t)
+
+	// The marker is what "already done" means; with it set, the pass
+	// must not reach the network or report a change.
+	imp.si.setMeta(creditsImportDoneKey, "1")
+
+	if imp.ensureArtistCredits(context.Background()) {
+		t.Fatal("a second run reported new credits; the artifact would republish forever")
+	}
+}
+
+// TestEnsureArtistCreditsReportsFailureAsNoChange: a dump that cannot be
+// reached leaves the catalog exactly as it was, and must not claim
+// otherwise — publishing on it would ship an artifact with no credits
+// and mark the work done.
+func TestEnsureArtistCreditsReportsFailureAsNoChange(t *testing.T) {
+	imp := creditTestImporter(t)
+	imp.httpClient = newDumpHTTPClient()
+	imp.mbdumpBaseURL = "http://127.0.0.1:1/nonexistent/"
+
+	if imp.ensureArtistCredits(context.Background()) {
+		t.Fatal("an unreachable dump reported new credits")
+	}
+
+	if imp.si.hasMeta(creditsImportDoneKey) {
+		t.Error("a failed pass marked itself done; it would never retry")
+	}
+}

backend/explore/dumpcreditswrite.go

@@ -0,0 +1,164 @@
+//go:build indexbuild
+
+package explore
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"sort"
+)
+
+// writeCredits persists the scanned decompositions.
+//
+// Only credits some catalog entity actually points at are written: the
+// dump has millions of multi-artist credits and the catalog keeps ~1.8M
+// entities, so storing every credit would be most of a table nothing
+// can reach.
+//
+// The two tables are written in one transaction, because a ref pointing
+// at parts that are not there renders as a credit with no artists --
+// worse than the single-artist fallback it replaced.
+func (imp *dumpImporter) writeCredits(ctx context.Context, scan *creditScan) error {
+	tx, err := imp.si.db.BeginTx()
+	if err != nil {
+		return fmt.Errorf("credit import: begin: %w", err)
+	}
+
+	defer func() { _ = tx.Rollback() }()
+
+	// A rebuild replaces the previous pass wholesale.  These are Cache
+	// tables derived entirely from the dump, so there is nothing to
+	// merge and a stale row is a wrong credit.
+	for _, table := range []string{"artist_credit_part", "artist_credit_ref"} {
+		if _, err := tx.ExecContext(ctx, "DELETE FROM "+table); err != nil {
+			return fmt.Errorf("credit import: clear %s: %w", table, err)
+		}
+	}
+
+	written, err := imp.writeCreditParts(ctx, tx, scan)
+	if err != nil {
+		return err
+	}
+
+	refs, err := imp.writeCreditRefs(ctx, tx, scan, written)
+	if err != nil {
+		return err
+	}
+
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("credit import: commit: %w", err)
+	}
+
+	imp.logger.Info("credit import: complete",
+		"credits", len(written),
+		"refs", refs,
+	)
+
+	return nil
+}
+
+// writeCreditParts inserts the parts of every used credit and returns
+// the set of credits that were actually stored.
+//
+// A credit is stored whole or not at all.  If any of its artists has no
+// MBID -- which should not happen, the dump being self-consistent, but
+// would leave a part that cannot be navigated to -- the credit is
+// dropped and the entity falls back to explore_index's single artist,
+// which is a worse answer rather than a broken one.
+func (imp *dumpImporter) writeCreditParts(
+	ctx context.Context, tx *sql.Tx, scan *creditScan,
+) (map[int32]struct{}, error) {
+	stmt, err := tx.PrepareContext(ctx,
+		`INSERT INTO artist_credit_part
+			(credit_id, position, artist_mbid, credited_name, join_phrase)
+		 VALUES (?, ?, ?, ?, ?)`,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("credit import: prepare part insert: %w", err)
+	}
+
+	defer func() { _ = stmt.Close() }()
+
+	written := make(map[int32]struct{}, len(scan.used))
+
+	for credit := range scan.used {
+		parts := scan.parts[credit]
+		if len(parts) < 2 {
+			// artist_credit said more than one artist and
+			// artist_credit_name did not deliver them.  Nothing to
+			// decompose, so leave the entity to its single artist.
+			continue
+		}
+
+		// Position order is the credit's meaning, and the dump is not
+		// obliged to emit it sorted.
+		sort.Slice(parts, func(i, j int) bool {
+			return parts[i].position < parts[j].position
+		})
+
+		resolved := make([][]any, 0, len(parts))
+		ok := true
+
+		for _, part := range parts {
+			gid, found := scan.artistGIDs[part.artistID]
+			if !found {
+				scan.skippedUnknownArtist++
+				ok = false
+
+				break
+			}
+
+			resolved = append(resolved, []any{
+				credit, part.position, gid[:], part.name, part.join,
+			})
+		}
+
+		if !ok {
+			continue
+		}
+
+		for _, args := range resolved {
+			if _, err := stmt.ExecContext(ctx, args...); err != nil {
+				return nil, fmt.Errorf("credit import: insert part: %w", err)
+			}
+		}
+
+		written[credit] = struct{}{}
+	}
+
+	return written, nil
+}
+
+// writeCreditRefs points each kept entity at its credit, skipping any
+// whose credit was not stored so a ref never dangles.
+func (imp *dumpImporter) writeCreditRefs(
+	ctx context.Context, tx *sql.Tx, scan *creditScan, written map[int32]struct{},
+) (int, error) {
+	stmt, err := tx.PrepareContext(ctx,
+		"INSERT OR REPLACE INTO artist_credit_ref (mbid, credit_id) VALUES (?, ?)",
+	)
+	if err != nil {
+		return 0, fmt.Errorf("credit import: prepare ref insert: %w", err)
+	}
+
+	defer func() { _ = stmt.Close() }()
+
+	count := 0
+
+	for mbid, credit := range scan.refs {
+		if _, stored := written[credit]; !stored {
+			continue
+		}
+
+		id := mbid
+
+		if _, err := stmt.ExecContext(ctx, id[:], credit); err != nil {
+			return 0, fmt.Errorf("credit import: insert ref: %w", err)
+		}
+
+		count++
+	}
+
+	return count, nil
+}

backend/explore/dumpimport.go

@@ -104,6 +104,7 @@ type dumpImporter struct {
 
 	canonicalBaseURL string
 	listensBaseURL   string
+	mbdumpBaseURL    string
 
 	// Disk safety floors (fields so tests can relax them).
 	minStartFreeBytes uint64
@@ -144,6 +145,7 @@ func newDumpImporter(si *SearchIndex, lb *ListenBrainzClient) (*dumpImporter, er
 		stagingDir:        stagingDir,
 		canonicalBaseURL:  defaultCanonicalBaseURL,
 		listensBaseURL:    defaultListensBaseURL,
+		mbdumpBaseURL:     defaultMBDumpBaseURL,
 		minStartFreeBytes: dumpMinStartFreeBytes,
 		abortFreeBytes:    dumpAbortFreeBytes,
 	}, nil
@@ -171,6 +173,7 @@ func (imp *dumpImporter) run(ctx context.Context) error {
 	// Fast path: rows already assembled, only patch passes remain.
 	if state.Stage == dumpStageAssembled {
 		imp.si.MarkReadyIfPopulated()
+		imp.ensureArtistCredits(ctx)
 		imp.runPatchPasses(ctx)
 
 		if err := ctx.Err(); err != nil {
@@ -305,6 +308,11 @@ func (imp *dumpImporter) run(ctx context.Context) error {
 	imp.si.MarkReadyIfPopulated()
 	imp.si.refreshStatusCounts()
 
+	// Multi-artist credits, from a different dump.  After the catalog,
+	// because it asks explore_index which entities are worth carrying
+	// credits for.
+	imp.ensureArtistCredits(ctx)
+
 	// Stage 4: API patch passes (idempotent).
 	imp.runPatchPasses(ctx)
 

backend/explore/explore.go

@@ -9,7 +9,6 @@ import (
 	"sync"
 	"time"
 
-	"github.com/wailsapp/wails/v3/pkg/application"
 	"golang.org/x/sync/singleflight"
 
 	"yellowjacket/backend/database"
@@ -144,19 +143,9 @@ func (e *Service) CAALimiter() *RateLimiter {
 	return e.caaLimiter
 }
 
-// ServiceStartup is v3's service lifecycle hook: it runs once the
-// runtime exists, and ctx is cancelled when the app shuts down.  It
-// replaces v2's SetContext, which had to be called by hand from
-// OnStartup and was exported, so it was also bound to the frontend.
-func (e *Service) ServiceStartup(
-	ctx context.Context,
-	_ application.ServiceOptions,
-) error {
-	e.ctx = ctx
-	e.index.SetContext(ctx)
-
-	return nil
-}
+// The v3 service lifecycle hook that fills e.ctx lives in
+// servicestartup.go, behind a build tag: naming
+// application.ServiceOptions is what would drag cgo into cmd/indexbuild.
 
 // StartIndexBuild kicks off the background search index build.
 // Call this after the library scan completes so the indexer doesn't

backend/explore/netpolicy.go

@@ -0,0 +1,137 @@
+package explore
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"sync"
+)
+
+// Whether the catalog artifact may be downloaded on this connection
+// (plan 016 B4).
+//
+// The artifact is ~0.6 GB. On a desktop that is a minute of someone
+// else's bandwidth; on a phone it can be a month's allowance, and the
+// app had no awareness of the difference at all.
+//
+// Three decisions shape this file.
+//
+// **The policy lives here and the platform call does not.** `explore` is
+// imported by `cmd/indexbuild`, which is built with `CGO_ENABLED=0` in a
+// plain Go container, so naming `application` here would break the one
+// job that must not fail (see `TestIndexToolsDoNotImportWails`). What is
+// injected is a closure; what is *tested* is the parsing and the
+// decision, on every platform.
+//
+// **An unknown answer is not a metered one.** Only mobile answers this
+// question — the desktop stub returns an empty string — so a policy that
+// treated silence as "metered" would refuse the download on every
+// desktop in the world. Silence means "no reason to refuse".
+//
+// **Cellular is the signal, and it is the only one available.** Wails
+// reports `{"connected":bool,"type":"wifi|cellular|ethernet|none"}` and
+// no metered flag, so a metered *wifi* — a phone hotspot, a hotel — is
+// invisible to us and will not be refused. That is a known gap rather
+// than an oversight: Android knows (`NET_CAPABILITY_NOT_METERED`) and
+// the runtime does not pass it on.
+
+// ErrMeteredNetwork is returned instead of downloading the catalog when
+// the connection looks metered and the user has not opted in. Every
+// failure path in `tryCoreArtifact` is already non-fatal, so this
+// behaves like any other reason the artifact is not available yet.
+var ErrMeteredNetwork = errors.New(
+	"explore: catalog download declined on a metered connection",
+)
+
+// Network is what the platform can say about the connection.
+type Network struct {
+	// Known is false when nothing answered — every desktop, and any
+	// mobile build whose bridge is not up yet.
+	Known bool
+	// Connected reports a usable connection of any kind.
+	Connected bool
+	// Metered reports a connection the user is plausibly paying for by
+	// the byte. See the note above on what this cannot see.
+	Metered bool
+}
+
+// NetworkProbe answers "what kind of connection is this", or an unknown
+// Network when the platform does not say.
+type NetworkProbe func() Network
+
+// ParseNetworkJSON reads the runtime's network payload.
+//
+// Anything unparseable is `Known: false` rather than an error: this
+// decides whether to *skip* an optional download, and a malformed
+// payload is not a reason to refuse one.
+func ParseNetworkJSON(payload string) Network {
+	var raw struct {
+		Connected bool   `json:"connected"`
+		Type      string `json:"type"`
+	}
+
+	if strings.TrimSpace(payload) == "" {
+		return Network{}
+	}
+
+	if err := json.Unmarshal([]byte(payload), &raw); err != nil {
+		return Network{}
+	}
+
+	return Network{
+		Known:     true,
+		Connected: raw.Connected,
+		Metered:   strings.EqualFold(raw.Type, "cellular"),
+	}
+}
+
+// networkPolicy is the injected half: how to ask, and whether the user
+// has said yes anyway.
+type networkPolicy struct {
+	mu           sync.RWMutex
+	probe        NetworkProbe
+	allowMetered func() bool
+}
+
+func (p *networkPolicy) set(probe NetworkProbe, allowMetered func() bool) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	p.probe = probe
+	p.allowMetered = allowMetered
+}
+
+// refuses reports whether a large optional download should be skipped.
+func (p *networkPolicy) refuses() bool {
+	p.mu.RLock()
+	probe, allow := p.probe, p.allowMetered
+	p.mu.RUnlock()
+
+	if probe == nil {
+		return false
+	}
+
+	if allow != nil && allow() {
+		return false
+	}
+
+	state := probe()
+
+	return state.Known && state.Metered
+}
+
+// SetNetworkPolicy wires how the catalog download decides whether this
+// connection is one to spend 0.6 GB on. Both arguments may be nil, which
+// is the desktop's answer: never refuse.
+//
+//wails:ignore // internal wiring, not part of the app's IPC surface.
+func (si *SearchIndex) SetNetworkPolicy(probe NetworkProbe, allowMetered func() bool) {
+	si.netPolicy.set(probe, allowMetered)
+}
+
+// SetNetworkPolicy wires the metered-connection policy into the index.
+//
+//wails:ignore // internal wiring, not part of the app's IPC surface.
+func (e *Service) SetNetworkPolicy(probe NetworkProbe, allowMetered func() bool) {
+	e.index.SetNetworkPolicy(probe, allowMetered)
+}

backend/explore/netpolicy_test.go

@@ -0,0 +1,158 @@
+package explore
+
+import (
+	"errors"
+	"testing"
+)
+
+// The catalog is ~0.6 GB and the decision not to fetch it is the only
+// part of plan 016 B4 that can be tested anywhere but on a phone: the
+// platform call is a one-line closure injected from app.go, and
+// everything that decides anything is here.
+
+func TestParseNetworkJSON(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		payload string
+		want    Network
+	}{{
+		name:    "cellular is metered",
+		payload: `{"connected":true,"type":"cellular"}`,
+		want:    Network{Known: true, Connected: true, Metered: true},
+	}, {
+		name:    "wifi is not",
+		payload: `{"connected":true,"type":"wifi"}`,
+		want:    Network{Known: true, Connected: true},
+	}, {
+		name:    "ethernet is not",
+		payload: `{"connected":true,"type":"ethernet"}`,
+		want:    Network{Known: true, Connected: true},
+	}, {
+		name:    "the case is the platform's business, not ours",
+		payload: `{"connected":true,"type":"Cellular"}`,
+		want:    Network{Known: true, Connected: true, Metered: true},
+	}, {
+		name:    "offline is known and unmetered",
+		payload: `{"connected":false,"type":"none"}`,
+		want:    Network{Known: true},
+	}, {
+		// The desktop stub. This is the case that must not read as
+		// "metered": every desktop in the world answers this way.
+		name:    "an empty payload is unknown",
+		payload: "",
+		want:    Network{},
+	}, {
+		name:    "so is a malformed one",
+		payload: `{"connected":`,
+		want:    Network{},
+	}}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			if got := ParseNetworkJSON(tt.payload); got != tt.want {
+				t.Errorf("ParseNetworkJSON(%q) = %+v, want %+v", tt.payload, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestNetworkPolicyRefuses(t *testing.T) {
+	t.Parallel()
+
+	cellular := func() Network {
+		return Network{Known: true, Connected: true, Metered: true}
+	}
+	wifi := func() Network { return Network{Known: true, Connected: true} }
+	unknown := func() Network { return Network{} }
+	yes := func() bool { return true }
+	no := func() bool { return false }
+
+	tests := []struct {
+		name         string
+		probe        NetworkProbe
+		allowMetered func() bool
+		want         bool
+	}{{
+		name:  "no probe wired refuses nothing",
+		probe: nil,
+		want:  false,
+	}, {
+		name:  "an unknown connection refuses nothing",
+		probe: unknown,
+		want:  false,
+	}, {
+		name:  "wifi refuses nothing",
+		probe: wifi,
+		want:  false,
+	}, {
+		name:  "cellular refuses by default",
+		probe: cellular,
+		want:  true,
+	}, {
+		name:         "cellular with no permission refuses",
+		probe:        cellular,
+		allowMetered: no,
+		want:         true,
+	}, {
+		name:         "cellular the user opted into does not",
+		probe:        cellular,
+		allowMetered: yes,
+		want:         false,
+	}, {
+		// The permission is read at decision time rather than captured,
+		// so turning it on takes effect on the next attempt instead of
+		// the next launch.
+		name:         "permission is asked, not remembered",
+		probe:        cellular,
+		allowMetered: yes,
+		want:         false,
+	}}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var p networkPolicy
+
+			p.set(tt.probe, tt.allowMetered)
+
+			if got := p.refuses(); got != tt.want {
+				t.Errorf("refuses() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+// The gate has to come before anything is staged: a declined download is
+// a no-op, not a job in the indicator or a status the user must dismiss.
+func TestTryCoreArtifactDeclinesMeteredWithoutStaging(t *testing.T) {
+	t.Parallel()
+
+	si := &SearchIndex{}
+
+	si.SetNetworkPolicy(
+		func() Network { return Network{Known: true, Connected: true, Metered: true} },
+		nil,
+	)
+
+	err := si.tryCoreArtifact(t.Context())
+
+	if !errors.Is(err, ErrMeteredNetwork) {
+		t.Fatalf("tryCoreArtifact() error = %v, want ErrMeteredNetwork", err)
+	}
+
+	// Nothing announced itself: no build status, no tiers, no job. A
+	// SearchIndex with no database would panic on any of the work below
+	// the gate, which is itself part of the assertion.
+	if si.buildStatus.Building {
+		t.Error("declining a metered download still reported a build in progress")
+	}
+
+	if len(si.buildStatus.Tiers) != 0 {
+		t.Errorf("declining staged %d tiers, want none", len(si.buildStatus.Tiers))
+	}
+}

backend/explore/searchindex.go

@@ -212,6 +212,11 @@ type SearchIndex struct {
 	cancel context.CancelFunc
 	done   chan struct{}
 
+	// netPolicy decides whether this connection is one to spend ~0.6 GB
+	// of catalog on. Its own lock: it is written once at startup and read
+	// from the build goroutine (netpolicy.go).
+	netPolicy networkPolicy
+
 	mu    sync.RWMutex
 	ready bool
 

backend/explore/servicestartup.go

@@ -0,0 +1,30 @@
+//go:build !indexbuild
+
+package explore
+
+import (
+	"context"
+
+	"github.com/wailsapp/wails/v3/pkg/application"
+)
+
+// ServiceStartup is v3's service lifecycle hook: it runs once the
+// runtime exists, and ctx is cancelled when the app shuts down.  It
+// replaces v2's SetContext, which had to be called by hand from
+// OnStartup and was exported, so it was also bound to the frontend.
+//
+// It is the one thing in this package that names the Wails application,
+// and it is behind a build tag for the reason
+// backend/events/runtime_wails.go states: cmd/indexbuild imports this
+// package and is built without cgo, GTK or WebKit.  Nothing under the
+// indexbuild tag runs a Wails app, so the hook — and the context it
+// installs — is simply absent there.
+func (e *Service) ServiceStartup(
+	ctx context.Context,
+	_ application.ServiceOptions,
+) error {
+	e.ctx = ctx
+	e.index.SetContext(ctx)
+
+	return nil
+}

backend/frontendutil/browse.go

@@ -0,0 +1,181 @@
+package frontendutil
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"sort"
+)
+
+// errNotADirectory is returned when a caller asks to list something
+// that exists but is not a directory.
+var errNotADirectory = errors.New("not a directory")
+
+// DirEntry is one selectable directory in a listing.
+type DirEntry struct {
+	Name string `json:"name"`
+	Path string `json:"path"`
+}
+
+// DirListing is one level of the filesystem, as a folder picker needs
+// it: where we are, what is above, and the directories below.
+//
+// Parent is empty at a root, which is what tells the UI not to draw an
+// "up" affordance rather than having it compute that from the path
+// separator.
+type DirListing struct {
+	Path    string     `json:"path"`
+	Parent  string     `json:"parent"`
+	Entries []DirEntry `json:"entries"`
+}
+
+// ListDirectories returns the directories directly inside path, so the
+// frontend can draw a folder picker.
+//
+// **It exists because Android has no directory picker.** Wails' file
+// dialog can choose directories on every desktop platform, and on
+// Android it returns an error: the Storage Access Framework yields tree
+// URIs rather than filesystem paths, and a path is what this app's
+// entire library model is keyed on. Rather than teach the backend about
+// tree URIs, the app browses the filesystem itself — which it can do
+// because it holds all-files access (see the manifest).
+//
+// Three rules, each of which a picker gets wrong if it is not stated:
+// only directories are returned, because the caller is choosing a
+// library root and files are noise; unreadable children are skipped
+// rather than failing the whole listing, since Android's storage root
+// contains directories no app may enter; and hidden directories are
+// omitted, because a music library is not in one and `.thumbnails`
+// alone would swamp the list.
+func (fe *FrontendUtil) ListDirectories(path string) (DirListing, error) {
+	if path == "" {
+		path = fe.DefaultBrowseRoot()
+	}
+
+	path = filepath.Clean(path)
+
+	info, err := os.Stat(path)
+	if err != nil {
+		return DirListing{}, fmt.Errorf("could not open %s: %w", path, err)
+	}
+
+	if !info.IsDir() {
+		return DirListing{}, fmt.Errorf("%w: %s", errNotADirectory, path)
+	}
+
+	entries, err := os.ReadDir(path)
+	if err != nil {
+		return DirListing{}, fmt.Errorf("could not read %s: %w", path, err)
+	}
+
+	dirs := make([]DirEntry, 0, len(entries))
+
+	for _, e := range entries {
+		name := e.Name()
+		if name == "" || name[0] == '.' {
+			continue
+		}
+
+		// A symlink reports itself, not its target, so ask the
+		// filesystem: a symlinked music directory is ordinary and
+		// skipping it would be a bug the user cannot explain.
+		child := filepath.Join(path, name)
+
+		info, err := os.Stat(child)
+		if err != nil || !info.IsDir() {
+			continue
+		}
+
+		dirs = append(dirs, DirEntry{Name: name, Path: child})
+	}
+
+	sort.Slice(dirs, func(i, j int) bool { return dirs[i].Name < dirs[j].Name })
+
+	parent := filepath.Dir(path)
+	if parent == path {
+		parent = ""
+	}
+
+	return DirListing{Path: path, Parent: parent, Entries: dirs}, nil
+}
+
+// androidSharedStorage is where a user's music lives on Android. It is
+// not derivable from the environment the way a desktop home directory
+// is: HOME inside an Android app process is "/", so os.UserHomeDir()
+// would start the picker at the filesystem root with nothing readable
+// under it.
+const androidSharedStorage = "/storage/emulated/0"
+
+// DefaultBrowseRoot is where a folder picker should open.
+func (fe *FrontendUtil) DefaultBrowseRoot() string {
+	if runtime.GOOS == "android" {
+		for _, candidate := range []string{androidSharedStorage, "/storage"} {
+			if info, err := os.Stat(candidate); err == nil && info.IsDir() {
+				return candidate
+			}
+		}
+
+		return "/"
+	}
+
+	if home, err := os.UserHomeDir(); err == nil && home != "" {
+		return home
+	}
+
+	return string(filepath.Separator)
+}
+
+// StorageAccess reports whether the app can actually read the place the
+// user's music lives.
+type StorageAccess struct {
+	Root     string `json:"root"`
+	Readable bool   `json:"readable"`
+	Reason   string `json:"reason"`
+}
+
+// CheckStorageAccess asks the filesystem rather than the permission
+// system.
+//
+// On Android this app holds MANAGE_EXTERNAL_STORAGE, which the user
+// grants on a Settings screen rather than in a dialog — so it can be
+// refused, revoked later, or simply never answered, and the permission
+// API is one more thing that can disagree with reality. Reading the
+// directory is the question the library scanner will actually ask, so
+// it is the one worth answering.
+//
+// It is deliberately not an error return: "we cannot read your music
+// yet" is a state the UI renders, not a failure of the call.
+func (fe *FrontendUtil) CheckStorageAccess() StorageAccess {
+	root := fe.DefaultBrowseRoot()
+
+	if _, err := os.ReadDir(root); err != nil {
+		return StorageAccess{
+			Root:     root,
+			Readable: false,
+			Reason:   err.Error(),
+		}
+	}
+
+	return StorageAccess{Root: root, Readable: true}
+}
+
+// HasNativeDirectoryPicker reports whether this platform can open a
+// directory dialog at all.
+//
+// It is asked of the backend rather than tested in the frontend with
+// `System.IsAndroid()`, for three reasons. The dialog *is* backend code
+// — `DirectoryPicker` above — so this is the same package saying what
+// it can do. It answers for iOS too without the frontend enumerating
+// platforms. And it makes the frontend's fallback testable through the
+// ordinary transport fake instead of a module mock of the Wails
+// runtime, whose platform helpers read build constants.
+func (fe *FrontendUtil) HasNativeDirectoryPicker() bool {
+	switch runtime.GOOS {
+	case "android", "ios":
+		return false
+	default:
+		return true
+	}
+}

backend/frontendutil/browse_test.go

@@ -0,0 +1,207 @@
+package frontendutil
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+)
+
+// listing helper: a tree with the three shapes the picker has to get
+// right — an ordinary directory, a file (never listed), and a hidden
+// directory (never listed).
+func browseFixture(t *testing.T) string {
+	t.Helper()
+
+	root := t.TempDir()
+
+	for _, dir := range []string{"Music", "Podcasts", "aaa", ".thumbnails"} {
+		if err := os.Mkdir(filepath.Join(root, dir), 0o755); err != nil {
+			t.Fatalf("mkdir %s: %v", dir, err)
+		}
+	}
+
+	if err := os.WriteFile(filepath.Join(root, "track.mp3"), []byte("x"), 0o600); err != nil {
+		t.Fatalf("write file: %v", err)
+	}
+
+	return root
+}
+
+func TestListDirectories(t *testing.T) {
+	fe := &FrontendUtil{}
+	root := browseFixture(t)
+
+	got, err := fe.ListDirectories(root)
+	if err != nil {
+		t.Fatalf("ListDirectories: %v", err)
+	}
+
+	// Sorted, directories only, no file and no dotted entry.
+	want := []string{"Music", "Podcasts", "aaa"}
+	if len(got.Entries) != len(want) {
+		t.Fatalf("got %d entries %v, want %v", len(got.Entries), got.Entries, want)
+	}
+
+	for i, w := range want {
+		if got.Entries[i].Name != w {
+			t.Errorf("entry %d = %q, want %q", i, got.Entries[i].Name, w)
+		}
+
+		if got.Entries[i].Path != filepath.Join(root, w) {
+			t.Errorf("entry %d path = %q, want %q", i, got.Entries[i].Path, filepath.Join(root, w))
+		}
+	}
+
+	if got.Path != root {
+		t.Errorf("Path = %q, want %q", got.Path, root)
+	}
+
+	if got.Parent != filepath.Dir(root) {
+		t.Errorf("Parent = %q, want %q", got.Parent, filepath.Dir(root))
+	}
+}
+
+// A symlink reports itself rather than its target, so a listing that
+// trusts DirEntry.IsDir() silently drops a symlinked music folder --
+// which is an ordinary thing to have and an unexplainable thing to
+// lose.
+func TestListDirectoriesFollowsSymlinks(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symlinks need elevation on Windows")
+	}
+
+	root := t.TempDir()
+	target := filepath.Join(root, "real")
+
+	if err := os.Mkdir(target, 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+
+	link := filepath.Join(root, "linked")
+	if err := os.Symlink(target, link); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+
+	fe := &FrontendUtil{}
+
+	got, err := fe.ListDirectories(root)
+	if err != nil {
+		t.Fatalf("ListDirectories: %v", err)
+	}
+
+	if len(got.Entries) != 2 {
+		t.Fatalf("got %v, want both 'linked' and 'real'", got.Entries)
+	}
+}
+
+// A dangling symlink, and anything else os.Stat refuses, must be
+// skipped rather than failing the whole listing: Android's storage
+// root holds directories no app may enter, and one of them must not
+// cost the user the picker.
+func TestListDirectoriesSkipsUnreadable(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symlinks need elevation on Windows")
+	}
+
+	root := t.TempDir()
+	if err := os.Mkdir(filepath.Join(root, "good"), 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+
+	dangling := filepath.Join(root, "dangling")
+	if err := os.Symlink(filepath.Join(root, "nowhere"), dangling); err != nil {
+		t.Fatalf("symlink: %v", err)
+	}
+
+	fe := &FrontendUtil{}
+
+	got, err := fe.ListDirectories(root)
+	if err != nil {
+		t.Fatalf("ListDirectories: %v", err)
+	}
+
+	if len(got.Entries) != 1 || got.Entries[0].Name != "good" {
+		t.Errorf("got %v, want only 'good'", got.Entries)
+	}
+}
+
+func TestListDirectoriesRejectsFiles(t *testing.T) {
+	root := t.TempDir()
+
+	file := filepath.Join(root, "track.mp3")
+	if err := os.WriteFile(file, []byte("x"), 0o600); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	fe := &FrontendUtil{}
+
+	if _, err := fe.ListDirectories(file); err == nil {
+		t.Error("listing a file should be an error")
+	}
+
+	if _, err := fe.ListDirectories(filepath.Join(root, "missing")); err == nil {
+		t.Error("listing a missing path should be an error")
+	}
+}
+
+// An empty path means "start where the picker should open", so the
+// frontend never has to know the platform.
+func TestListDirectoriesDefaultsToBrowseRoot(t *testing.T) {
+	fe := &FrontendUtil{}
+
+	got, err := fe.ListDirectories("")
+	if err != nil {
+		t.Skipf("default root not listable in this environment: %v", err)
+	}
+
+	if got.Path != fe.DefaultBrowseRoot() {
+		t.Errorf("Path = %q, want the default root %q", got.Path, fe.DefaultBrowseRoot())
+	}
+}
+
+// Parent is empty at a root, which is what tells the picker not to draw
+// an "up" control rather than making it reason about separators.
+func TestListDirectoriesRootHasNoParent(t *testing.T) {
+	fe := &FrontendUtil{}
+
+	got, err := fe.ListDirectories(string(filepath.Separator))
+	if err != nil {
+		t.Skipf("filesystem root not listable: %v", err)
+	}
+
+	if got.Parent != "" {
+		t.Errorf("Parent = %q at the root, want empty", got.Parent)
+	}
+}
+
+func TestCheckStorageAccess(t *testing.T) {
+	fe := &FrontendUtil{}
+
+	got := fe.CheckStorageAccess()
+	if got.Root == "" {
+		t.Error("Root should never be empty")
+	}
+
+	// The developer machine running this test can read its own home
+	// directory; the assertion is that the two fields agree, not that
+	// access is granted.
+	if got.Readable && got.Reason != "" {
+		t.Errorf("readable but Reason = %q", got.Reason)
+	}
+
+	if !got.Readable && got.Reason == "" {
+		t.Error("not readable but no Reason given")
+	}
+}
+
+// The picker's fallback is chosen from this, so a platform that gains
+// a working dialog must flip it here rather than in the frontend.
+func TestHasNativeDirectoryPicker(t *testing.T) {
+	fe := &FrontendUtil{}
+
+	want := runtime.GOOS != "android" && runtime.GOOS != "ios"
+	if got := fe.HasNativeDirectoryPicker(); got != want {
+		t.Errorf("HasNativeDirectoryPicker() on %s = %v, want %v", runtime.GOOS, got, want)
+	}
+}

backend/library/library.go

@@ -289,8 +289,13 @@ 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(
-		ScanConcurrencyAuto,
+		l.conf.ScanConcurrency,
 		libraryPath,
 	)
 
@@ -300,6 +305,10 @@ 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.
@@ -818,7 +827,7 @@ func (l *Library) scanInternal(
 	g := new(errgroup.Group)
 	g.SetLimit(workerCount)
 
-	for work := range workChan {
+	for work := range readaheadWork(scanCtx, workChan, diskProfile) {
 		g.Go(func() error {
 			if err := l.waitIfPaused(scanCtx); err != nil {
 				return err
@@ -1285,9 +1294,101 @@ func surveyAudioFiles(
 	return count, maxModTime
 }
 
-// hddWorkerCount is the maximum number of concurrent extraction
-// workers when the library resides on a spinning disk.
-const hddWorkerCount = 2
+// How many extraction workers a spinning disk gets, and why it is two
+// numbers rather than one.
+//
+// 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
@@ -1296,20 +1397,45 @@ 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:
-		return goruntime.NumCPU()
+		spinning = false
 	case ScanConcurrencyHDD:
-		return min(hddWorkerCount, goruntime.NumCPU())
-	default: // auto
-		if system.IsRotationalDisk(libraryPath) {
-			return min(
-				hddWorkerCount, goruntime.NumCPU(),
-			)
-		}
-
-		return goruntime.NumCPU()
+		spinning = true
+	case ScanConcurrencyAuto:
 	}
+
+	if !spinning {
+		return cpus
+	}
+
+	workers := hddWorkerCountSerial
+	if profile.Queues() {
+		workers = hddWorkerCountQueued
+	}
+
+	return min(workers, cpus)
 }
 
 // scanWork represents a file to be processed by a worker.

backend/library/readahead_linux.go

@@ -0,0 +1,38 @@
+//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,
+	)
+}

backend/library/readahead_other.go

@@ -0,0 +1,13 @@
+//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) {}

backend/library/scan_workers_test.go

@@ -0,0 +1,122 @@
+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")
+	}
+}

backend/mediacontrols/android.go

@@ -0,0 +1,215 @@
+//go:build android
+
+// Android's answer to MPRIS is a MediaSession, and reaching it needs no
+// new JNI: Wails exports application.Android.StartForegroundService(json)
+// going out, and Java's WailsBridge.emitEvent lands on the application
+// event bus coming back. So this handler is one JSON payload pushed to
+// the foreground service and one command event read from it. The Java
+// half is
+// build/android/app/src/main/java/com/wails/app/WailsForegroundService.java
+// and the payload keys below are its contract.
+
+package mediacontrols
+
+import (
+	"errors"
+	"log/slog"
+	"sync"
+
+	"github.com/wailsapp/wails/v3/pkg/application"
+)
+
+// commandEvent is the event name the Java side emits transport
+// commands on. It is a plain string on both sides; changing it means
+// changing WailsForegroundService too.
+const commandEvent = "yj:media:command"
+
+var errNoApplication = errors.New(
+	"no running application to attach media controls to",
+)
+
+// androidHandler drives the media notification, the lock-screen
+// transport and audio focus through the foreground service.
+type androidHandler struct {
+	logger *slog.Logger
+
+	mu          sync.Mutex
+	callbacks   Callbacks
+	meta        Metadata
+	state       PlaybackState
+	positionSec int
+
+	// running tracks whether the foreground service has been started.
+	// Android 12+ forbids starting one from the background, so it is
+	// started when playback starts -- a user action, in a visible app
+	// -- and stopped only when playback stops, which is what keeps
+	// queue auto-advance working with the screen off.
+	running bool
+
+	// lastPayload is the last JSON sent. An unchanged payload is not
+	// an event here either: every push crosses JNI and re-delivers an
+	// Intent, and the player pushes state on several paths that can
+	// agree.
+	lastPayload string
+
+	unsubscribe func()
+}
+
+// NewHandler returns the Android media-session handler.
+func NewHandler(logger *slog.Logger) Handler {
+	return &androidHandler{logger: logger, state: StateStopped}
+}
+
+// Init subscribes to the transport commands the Java side emits.
+func (a *androidHandler) Init(callbacks Callbacks) error {
+	app := application.Get()
+	if app == nil {
+		return errNoApplication
+	}
+
+	a.mu.Lock()
+	a.callbacks = callbacks
+	a.mu.Unlock()
+
+	a.unsubscribe = app.Event.On(commandEvent, a.onCommand)
+
+	return nil
+}
+
+// onCommand dispatches one transport command from the notification,
+// the lock screen, a headset button or an audio-focus change.
+//
+// Every callback runs on its own goroutine, for the reason the MPRIS
+// handler does the same: they take the player and queue mutexes, and
+// this runs on the event processor's dispatch goroutine.
+func (a *androidHandler) onCommand(event *application.CustomEvent) {
+	data, ok := event.Data.(map[string]any)
+	if !ok {
+		return
+	}
+
+	command := parseMediaCommand(data)
+
+	a.mu.Lock()
+	cb := a.callbacks
+	a.mu.Unlock()
+
+	switch command.name {
+	case cmdPlay:
+		run(cb.OnPlay)
+	case cmdPause:
+		run(cb.OnPause)
+	case cmdPlayPause:
+		run(cb.OnPlayPause)
+	case cmdStop:
+		run(cb.OnStop)
+	case cmdNext:
+		run(cb.OnNext)
+	case cmdPrevious:
+		run(cb.OnPrevious)
+	case cmdSeek:
+		if cb.OnSeek != nil {
+			go cb.OnSeek(command.positionSec)
+		}
+	case cmdDuck:
+		if cb.OnDuck != nil {
+			go cb.OnDuck(command.duck)
+		}
+	default:
+		a.logger.Warn("Unknown media command", "command", command.name)
+	}
+}
+
+// run invokes a callback on its own goroutine, tolerating a nil one.
+func run(fn func()) {
+	if fn != nil {
+		go fn()
+	}
+}
+
+// UpdateMetadata pushes new track details to the notification.
+func (a *androidHandler) UpdateMetadata(meta Metadata) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	a.meta = meta
+	a.push()
+}
+
+// UpdatePlaybackState pushes the state and a fresh position anchor;
+// the MediaSession interpolates from there while playing.
+func (a *androidHandler) UpdatePlaybackState(
+	state PlaybackState,
+	positionSec int,
+) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	a.state = state
+	a.positionSec = positionSec
+	a.push()
+}
+
+// NotifySeek re-anchors the position. Unlike MPRIS, a MediaSession has
+// no separate seeked signal -- a new state with a new position is the
+// whole mechanism.
+func (a *androidHandler) NotifySeek(positionSec int) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	a.positionSec = positionSec
+	a.push()
+}
+
+// UpdateVolume is deliberately a no-op. Android's volume keys act on
+// the media stream, which the OS owns; an app that also moved its own
+// volume in response would move it twice.
+func (a *androidHandler) UpdateVolume(_ float64) {}
+
+// Close stops the service and drops the command subscription.
+func (a *androidHandler) Close() {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if a.unsubscribe != nil {
+		a.unsubscribe()
+		a.unsubscribe = nil
+	}
+
+	if a.running {
+		application.Android.StopForegroundService()
+		a.running = false
+	}
+}
+
+// push sends the current state to the Java side, if it has changed.
+// The caller holds a.mu.
+func (a *androidHandler) push() {
+	if a.state == StateStopped {
+		// Nothing is playing, so nothing justifies an ongoing
+		// notification or the process staying alive.
+		if a.running {
+			application.Android.StopForegroundService()
+			a.running = false
+			a.lastPayload = ""
+		}
+
+		return
+	}
+
+	payload, err := mediaPayload(a.meta, a.state, a.positionSec)
+	if err != nil {
+		a.logger.Error("Failed to encode media payload", "err", err)
+
+		return
+	}
+
+	if payload == a.lastPayload {
+		return
+	}
+
+	a.lastPayload = payload
+	a.running = true
+
+	application.Android.StartForegroundService(payload)
+}

backend/mediacontrols/androidpayload.go

@@ -0,0 +1,85 @@
+// The contract between the Android handler and the Java
+// WailsForegroundService is two JSON documents -- one pushed out with
+// the track and the state, one read back with a transport command --
+// and neither side can check the other.
+//
+// It lives here, *without* the android build tag, so that `go test` on
+// any platform exercises it. android.go itself can only be compiled by
+// a cross-compiler and only be run by a phone, so anything left in it
+// is untested by construction; this is the half worth not leaving
+// there.
+
+package mediacontrols
+
+import "encoding/json"
+
+// Media command names, as the Java side spells them.
+const (
+	cmdPlay      = "play"
+	cmdPause     = "pause"
+	cmdPlayPause = "playpause"
+	cmdStop      = "stop"
+	cmdNext      = "next"
+	cmdPrevious  = "previous"
+	cmdSeek      = "seek"
+	cmdDuck      = "duck"
+)
+
+// stateNames are what the payload's "state" key carries. Words rather
+// than the PlaybackState integers, because the Java side reads them as
+// JSON and a renumbered constant would silently mean something else
+// there.
+var stateNames = map[PlaybackState]string{
+	StateStopped: "stopped",
+	StatePlaying: "playing",
+	StatePaused:  "paused",
+}
+
+// mediaCommand is one transport command from the notification, the
+// lock screen, a headset button or an audio-focus change.
+type mediaCommand struct {
+	name        string
+	positionSec int
+	duck        bool
+}
+
+// mediaPayload encodes the state the notification and MediaSession
+// render.
+func mediaPayload(
+	meta Metadata,
+	state PlaybackState,
+	positionSec int,
+) (string, error) {
+	payload, err := json.Marshal(map[string]any{
+		"title":       meta.Title,
+		"artist":      meta.Artist,
+		"album":       meta.Album,
+		"artPath":     meta.ArtFilePath,
+		"durationSec": meta.DurationSec,
+		"positionSec": positionSec,
+		"state":       stateNames[state],
+	})
+	if err != nil {
+		return "", err
+	}
+
+	return string(payload), nil
+}
+
+// parseMediaCommand reads one command out of the event payload.
+//
+// The numbers arrive as float64 because they came through
+// encoding/json as an untyped document -- asserting int here is the
+// way a seek silently becomes a seek to zero.
+func parseMediaCommand(data map[string]any) mediaCommand {
+	cmd := mediaCommand{}
+	cmd.name, _ = data["command"].(string)
+
+	if position, ok := data["positionSec"].(float64); ok {
+		cmd.positionSec = int(position)
+	}
+
+	cmd.duck, _ = data["on"].(bool)
+
+	return cmd
+}

backend/mediacontrols/androidpayload_test.go

@@ -0,0 +1,165 @@
+package mediacontrols
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// TestMediaPayloadKeys pins the document the Java side parses. The
+// keys are the contract: a rename here is silently a track with no
+// title on the lock screen, because WailsForegroundService reads them
+// with optString and a missing key is simply "".
+func TestMediaPayloadKeys(t *testing.T) {
+	t.Parallel()
+
+	payload, err := mediaPayload(Metadata{
+		Title:       "Tideline",
+		Artist:      "Sea Change",
+		Album:       "Ebb",
+		ArtFilePath: "/covers/ebb_lg.jpg",
+		DurationSec: 245,
+	}, StatePlaying, 30)
+	if err != nil {
+		t.Fatalf("mediaPayload: %v", err)
+	}
+
+	var got map[string]any
+	if err := json.Unmarshal([]byte(payload), &got); err != nil {
+		t.Fatalf("payload is not JSON: %v", err)
+	}
+
+	want := map[string]any{
+		"title":       "Tideline",
+		"artist":      "Sea Change",
+		"album":       "Ebb",
+		"artPath":     "/covers/ebb_lg.jpg",
+		"durationSec": float64(245),
+		"positionSec": float64(30),
+		"state":       "playing",
+	}
+
+	if len(got) != len(want) {
+		t.Errorf("payload has %d keys, want %d: %s", len(got), len(want), payload)
+	}
+
+	for key, expected := range want {
+		if got[key] != expected {
+			t.Errorf("payload[%q] = %v, want %v", key, got[key], expected)
+		}
+	}
+}
+
+// TestMediaPayloadStateNames covers the one value the Java side
+// compares against a literal.
+func TestMediaPayloadStateNames(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		state PlaybackState
+		want  string
+	}{
+		{StatePlaying, "playing"},
+		{StatePaused, "paused"},
+		{StateStopped, "stopped"},
+	}
+
+	for _, tt := range tests {
+		payload, err := mediaPayload(Metadata{}, tt.state, 0)
+		if err != nil {
+			t.Fatalf("mediaPayload: %v", err)
+		}
+
+		var got struct {
+			State string `json:"state"`
+		}
+
+		if err := json.Unmarshal([]byte(payload), &got); err != nil {
+			t.Fatalf("payload is not JSON: %v", err)
+		}
+
+		if got.State != tt.want {
+			t.Errorf("state %d encoded as %q, want %q", tt.state, got.State, tt.want)
+		}
+	}
+}
+
+// TestParseMediaCommand covers the direction that arrives untyped.
+// The seek case is the one with teeth: the position crosses as a JSON
+// number, so it is a float64 in the map and an int assertion would
+// make every seek a seek to zero.
+func TestParseMediaCommand(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		data map[string]any
+		want mediaCommand
+	}{
+		{
+			name: "play",
+			data: map[string]any{"command": "play"},
+			want: mediaCommand{name: cmdPlay},
+		},
+		{
+			name: "seek carries a position",
+			data: map[string]any{"command": "seek", "positionSec": float64(93)},
+			want: mediaCommand{name: cmdSeek, positionSec: 93},
+		},
+		{
+			name: "duck carries a flag",
+			data: map[string]any{"command": "duck", "on": true},
+			want: mediaCommand{name: cmdDuck, duck: true},
+		},
+		{
+			name: "unduck",
+			data: map[string]any{"command": "duck", "on": false},
+			want: mediaCommand{name: cmdDuck},
+		},
+		{
+			name: "a command with nothing in it is not a panic",
+			data: map[string]any{},
+			want: mediaCommand{},
+		},
+		{
+			name: "wrongly typed fields fall back to zero",
+			data: map[string]any{"command": "seek", "positionSec": "93"},
+			want: mediaCommand{name: cmdSeek},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			if got := parseMediaCommand(tt.data); got != tt.want {
+				t.Errorf("parseMediaCommand(%v) = %+v, want %+v", tt.data, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestMediaCommandNamesAreWhatJavaSends is a spelling check against
+// the Java side, which builds these strings by hand. It is a list, not
+// a mechanism: nothing can reach across into the .java file, so the
+// point is that changing one of these constants fails a test that
+// names the file to change with it.
+//
+// See build/android/app/src/main/java/com/wails/app/WailsForegroundService.java.
+func TestMediaCommandNamesAreWhatJavaSends(t *testing.T) {
+	t.Parallel()
+
+	want := []string{
+		"play", "pause", "playpause", "stop",
+		"next", "previous", "seek", "duck",
+	}
+	got := []string{
+		cmdPlay, cmdPause, cmdPlayPause, cmdStop,
+		cmdNext, cmdPrevious, cmdSeek, cmdDuck,
+	}
+
+	for i, name := range want {
+		if got[i] != name {
+			t.Errorf("command %d = %q, want %q", i, got[i], name)
+		}
+	}
+}

backend/mediacontrols/mediacontrols.go

@@ -34,6 +34,13 @@ type Callbacks struct {
 	OnPrevious  func()
 	OnSeek      func(positionSec int)
 	OnVolume    func(volume float64) // 0.0–1.0 linear scale.
+
+	// OnDuck asks for playback to be attenuated (true) or restored
+	// (false) without changing the user's volume. Android alone sends
+	// it, and only below API 26 -- from Oreo the audio framework ducks
+	// the app itself and reports no such focus change, so doing both
+	// would attenuate twice.
+	OnDuck func(ducked bool)
 }
 
 // Handler manages the OS media control integration.

backend/mediacontrols/mpris_linux.go

@@ -1,4 +1,11 @@
-//go:build linux
+//go:build linux && !android
+
+// MPRIS is a D-Bus desktop specification, and `android` implies the
+// `linux` build tag -- so without the `!android` this file compiled
+// into the Android app and went looking for a session bus that does
+// not exist. Desktop-Linux-only files need both halves; see Wails'
+// mobile guide, which names this as the Android analogue of
+// ios/darwin.
 
 package mediacontrols
 

backend/mediacontrols/stub.go

@@ -1,5 +1,10 @@
 //go:build !linux
 
+// Windows and macOS have no media-control integration yet. `!linux`
+// covers Android too without naming it, since `android` implies the
+// `linux` tag -- android.go claims it, mpris_linux.go excludes it, and
+// this file is left with the platforms neither wants.
+
 package mediacontrols
 
 import "log/slog"

backend/player/player.go

@@ -56,6 +56,13 @@ type Player struct {
 	trackChangeID           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.
+	// It is deliberately not persisted and emits no VolumeChanged: a
+	// duck is something the OS did for the length of a notification,
+	// not something the user chose.
+	duckAmount float64
+
 	// 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
@@ -793,12 +800,40 @@ func (p *Player) setVolumeLocked(desiredVolume UserVolume) {
 	speaker.Lock()
 
 	volume := clampVolume(desiredVolume)
-	p.volume.Volume = float64(volume.ToVolume())
+	p.volume.Volume = float64(volume.ToVolume()) - p.duckAmount
 	p.volume.Silent = volume == MinUserVol
 
 	speaker.Unlock()
 }
 
+// SetDuck attenuates playback (or restores it) without changing the
+// user's volume, for an OS that has asked us to get out of the way of
+// something short -- a navigation prompt, a notification tone.
+//
+// It re-applies the *user's* level through setVolumeLocked rather than
+// nudging the effect directly, so the offset cannot accumulate across
+// repeated ducks, and it neither emits nor persists: the level the user
+// set has not changed and the UI must not claim it has.
+//
+//wails:ignore // driven by OS audio focus, not by the frontend.
+func (p *Player) SetDuck(ducked bool) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	amount := 0.0
+	if ducked {
+		amount = duckAttenuation
+	}
+
+	if p.volume == nil || amount == p.duckAmount {
+		return
+	}
+
+	current := p.getUserVolume()
+	p.duckAmount = amount
+	p.setVolumeLocked(current)
+}
+
 // ChangeVolume adjusts the volume by a relative amount.
 func (p *Player) ChangeVolume(deltaVolume int) error {
 	p.mu.Lock()
@@ -812,7 +847,9 @@ func (p *Player) ChangeVolume(deltaVolume int) error {
 }
 
 func (p *Player) getUserVolume() UserVolume {
-	return Volume(p.volume.Volume).ToUserVolume()
+	// Undo any duck, so every caller -- the event, the persisted
+	// state, a relative change -- sees the level the user chose.
+	return Volume(p.volume.Volume + p.duckAmount).ToUserVolume()
 }
 
 // Muted reports whether playback is currently silenced.

backend/player/volume.go

@@ -19,6 +19,12 @@ const (
 	MaxVol Volume = 0
 )
 
+// duckAttenuation is how far playback drops when the OS asks us to
+// duck, on the same base-2 exponent scale: two steps is a quarter of
+// the amplitude (-12 dB), which is audible under a spoken notification
+// without sounding like a pause.
+const duckAttenuation = 2.0
+
 // ToVolume converts user volume to internal player volume.
 func (oldVol UserVolume) ToVolume() Volume {
 	var newVol Volume

backend/player/volume_test.go

@@ -1,9 +1,12 @@
 package player
 
 import (
+	"log/slog"
 	"math"
 	"testing"
 
+	"github.com/gopxl/beep/v2/effects"
+
 	"yellowjacket/backend/mediacontrols"
 )
 
@@ -202,3 +205,60 @@ func TestStateToMediaControls(t *testing.T) {
 		})
 	}
 }
+
+// TestSetDuck covers the property the duck rests on: the attenuation
+// is applied to the output and is invisible to everything that asks
+// what the volume is -- the event, the persisted state, a relative
+// change. Getting that wrong would let one notification tone
+// permanently rewrite the user's volume.
+func TestSetDuck(t *testing.T) {
+	t.Parallel()
+
+	p := NewPlayer(slog.Default(), nil)
+	p.volume = &effects.Volume{Base: 2}
+	p.setVolumeLocked(80)
+
+	unducked := p.volume.Volume
+
+	p.SetDuck(true)
+
+	if p.volume.Volume >= unducked {
+		t.Errorf(
+			"ducked output volume = %v, want less than %v",
+			p.volume.Volume, unducked,
+		)
+	}
+
+	if got := p.getUserVolume(); got != 80 {
+		t.Errorf("user volume while ducked = %d, want 80", got)
+	}
+
+	// A second duck must not stack: the offset is re-applied to the
+	// user's level, never subtracted again from the current output.
+	ducked := p.volume.Volume
+
+	p.SetDuck(true)
+
+	if p.volume.Volume != ducked {
+		t.Errorf(
+			"duck applied twice = %v, want %v", p.volume.Volume, ducked,
+		)
+	}
+
+	// Changing the volume while ducked keeps the attenuation.
+	p.setVolumeLocked(60)
+
+	if got := p.getUserVolume(); got != 60 {
+		t.Errorf("user volume set while ducked = %d, want 60", got)
+	}
+
+	if want := float64(UserVolume(60).ToVolume()) - duckAttenuation; p.volume.Volume != want {
+		t.Errorf("output while ducked = %v, want %v", p.volume.Volume, want)
+	}
+
+	p.SetDuck(false)
+
+	if want := float64(UserVolume(60).ToVolume()); p.volume.Volume != want {
+		t.Errorf("output after unduck = %v, want %v", p.volume.Volume, want)
+	}
+}

backend/system/disktype_linux.go

@@ -16,32 +16,107 @@ var errNoBlockDevice = errors.New(
 	"no matching block device found",
 )
 
-// IsRotationalDisk reports whether the block device backing the
-// given path is a rotational (spinning) disk.  Detection uses the
-// Linux sysfs interface at /sys/block/<dev>/queue/rotational.
-// Returns false on any error (assumes SSD).
-func IsRotationalDisk(path string) bool {
-	dev, err := deviceForPath(path)
-	if err != nil {
-		return false
-	}
+// 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, err := os.ReadFile(
-		filepath.Join(
-			"/sys/block", dev, "queue", "rotational",
-		),
-	)
-	if err != nil {
-		return false
-	}
+	// Rotational is /sys/block/<dev>/queue/rotational: true for a
+	// spinning disk, where a seek costs milliseconds.
+	Rotational bool
 
-	return strings.TrimSpace(string(rotational)) == "1"
+	// 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
 }
 
-// deviceForPath resolves a filesystem path to its underlying block
-// device name (e.g. "sda") by matching the device major:minor
-// from stat(2) against /sys/block/ entries.
-func deviceForPath(path string) (string, error) {
+// 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
+// error (assumes SSD).
+func IsRotationalDisk(path string) bool {
+	return ProfileForPath(path).Rotational
+}
+
+// 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 DiskProfile{
+		Device:     dev,
+		Rotational: sysfsInt(dev, "queue", "rotational") == 1,
+		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
+	}
+
+	n, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	if err != nil {
+		return 0
+	}
+
+	return n
+}
+
+// diskForPath resolves a filesystem path to the *whole disk* backing
+// it — "sdb" for a file on "sdb3".
+//
+// It goes through /sys/dev/block/<major>:<minor>, which the kernel
+// 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(
@@ -49,48 +124,50 @@ func deviceForPath(path string) (string, error) {
 		)
 	}
 
-	// Extract major and minor device numbers.
-	major := (st.Dev >> 8) & 0xff
-	minor := st.Dev & 0xff
+	// Linux packs dev_t as 12 bits of major and 20 of minor, split
+	// across the word.  Masking the low byte of each — which is what
+	// this used to do — is right only for the first 256 of either.
+	major := unixMajor(uint64(st.Dev))
+	minor := unixMinor(uint64(st.Dev))
 
-	// Scan /sys/block/ for a matching device.
-	entries, err := os.ReadDir("/sys/block")
+	link := filepath.Join(
+		"/sys/dev/block",
+		strconv.FormatUint(major, 10)+":"+
+			strconv.FormatUint(minor, 10),
+	)
+
+	target, err := filepath.EvalSymlinks(link)
 	if err != nil {
 		return "", fmt.Errorf(
-			"could not read /sys/block: %w", err,
+			"%w: %s (%w)", errNoBlockDevice, link, err,
 		)
 	}
 
-	majorStr := strconv.FormatUint(major, 10)
-	devStr := majorStr + ":" +
-		strconv.FormatUint(minor, 10)
+	// A partition's directory sits inside its disk's, and only the
+	// disk carries `queue`. Climb at most one level: sysfs nests a
+	// partition exactly one deep under its disk.
+	name := filepath.Base(target)
 
-	for _, entry := range entries {
-		devFile := filepath.Join(
-			"/sys/block", entry.Name(), "dev",
-		)
-
-		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
-		}
+	if _, err := os.Stat(filepath.Join(target, "queue")); err != nil {
+		name = filepath.Base(filepath.Dir(target))
 	}
 
-	return "", fmt.Errorf(
-		"%w for %s", errNoBlockDevice, devStr,
-	)
+	if name == "" || name == "." || name == string(filepath.Separator) {
+		return "", fmt.Errorf(
+			"%w for %d:%d", errNoBlockDevice, major, minor,
+		)
+	}
+
+	return name, nil
+}
+
+// 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))
 }

backend/system/disktype_other.go

@@ -2,9 +2,34 @@
 
 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{}
+}

backend/system/userdata.go

@@ -29,6 +29,29 @@ const (
 // without touching the current user's real config.toml or yj.db.
 const envHomeOverride = "YJ_HOME"
 
+// UseHomeOverride points every config and data path at base, by setting
+// the same override a development sandbox uses.
+//
+// It exists for mobile, where the switch in buildUserDirPath has no
+// answer: there is no home directory and no XDG, only a per-app private
+// directory the OS hands out at runtime. The caller is main(), which is
+// the only place that can ask the platform for it — deliberately, so
+// this package stays free of the Wails application package that knows
+// (see backend/events' indexbuild split for why that matters).
+//
+// Two rules. An empty base is a no-op, because that is exactly what
+// application.Mobile.StoragePath() returns on desktop. And an override
+// that is already set wins, so YJ_HOME on the command line still
+// relocates a sandbox on a platform that would otherwise decide for
+// itself.
+func UseHomeOverride(base string) {
+	if base == "" || os.Getenv(envHomeOverride) != "" {
+		return
+	}
+
+	_ = os.Setenv(envHomeOverride, base)
+}
+
 // getUserDirPath returns and creates the path for a user directory.
 func getUserDirPath(dt dirType) (string, error) {
 	path, err := resolveUserDirPath(dt)

backend/system/userdata_test.go

@@ -1,6 +1,7 @@
 package system
 
 import (
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -50,3 +51,39 @@ func TestResolveUserDirPath_NoOverrideUsesOSPath(t *testing.T) {
 		)
 	}
 }
+
+// UseHomeOverride carries two rules that a mobile launch depends on and
+// that nothing else would notice breaking: an empty base must do
+// nothing, because that is precisely what StoragePath() returns on
+// desktop, and an override already set must win, or YJ_HOME would stop
+// relocating a sandbox on the platform that decides for itself.
+func TestUseHomeOverride(t *testing.T) {
+	const (
+		storage = "/data/user/0/app.yellowjacket/files"
+		sandbox = "/tmp/sandbox"
+	)
+
+	tests := []struct {
+		name    string
+		already string
+		base    string
+		want    string
+	}{
+		{name: "empty base is a no-op", already: "", base: "", want: ""},
+		{name: "sets the override when unset", already: "", base: storage, want: storage},
+		{name: "an existing override wins", already: sandbox, base: storage, want: sandbox},
+		{name: "empty base keeps an existing override", already: sandbox, base: "", want: sandbox},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Setenv(envHomeOverride, tt.already)
+
+			UseHomeOverride(tt.base)
+
+			if got := os.Getenv(envHomeOverride); got != tt.want {
+				t.Errorf("%s = %q, want %q", envHomeOverride, got, tt.want)
+			}
+		})
+	}
+}

build/android/Taskfile.yml

@@ -0,0 +1,486 @@
+version: '3'
+
+includes:
+  common: ../Taskfile.yml
+
+vars:
+  # The *installed* package name, which every adb-driven task below uses
+  # to uninstall, launch and filter. It must agree with `applicationId`
+  # in app/build.gradle, and nothing enforces that.
+  #
+  # ANDROID.md says to set this in build/config.yml. That does not work
+  # in beta.8, checked both ways: `wails3 task` builds its var set from
+  # CLI KEY=VALUE arguments and the Taskfile tree only -- nothing reads
+  # config.yml -- and even when set it feeds only these adb commands,
+  # never Gradle. So the identity is declared twice, here and in
+  # build.gradle, and a change to one alone means the official run and
+  # deploy tasks address a package that is not installed.
+  APP_ID: '{{.APP_ID | default "app.yellowjacket"}}'
+  MIN_SDK: '21'
+  TARGET_SDK: '35'
+  # The emulator runs the host architecture; physical devices are arm64
+  HOST_ARCH:
+    sh: '[ "$(uname -m)" = "x86_64" ] && echo "amd64" || echo "arm64"'
+  # System-image ABI for the host, used in the "create an AVD" hint below.
+  ANDROID_ABI:
+    sh: '[ "$(uname -m)" = "arm64" ] && echo "arm64-v8a" || echo "x86_64"'
+  # SDK location: $ANDROID_HOME / $ANDROID_SDK_ROOT, else the per-OS default
+  # (macOS: ~/Library/Android/sdk, Linux/other: ~/Android/Sdk)
+  SDK_ROOT:
+    sh: 'echo "${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$([ -d "$HOME/Library/Android/sdk" ] && echo "$HOME/Library/Android/sdk" || echo "$HOME/Android/Sdk")}}"'
+  ADB:
+    sh: 'command -v adb || echo "${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$([ -d "$HOME/Library/Android/sdk" ] && echo "$HOME/Library/Android/sdk" || echo "$HOME/Android/Sdk")}}/platform-tools/adb"'
+  EMULATOR:
+    sh: 'command -v emulator || echo "${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$([ -d "$HOME/Library/Android/sdk" ] && echo "$HOME/Library/Android/sdk" || echo "$HOME/Android/Sdk")}}/emulator/emulator"'
+  # avdmanager lives under cmdline-tools/<version>/bin; used to auto-create an
+  # AVD when none exists (mirrors the iOS `ensure-simulator` auto-create flow).
+  AVDMANAGER:
+    sh: 'command -v avdmanager || ls "${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$([ -d "$HOME/Library/Android/sdk" ] && echo "$HOME/Library/Android/sdk" || echo "$HOME/Android/Sdk")}}"/cmdline-tools/*/bin/avdmanager 2>/dev/null | sort -V | tail -1 || true'
+
+tasks:
+  install:deps:
+    summary: Check and install Android development dependencies
+    cmds:
+      - go run build/android/scripts/deps/install_deps.go
+    env:
+      TASK_FORCE_YES: '{{if .YES}}true{{else}}false{{end}}'
+    prompt: This will check and install Android development dependencies. Continue?
+
+  build:
+    summary: Creates a debug build of the application for Android
+    deps:
+      - task: common:go:mod:tidy
+      - task: generate:android:overlay
+      - task: common:build:frontend
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          PRODUCTION:
+            ref: .PRODUCTION
+    cmds:
+      - echo "Building Android app {{.APP_NAME}}..."
+      - task: compile:go:shared
+        vars:
+          ARCH: '{{.ARCH | default .HOST_ARCH}}'
+          # This repo's one edit to the android scaffold, and it is not
+          # cosmetic. Upstream forwards ARCH here and not PRODUCTION, so
+          # compile:go:shared recomputed BUILD_FLAGS against an unset
+          # .PRODUCTION and fell back to the debug branch. package:fat
+          # calls compile:go:shared directly for amd64 (passing it), and
+          # reaches arm64 only through this task -- so a release APK
+          # shipped a *debug* 40 MB arm64 library beside a production
+          # 31 MB x86_64 one. The phone ABI, which is the only one a
+          # release is for, was the broken one. 34 MB APK before, 27
+          # after.
+          PRODUCTION: '{{.PRODUCTION}}'
+    vars:
+      BUILD_FLAGS: '{{if eq .PRODUCTION "true"}}-tags production,android -trimpath -buildvcs=false -ldflags="-w -s"{{else}}-tags android,debug -buildvcs=false -gcflags=all="-l"{{end}}'
+    env:
+      PRODUCTION: '{{.PRODUCTION | default "false"}}'
+
+  compile:go:shared:
+    summary: Compile Go code to shared library (.so)
+    cmds:
+      - |
+        # Locate the NDK: $ANDROID_NDK_HOME, or the newest installed NDK
+        NDK_ROOT="$ANDROID_NDK_HOME"
+        if [ -z "$NDK_ROOT" ]; then
+          SDK_ROOT="{{.SDK_ROOT}}"
+          NDK_ROOT=$(ls -d "$SDK_ROOT"/ndk/* 2>/dev/null | sort -V | tail -1)
+        fi
+        if [ -z "$NDK_ROOT" ] || [ ! -d "$NDK_ROOT" ]; then
+          echo "Error: Android NDK not found"
+          echo "Install one with: sdkmanager 'ndk;26.3.11579264' (or set ANDROID_NDK_HOME)"
+          exit 1
+        fi
+
+        # Determine toolchain based on host OS
+        case "$(uname -s)" in
+          Darwin) HOST_TAG="darwin-x86_64" ;;
+          Linux)  HOST_TAG="linux-x86_64" ;;
+          *)      echo "Unsupported host OS"; exit 1 ;;
+        esac
+
+        TOOLCHAIN="$NDK_ROOT/toolchains/llvm/prebuilt/$HOST_TAG"
+
+        # Set compiler based on architecture
+        case "{{.ARCH}}" in
+          arm64)
+            export CC="$TOOLCHAIN/bin/aarch64-linux-android{{.MIN_SDK}}-clang"
+            export CXX="$TOOLCHAIN/bin/aarch64-linux-android{{.MIN_SDK}}-clang++"
+            export GOARCH=arm64
+            JNI_DIR="arm64-v8a"
+            ;;
+          amd64|x86_64)
+            export CC="$TOOLCHAIN/bin/x86_64-linux-android{{.MIN_SDK}}-clang"
+            export CXX="$TOOLCHAIN/bin/x86_64-linux-android{{.MIN_SDK}}-clang++"
+            export GOARCH=amd64
+            JNI_DIR="x86_64"
+            ;;
+          *)
+            echo "Unsupported architecture: {{.ARCH}}"
+            exit 1
+            ;;
+        esac
+
+        export CGO_ENABLED=1
+        export GOOS=android
+
+        mkdir -p {{.BIN_DIR}}
+        mkdir -p build/android/app/src/main/jniLibs/$JNI_DIR
+
+        go build -buildmode=c-shared -overlay build/android/overlay.json {{.BUILD_FLAGS}} \
+          -o build/android/app/src/main/jniLibs/$JNI_DIR/libwails.so
+    vars:
+      BUILD_FLAGS: '{{if eq .PRODUCTION "true"}}-tags production,android -trimpath -buildvcs=false -ldflags="-w -s"{{else}}-tags android,debug -buildvcs=false -gcflags=all="-l"{{end}}'
+
+  compile:go:all-archs:
+    summary: Compile Go code for all Android architectures (fat APK)
+    cmds:
+      - task: compile:go:shared
+        vars:
+          ARCH: arm64
+      - task: compile:go:shared
+        vars:
+          ARCH: amd64
+
+  package:
+    summary: Packages a production build of the application into a signed release APK
+    desc: |
+      Builds for arm64 by default (covers 99%+ of real devices). Set ARCH=amd64
+      for emulator-only APKs, or use package:fat for a universal APK.
+    deps:
+      - task: build
+        vars:
+          PRODUCTION: "true"
+          ARCH: '{{.ARCH | default "arm64"}}'
+    cmds:
+      - task: assemble:apk:release
+
+  package:fat:
+    summary: Packages a production build for all architectures (fat APK)
+    deps:
+      - task: build
+        vars:
+          PRODUCTION: "true"
+          ARCH: arm64
+    cmds:
+      - task: compile:go:shared
+        vars:
+          ARCH: amd64
+          PRODUCTION: "true"
+      - task: assemble:apk:release
+
+  bundle:
+    summary: Packages a production AAB (Android App Bundle) for Play Store submission
+    desc: |
+      Builds for arm64 by default. Set ARCH=amd64 for emulator builds, or use
+      bundle:fat for a universal AAB.
+    deps:
+      - task: build
+        vars:
+          PRODUCTION: "true"
+          ARCH: '{{.ARCH | default "arm64"}}'
+    cmds:
+      - task: assemble:aab:release
+
+  bundle:fat:
+    summary: Packages a production AAB for all architectures
+    deps:
+      - task: build
+        vars:
+          PRODUCTION: "true"
+          ARCH: arm64
+    cmds:
+      - task: compile:go:shared
+        vars:
+          ARCH: amd64
+          PRODUCTION: "true"
+      - task: assemble:aab:release
+
+  assemble:apk:
+    summary: Assembles a debug APK using Gradle
+    preconditions:
+      - sh: 'command -v java >/dev/null || [ -n "$JAVA_HOME" ]'
+        msg: "Java not found. Install a JDK (e.g. brew install openjdk@21) and/or set JAVA_HOME"
+    cmds:
+      - |
+        cd build/android
+        # The exec bit is lost when gradlew is extracted from the embedded
+        # build assets, so restore it before invoking the wrapper.
+        chmod +x ./gradlew
+        ./gradlew assembleDebug
+        cp app/build/outputs/apk/debug/app-debug.apk "../../{{.BIN_DIR}}/{{.APP_NAME}}.apk"
+        echo "APK created: {{.BIN_DIR}}/{{.APP_NAME}}.apk"
+
+  assemble:apk:release:
+    summary: Assembles a release APK using Gradle (signed with the debug keystore unless ANDROID_KEYSTORE_FILE is set)
+    preconditions:
+      - sh: 'command -v java >/dev/null || [ -n "$JAVA_HOME" ]'
+        msg: "Java not found. Install a JDK (e.g. brew install openjdk@21) and/or set JAVA_HOME"
+    cmds:
+      - |
+        cd build/android
+        # The exec bit is lost when gradlew is extracted from the embedded
+        # build assets, so restore it before invoking the wrapper.
+        chmod +x ./gradlew
+        ./gradlew assembleRelease
+        cp app/build/outputs/apk/release/app-release.apk "../../{{.BIN_DIR}}/{{.APP_NAME}}.apk"
+        echo "Release APK created: {{.BIN_DIR}}/{{.APP_NAME}}.apk"
+
+  assemble:aab:
+    summary: Assembles a debug AAB (Android App Bundle) using Gradle
+    preconditions:
+      - sh: 'command -v java >/dev/null || [ -n "$JAVA_HOME" ]'
+        msg: "Java not found. Install a JDK (e.g. brew install openjdk@21) and/or set JAVA_HOME"
+    cmds:
+      - |
+        cd build/android
+        # The exec bit is lost when gradlew is extracted from the embedded
+        # build assets, so restore it before invoking the wrapper.
+        chmod +x ./gradlew
+        ./gradlew bundleDebug
+        cp app/build/outputs/bundle/debug/app-debug.aab "../../{{.BIN_DIR}}/{{.APP_NAME}}.aab"
+        echo "AAB created: {{.BIN_DIR}}/{{.APP_NAME}}.aab"
+
+  assemble:aab:release:
+    summary: Assembles a release AAB for Play Store upload (signed with the debug keystore unless ANDROID_KEYSTORE_FILE is set)
+    preconditions:
+      - sh: 'command -v java >/dev/null || [ -n "$JAVA_HOME" ]'
+        msg: "Java not found. Install a JDK (e.g. brew install openjdk@21) and/or set JAVA_HOME"
+    cmds:
+      - |
+        # With Play App Signing, the keystore configured here is your UPLOAD
+        # key: Google verifies the upload with it, then re-signs the app with
+        # the app signing key it manages for distribution.
+        if [ -z "$ANDROID_KEYSTORE_FILE" ]; then
+          echo "WARNING: ANDROID_KEYSTORE_FILE is not set, so this AAB will be"
+          echo "signed with the debug keystore. Google Play rejects debug-signed"
+          echo "bundles. Set ANDROID_KEYSTORE_FILE, ANDROID_KEYSTORE_PASSWORD,"
+          echo "ANDROID_KEY_ALIAS and ANDROID_KEY_PASSWORD before uploading."
+        fi
+        cd build/android
+        # The exec bit is lost when gradlew is extracted from the embedded
+        # build assets, so restore it before invoking the wrapper.
+        chmod +x ./gradlew
+        ./gradlew bundleRelease
+        cp app/build/outputs/bundle/release/app-release.aab "../../{{.BIN_DIR}}/{{.APP_NAME}}.aab"
+        echo "Release AAB created: {{.BIN_DIR}}/{{.APP_NAME}}.aab"
+
+  generate:android:overlay:
+    internal: true
+    summary: Generate Go build overlay that registers the Android main
+    sources:
+      - build/config.yml
+    generates:
+      - build/android/overlay.json
+      - build/android/gen/main_android.gen.go
+    cmds:
+      - wails3 android overlay:gen -out build/android/overlay.json -config build/config.yml
+
+  generate:android:bindings:
+    internal: true
+    summary: Generates bindings for Android
+    sources:
+      - "**/*.go"
+      - go.mod
+      - go.sum
+    generates:
+      - frontend/bindings/**/*
+    cmds:
+      # Bindings are generated from the Go AST; CGO is disabled so the NDK
+      # is not required for this step
+      - wails3 generate bindings -f '-tags android' -clean=true
+    env:
+      GOOS: android
+      CGO_ENABLED: 0
+
+  ensure-emulator:
+    internal: true
+    summary: Ensure Android Emulator is running
+    silent: true
+    cmds:
+      - |
+        # Check if an emulator is already running
+        if "{{.ADB}}" devices | grep -q "emulator"; then
+          echo "Emulator already running"
+          exit 0
+        fi
+
+        # Get first available AVD
+        AVD_NAME=$("{{.EMULATOR}}" -list-avds | tail -1)
+        if [ -z "$AVD_NAME" ]; then
+          # No AVD yet. Mirror the iOS `ensure-simulator` flow and create one
+          # automatically — but ONLY from a system image that is already
+          # installed. We never trigger an sdkmanager download from a `run`
+          # task (that would be a surprise multi-GB download + license prompt).
+          # Pick the highest-API installed image matching the host ABI.
+          SDK_ROOT="{{.SDK_ROOT}}"
+          ABI="{{.ANDROID_ABI}}"
+          IMG=$(ls -d "$SDK_ROOT"/system-images/android-*/*/"$ABI" 2>/dev/null | sort -V | tail -1)
+          AVDMANAGER="{{.AVDMANAGER}}"
+          if [ -n "$IMG" ] && [ -x "$AVDMANAGER" ]; then
+            PKG="system-images;$(echo "$IMG" | sed "s|$SDK_ROOT/system-images/||" | tr '/' ';')"
+            echo "No Android Virtual Devices found. Creating 'wails' from $PKG..."
+            echo "no" | "$AVDMANAGER" create avd --name wails --package "$PKG" --device pixel_7 --force
+            AVD_NAME=wails
+          else
+            echo "No Android Virtual Devices found, and no system image is installed to create one from."
+            echo "Install a system image and create an AVD, e.g.:"
+            echo "  sdkmanager 'system-images;android-35;google_apis;$ABI'"
+            echo "  avdmanager create avd --name wails --package 'system-images;android-35;google_apis;$ABI' --device pixel_7"
+            exit 1
+          fi
+        fi
+
+        echo "Starting emulator: $AVD_NAME"
+        # Start the emulator daemonized so it outlives this task step. go-task's
+        # shell tracks background jobs by PID and reaps them when the command's
+        # interpreter finishes (which nohup/setsid alone don't prevent — the kill
+        # is direct), so a bare `emulator &` is gone before the later
+        # install/launch steps run. Launch it from a short-lived child shell that
+        # backgrounds the emulator and exits immediately: the emulator is then
+        # reparented to init/launchd and go-task's shell has no handle to reap it.
+        nohup sh -c "'{{.EMULATOR}}' -avd '$AVD_NAME' -no-snapshot-load </dev/null >/dev/null 2>&1 &" >/dev/null 2>&1
+
+        # Wait for emulator to boot (max 120 seconds)
+        echo "Waiting for emulator to boot..."
+        "{{.ADB}}" wait-for-device
+
+        for i in $(seq 1 120); do
+          BOOT_COMPLETED=$("{{.ADB}}" shell getprop sys.boot_completed 2>/dev/null | tr -d '\r')
+          if [ "$BOOT_COMPLETED" = "1" ]; then
+            echo "Emulator booted successfully"
+            exit 0
+          fi
+          sleep 1
+        done
+
+        echo "Emulator boot timeout"
+        exit 1
+    preconditions:
+      - sh: '[ -x "{{.ADB}}" ] || command -v adb'
+        msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"
+      - sh: '[ -x "{{.EMULATOR}}" ] || command -v emulator'
+        msg: "emulator not found. Install the Android SDK emulator package (or set ANDROID_HOME)"
+
+  deploy-emulator:
+    summary: Deploy the packaged release APK to the Android Emulator
+    deps:
+      - task: package
+        vars:
+          ARCH: '{{.ARCH | default .HOST_ARCH}}'
+    cmds:
+      - task: ensure-emulator
+      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
+      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
+      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+
+  run:
+    summary: Build, install and launch a debug build in the Android Emulator
+    deps:
+      - task: ensure-emulator
+      - task: build
+    cmds:
+      - task: assemble:apk
+      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
+      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
+      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+
+  device:list:
+    summary: Lists connected Android devices and emulators (serials)
+    cmds:
+      - '"{{.ADB}}" devices -l'
+
+  run:device:
+    summary: Build, install and launch a debug build on a connected physical Android device
+    deps:
+      - task: build
+        vars:
+          ARCH: arm64
+    cmds:
+      - task: assemble:apk
+      - |
+        DEVICE='{{.DEVICE_ID | default ""}}'
+        if [ -z "$DEVICE" ]; then
+          DEVICE="${DEVICE_ID:-}"
+        fi
+        if [ -z "$DEVICE" ]; then
+          DEVICE=$("{{.ADB}}" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1; exit }')
+        fi
+        if [ -z "$DEVICE" ]; then
+          echo "Error: no connected physical Android device found."
+          echo "Pass DEVICE_ID=<serial> to target a device explicitly."
+          echo "Find connected device serials with: {{.ADB}} devices"
+          exit 1
+        fi
+
+        echo "Deploying {{.BIN_DIR}}/{{.APP_NAME}}.apk to device $DEVICE..."
+        "{{.ADB}}" -s "$DEVICE" uninstall {{.APP_ID}} 2>/dev/null || true
+        "{{.ADB}}" -s "$DEVICE" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"
+        "{{.ADB}}" -s "$DEVICE" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity
+    preconditions:
+      - sh: '[ -x "{{.ADB}}" ] || command -v adb'
+        msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"
+
+  deploy-device:
+    summary: Deploy the packaged release APK to a connected physical Android device
+    deps:
+      - task: package
+        vars:
+          ARCH: arm64
+    cmds:
+      - |
+        DEVICE='{{.DEVICE_ID | default ""}}'
+        if [ -z "$DEVICE" ]; then
+          DEVICE="${DEVICE_ID:-}"
+        fi
+        if [ -z "$DEVICE" ]; then
+          DEVICE=$("{{.ADB}}" devices | awk 'NR > 1 && $2 == "device" && $1 !~ /^emulator-/ { print $1; exit }')
+        fi
+        if [ -z "$DEVICE" ]; then
+          echo "Error: no connected physical Android device found."
+          echo "Pass DEVICE_ID=<serial> to target a device explicitly."
+          echo "Find connected device serials with: {{.ADB}} devices"
+          exit 1
+        fi
+
+        echo "Deploying {{.BIN_DIR}}/{{.APP_NAME}}.apk to device $DEVICE..."
+        "{{.ADB}}" -s "$DEVICE" uninstall {{.APP_ID}} 2>/dev/null || true
+        "{{.ADB}}" -s "$DEVICE" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"
+        "{{.ADB}}" -s "$DEVICE" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity
+    preconditions:
+      - sh: '[ -x "{{.ADB}}" ] || command -v adb'
+        msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"
+
+  studio:
+    summary: Open the generated Android project in Android Studio
+    cmds:
+      - |
+        if command -v studio >/dev/null 2>&1; then
+          studio build/android
+        elif [ -d "/Applications/Android Studio.app" ]; then
+          open -a "Android Studio" build/android
+        else
+          echo "Android Studio not found. Install it from https://developer.android.com/studio,"
+          echo "then open the build/android directory."
+          exit 1
+        fi
+
+  logs:
+    summary: Stream Android logcat filtered to this app
+    cmds:
+      - '"{{.ADB}}" logcat -v time | grep -E "(Wails|{{.APP_NAME}})" || true'
+
+  logs:all:
+    summary: Stream all Android logcat (verbose)
+    cmds:
+      - '"{{.ADB}}" logcat -v time'
+
+  clean:
+    summary: Clean build artifacts
+    cmds:
+      - rm -rf {{.BIN_DIR}}
+      - rm -rf build/android/app/build
+      - rm -rf build/android/app/src/main/jniLibs/*/libwails.so
+      - rm -rf build/android/.gradle

build/android/app/build.gradle

@@ -0,0 +1,127 @@
+plugins {
+    id 'com.android.application'
+}
+
+android {
+    namespace 'com.wails.app'
+    compileSdk 35
+
+    buildFeatures {
+        buildConfig = true
+    }
+
+    defaultConfig {
+        // The app's identity on the device. `namespace` above stays
+        // com.wails.app -- that is the *Java package* the scaffold's
+        // MainActivity/WailsBridge live in, and renaming it would mean
+        // renaming their source. The two being different is normal and is
+        // why every `am start` needs the fully-qualified activity name
+        // (app.yellowjacket/com.wails.app.MainActivity), not `.MainActivity`.
+        //
+        // Matches build/config.yml's productIdentifier.
+        applicationId "app.yellowjacket"
+        minSdk 21
+        targetSdk 35
+
+        // **Android orders releases by this integer, not by the version
+        // string, and refuses to install anything not greater than what is
+        // already there.** A hardcoded 1 means the first install is the
+        // last: every later build is rejected as a downgrade and the only
+        // way out is an uninstall, which takes the user's library with it.
+        // CI derives it from the tag (1.3.1 -> 10301), monotonic as long as
+        // minor and patch stay under 100. The defaults keep a local build
+        // working with no environment at all.
+        //
+        // `Integer.parseInt`, not `(...) as Integer`: Groovy binds the call
+        // parentheses to `versionCode` before the cast, so the latter reads
+        // as `versionCode("1") as Integer` -- it sets a String, then casts
+        // the setter's null return, and Gradle fails the entire project
+        // with "Value is null" pointing at this line.
+        versionCode Integer.parseInt(System.getenv("YJ_VERSION_CODE") ?: "1")
+        versionName System.getenv("YJ_VERSION") ?: "0.0.0"
+
+        // **arm64 only, and x86_64 is not a gap.**  `modernc.org/libc`'s
+        // Xlstat64 issues a raw lstat syscall on linux/amd64, which
+        // Android's seccomp policy forbids (bionic never issues it), so
+        // the process takes SIGSYS the first time anything touches the
+        // database -- which for this app is startup.  That is every
+        // x86_64 Android, emulators and x86 Chromebooks alike, not just
+        // some.  arm64 is structurally unaffected: the architecture has
+        // no lstat syscall at all, so modernc routes through fstatat.
+        //
+        // So the second ABI was ~31 MB of an artifact that could not run
+        // anywhere.  If modernc fixes it, adding 'x86_64' back here and
+        // to the native-code assertion in android-apk.yml is the whole
+        // change.
+        ndk {
+            abiFilters 'arm64-v8a'
+        }
+    }
+
+    def keystoreFile = System.getenv("ANDROID_KEYSTORE_FILE")
+    def hasKeystore = keystoreFile != null && !keystoreFile.trim().isEmpty()
+
+    signingConfigs {
+        // A real keystore can be provided via environment variables; without
+        // one, release builds are signed with the debug keystore so they can
+        // be installed for testing (not suitable for Play Store uploads).
+        release {
+            if (hasKeystore) {
+                storeFile file(keystoreFile)
+                storePassword System.getenv("ANDROID_KEYSTORE_PASSWORD")
+                keyAlias System.getenv("ANDROID_KEY_ALIAS")
+                keyPassword System.getenv("ANDROID_KEY_PASSWORD")
+            }
+        }
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+            signingConfig hasKeystore ? signingConfigs.release : signingConfigs.debug
+        }
+        debug {
+            debuggable true
+            // Its own application id, so it installs *beside* the release
+            // app rather than needing an uninstall to replace it. The two
+            // are signed by different certificates (the release one comes
+            // from a keystore CI holds), and Android's remedy for a
+            // certificate change is an uninstall -- which takes the
+            // user's library with it. This is also what makes the WebView
+            // inspectable on a real phone: `debuggable` is what turns on
+            // `setWebContentsDebuggingEnabled`, and `make android-inspect`
+            // drives it.
+            applicationIdSuffix ".dev"
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_11
+        targetCompatibility JavaVersion.VERSION_11
+    }
+
+    // Source sets configuration
+    sourceSets {
+        main {
+            // JNI libraries are in jniLibs folder
+            jniLibs.srcDirs = ['src/main/jniLibs']
+            // Assets for the WebView
+            assets.srcDirs = ['src/main/assets']
+        }
+    }
+
+    // Packaging options
+    packagingOptions {
+        // Don't strip Go symbols in debug builds
+        doNotStrip '*/arm64-v8a/libwails.so'
+    }
+}
+
+dependencies {
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+    implementation 'androidx.webkit:webkit:1.9.0'
+    implementation 'com.google.android.material:material:1.11.0'
+    implementation 'androidx.biometric:biometric:1.1.0'
+    implementation 'androidx.security:security-crypto:1.1.0-alpha06'
+}

build/android/app/proguard-rules.pro

@@ -0,0 +1,12 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+
+# Keep native methods
+-keepclasseswithmembernames class * {
+    native <methods>;
+}
+
+# Keep Wails bridge classes
+-keep class com.wails.app.WailsBridge { *; }
+-keep class com.wails.app.WailsJSBridge { *; }

build/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- Internet permission for WebView -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.VIBRATE" />
+    <!-- Observe network connectivity / type for android:NetworkChanged events -->
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.USE_BIOMETRIC" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+
+    <!--
+      Playback has to survive the screen locking, and that needs a
+      foreground service typed mediaPlayback rather than dataSync. The
+      type in the <service> element and the permission here must agree,
+      or startForeground throws at runtime.
+    -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+
+    <!--
+      Reading the user's music.
+
+      READ_MEDIA_AUDIO is the Android 13+ grant and READ_EXTERNAL_STORAGE
+      is its predecessor, capped so it is not requested where it no
+      longer applies. Both give access through **MediaStore**.
+
+      MANAGE_EXTERNAL_STORAGE is what gives access through the
+      *filesystem*, and this app needs it rather than merely preferring
+      it: `audio_files.file_path` is the primary key of ownership, the
+      scanner walks a directory the user chose, and every
+      GetFilePathsBy... query exists to hand a path to the player.
+      MediaStore offers no stable directory to walk and no way to write
+      a tag back in place, so the alternative is not "more work" but a
+      different application.
+
+      It is a Play-restricted permission, granted on a Settings screen
+      rather than in a dialog. That is acceptable *here* only because
+      this app is distributed as an APK through the package registry and
+      not through Play — see docs/android-release.md. If it ever targets
+      Play, this is the line that has to go, and plan 016 says what
+      would replace it.
+    -->
+    <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
+    <uses-permission
+        android:name="android.permission.READ_EXTERNAL_STORAGE"
+        android:maxSdkVersion="32" />
+    <uses-permission
+        android:name="android.permission.WRITE_EXTERNAL_STORAGE"
+        android:maxSdkVersion="29" />
+    <uses-permission
+        android:name="android.permission.MANAGE_EXTERNAL_STORAGE"
+        tools:ignore="ScopedStorage" />
+
+    <queries>
+        <intent>
+            <action android:name="android.media.action.IMAGE_CAPTURE" />
+        </intent>
+        <intent>
+            <action android:name="android.media.action.VIDEO_CAPTURE" />
+        </intent>
+    </queries>
+
+    <application
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.WailsApp"
+        tools:targetApi="31">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:configChanges="orientation|screenSize|keyboardHidden|uiMode"
+            android:windowSoftInputMode="adjustResize">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths" />
+        </provider>
+
+        <!--
+          mediaPlayback, not the scaffold's dataSync: this app's reason
+          for staying alive in the background is that a song is
+          playing, and Android matches the declared type against what
+          the service actually does.
+        -->
+        <service
+            android:name=".WailsForegroundService"
+            android:exported="false"
+            android:foregroundServiceType="mediaPlayback" />
+    </application>
+
+</manifest>

build/android/app/src/main/java/com/wails/app/MainActivity.java

@@ -0,0 +1,967 @@
+package com.wails.app;
+
+import android.annotation.SuppressLint;
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.content.IntentFilter;
+import android.content.res.Configuration;
+import android.database.Cursor;
+import android.net.ConnectivityManager;
+import android.net.Network;
+import android.net.NetworkCapabilities;
+import android.net.Uri;
+import android.Manifest;
+import android.os.BatteryManager;
+import android.os.Build;
+import android.os.Bundle;
+import android.os.Environment;
+import android.os.PowerManager;
+import android.provider.Settings;
+import android.content.pm.PackageManager;
+import android.graphics.Bitmap;
+import android.graphics.BitmapFactory;
+import android.provider.MediaStore;
+import android.provider.OpenableColumns;
+import android.util.Base64;
+import android.util.Log;
+import android.webkit.WebResourceRequest;
+import android.webkit.WebResourceResponse;
+import android.webkit.WebSettings;
+import android.webkit.WebView;
+import android.webkit.WebViewClient;
+
+import android.view.View;
+
+import androidx.annotation.Nullable;
+import androidx.appcompat.app.AppCompatActivity;
+import androidx.core.content.FileProvider;
+import androidx.core.graphics.Insets;
+import androidx.core.view.ViewCompat;
+import androidx.core.view.WindowInsetsCompat;
+import androidx.core.view.WindowCompat;
+import androidx.core.view.WindowInsetsControllerCompat;
+import androidx.webkit.WebViewAssetLoader;
+
+import org.json.JSONObject;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * MainActivity hosts the WebView and manages the Wails application lifecycle.
+ * It uses WebViewAssetLoader to serve assets from the Go library without
+ * requiring a network server.
+ */
+public class MainActivity extends AppCompatActivity {
+    private static final String TAG = "WailsActivity";
+    private static final boolean DEBUG = BuildConfig.DEBUG;
+    private static final String WAILS_SCHEME = "https";
+    private static final String WAILS_HOST = "wails.localhost";
+    private static final int FILE_PICKER_REQUEST = 7001;
+
+    private WebView webView;
+    private WailsBridge bridge;
+    // Battery: system-event receivers are registered only while the activity is
+    // in the foreground (onStart) and torn down in onStop, so background battery/
+    // network/screen broadcasts don't wake the app.
+    private boolean systemReceiversRegistered = false;
+    private WebViewAssetLoader assetLoader;
+
+    // The Go-side dialog ID of the in-flight file picker (-1 when idle)
+    private int pendingFilePickerCallbackID = -1;
+    private static final int PHOTO_CAPTURE_REQUEST = 7002;
+    private static final int VIDEO_CAPTURE_REQUEST = 7003;
+    private static final int CAMERA_PERMISSION_REQUEST = 7010;
+    private File pendingCaptureFile;
+    private boolean pendingCaptureIsVideo;
+
+    // System-event sources (battery/power, screen lock, network). Registered in
+    // onCreate, torn down in onDestroy. Each forwards a "system:*" event to JS
+    // via the bridge.
+    private BroadcastReceiver batteryReceiver;
+    private BroadcastReceiver screenReceiver;
+    private BroadcastReceiver powerSaveReceiver;
+    private ConnectivityManager connectivityManager;
+    private ConnectivityManager.NetworkCallback networkCallback;
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.activity_main);
+
+        // Before anything renders: the page is laid out inside the
+        // window, and on Android 15 the window is the whole screen.
+        applyWindowInsets();
+
+        // Initialize the native Go library
+        bridge = new WailsBridge(this);
+        bridge.initialize();
+
+        // Ask for access to the user's music before the frontend has
+        // anything to say about it.  See ensureStorageAccess().
+        ensureStorageAccess();
+
+        // Set up WebView
+        setupWebView();
+
+        // Load the application
+        loadApplication();
+    }
+
+    /**
+     * Obtain access to the user's music.
+     *
+     * <p>This app is a library manager: its database is keyed on file
+     * paths, its scanner walks a directory the user chose, and its tag
+     * writer rewrites files in place. MediaStore offers none of those,
+     * so the app holds MANAGE_EXTERNAL_STORAGE — which is granted on a
+     * Settings screen rather than in a dialog, and therefore cannot be
+     * requested with requestPermissions().
+     *
+     * <p>The screen is opened on every cold start until access exists,
+     * because without it the app can see nothing at all and there is no
+     * degraded mode worth offering. Returning from it lands in
+     * onResume, which re-checks and tells the frontend.
+     *
+     * <p>Below Android 11 there is no all-files concept and plain
+     * READ_EXTERNAL_STORAGE is both sufficient and a normal dialog.
+     */
+    private void ensureStorageAccess() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            if (Environment.isExternalStorageManager()) {
+                return;
+            }
+            // The per-app screen is the one that can actually grant it.
+            // A few OEM builds do not implement it, so fall back to the
+            // global list rather than leaving the user with nothing.
+            try {
+                startActivity(new Intent(
+                        Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION,
+                        Uri.parse("package:" + getPackageName())));
+            } catch (Exception e) {
+                Log.w(TAG, "per-app all-files screen unavailable: " + e.getMessage());
+                try {
+                    startActivity(new Intent(Settings.ACTION_MANAGE_ALL_FILES_ACCESS_PERMISSION));
+                } catch (Exception e2) {
+                    Log.w(TAG, "no all-files settings screen at all: " + e2.getMessage());
+                }
+            }
+            return;
+        }
+
+        if (checkSelfPermission(Manifest.permission.READ_EXTERNAL_STORAGE)
+                != PackageManager.PERMISSION_GRANTED) {
+            requestPermissions(new String[]{Manifest.permission.READ_EXTERNAL_STORAGE}, 1010);
+        }
+    }
+
+    /**
+     * Whether the app can currently read the user's music, by the same
+     * test the Go side uses.
+     */
+    private boolean hasStorageAccess() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            return Environment.isExternalStorageManager();
+        }
+        return checkSelfPermission(Manifest.permission.READ_EXTERNAL_STORAGE)
+                == PackageManager.PERMISSION_GRANTED;
+    }
+
+    /**
+     * Tell the frontend whether music is readable. Emitted on resume
+     * rather than only at startup, because the grant happens on a
+     * Settings screen in another task and the way back is a resume.
+     */
+    private void emitStorageAccess() {
+        if (bridge == null) {
+            return;
+        }
+        bridge.emitEvent("android:storageAccess",
+                "{\"granted\":" + (hasStorageAccess() ? "true" : "false") + "}");
+    }
+
+    @SuppressLint("SetJavaScriptEnabled")
+    private void setupWebView() {
+        webView = findViewById(R.id.webview);
+        bridge.setWebView(webView);
+
+        // Configure WebView settings
+        WebSettings settings = webView.getSettings();
+        settings.setJavaScriptEnabled(true);
+        settings.setDomStorageEnabled(true);
+        settings.setDatabaseEnabled(true);
+        settings.setAllowFileAccess(false);
+        settings.setAllowContentAccess(false);
+        settings.setMediaPlaybackRequiresUserGesture(false);
+        settings.setMixedContentMode(WebSettings.MIXED_CONTENT_NEVER_ALLOW);
+
+        // Enable debugging in debug builds
+        if (DEBUG) {
+            WebView.setWebContentsDebuggingEnabled(true);
+        }
+
+        // Set up asset loader for serving local assets
+        assetLoader = new WebViewAssetLoader.Builder()
+                .setDomain(WAILS_HOST)
+                .addPathHandler("/", new WailsPathHandler(bridge))
+                .build();
+
+        // Set up WebView client to intercept requests
+        webView.setWebViewClient(new WebViewClient() {
+            @Nullable
+            @Override
+            public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) {
+                // Handle wails.localhost requests
+                if (request.getUrl().getHost() != null &&
+                        request.getUrl().getHost().equals(WAILS_HOST)) {
+
+                    // For wails API calls (runtime, capabilities, etc.) pass the
+                    // full URL including the query string, because
+                    // WebViewAssetLoader.PathHandler strips query params
+                    String path = request.getUrl().getPath();
+                    if (path != null && path.startsWith("/wails/")) {
+                        String fullPath = path;
+                        String query = request.getUrl().getQuery();
+                        if (query != null && !query.isEmpty()) {
+                            fullPath = path + "?" + query;
+                        }
+                        if (DEBUG) Log.d(TAG, "Wails API call: " + fullPath);
+
+                        byte[] data = bridge.serveAsset(fullPath, request.getMethod(), "{}");
+                        if (data != null && data.length > 0) {
+                            java.io.InputStream inputStream = new java.io.ByteArrayInputStream(data);
+                            java.util.Map<String, String> headers = new java.util.HashMap<>();
+                            headers.put("Access-Control-Allow-Origin", "*");
+                            headers.put("Cache-Control", "no-cache");
+                            headers.put("Content-Type", "application/json");
+
+                            return new WebResourceResponse(
+                                "application/json",
+                                "UTF-8",
+                                200,
+                                "OK",
+                                headers,
+                                inputStream
+                            );
+                        }
+                        // Return error response if data is null
+                        return new WebResourceResponse(
+                            "application/json",
+                            "UTF-8",
+                            500,
+                            "Internal Error",
+                            new java.util.HashMap<>(),
+                            new java.io.ByteArrayInputStream("{}".getBytes())
+                        );
+                    }
+
+                    // Stream captured photos/videos from the cache with HTTP Range
+                    // support so <video> can seek/stream a clip of any length.
+                    if (path != null && path.startsWith("/__capture__/")) {
+                        return serveCaptureFile(path.substring("/__capture__/".length()), request);
+                    }
+
+                    // For regular assets, use the asset loader
+                    return assetLoader.shouldInterceptRequest(request.getUrl());
+                }
+
+                return super.shouldInterceptRequest(view, request);
+            }
+
+            @Override
+            public void onPageFinished(WebView view, String url) {
+                super.onPageFinished(view, url);
+                if (DEBUG) Log.d(TAG, "Page loaded: " + url);
+                bridge.onPageFinished(url);
+                // Now that JS listeners are mounted, push a snapshot of the
+                // current battery / network / theme so the UI starts populated.
+                emitSystemSnapshot();
+            }
+        });
+
+        // Add JavaScript interface for Go communication
+        webView.addJavascriptInterface(new WailsJSBridge(bridge, webView), "wails");
+    }
+
+    private void loadApplication() {
+        String url = WAILS_SCHEME + "://" + WAILS_HOST + "/";
+        if (DEBUG) Log.d(TAG, "Loading URL: " + url);
+        webView.loadUrl(url);
+    }
+
+    /**
+     * Launch the system camera to capture a photo (video=false) or a video
+     * (video=true). The capture is written to a FileProvider URI in the cache and
+     * the result is delivered to JS as a "common:capture" event.
+     */
+    public void launchCameraCapture(boolean video) {
+        if (checkSelfPermission("android.permission.CAMERA") != PackageManager.PERMISSION_GRANTED) {
+            pendingCaptureIsVideo = video;
+            requestPermissions(new String[]{"android.permission.CAMERA"}, CAMERA_PERMISSION_REQUEST);
+            return;
+        }
+        try {
+            File dir = new File(getCacheDir(), "captures");
+            if (!dir.exists()) dir.mkdirs();
+            pendingCaptureFile = new File(dir, "capture_" + System.currentTimeMillis() + (video ? ".mp4" : ".jpg"));
+            pendingCaptureIsVideo = video;
+            Uri uri = FileProvider.getUriForFile(this, getPackageName() + ".fileprovider", pendingCaptureFile);
+            Intent intent = new Intent(video ? MediaStore.ACTION_VIDEO_CAPTURE : MediaStore.ACTION_IMAGE_CAPTURE);
+            intent.putExtra(MediaStore.EXTRA_OUTPUT, uri);
+            intent.addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
+            // Don't pre-check with resolveActivity(): Android 11+ package visibility
+            // hides other apps' intents unless declared in <queries>, so it can
+            // return null even when a camera app exists. Just launch and handle a miss.
+            startActivityForResult(intent, video ? VIDEO_CAPTURE_REQUEST : PHOTO_CAPTURE_REQUEST);
+        } catch (android.content.ActivityNotFoundException e) {
+            bridge.emitEvent("common:capture", "{\"error\":\"no camera app available\"}");
+        } catch (Exception e) {
+            Log.e(TAG, "launchCameraCapture failed", e);
+            bridge.emitEvent("common:capture", "{\"error\":\"capture failed\"}");
+        }
+    }
+
+    @Override
+    public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
+        super.onRequestPermissionsResult(requestCode, permissions, grantResults);
+        if (requestCode == CAMERA_PERMISSION_REQUEST) {
+            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
+                launchCameraCapture(pendingCaptureIsVideo);
+            } else {
+                bridge.emitEvent("common:capture", "{\"error\":\"camera permission denied\"}");
+            }
+            return;
+        }
+        if (bridge != null) {
+            bridge.onRequestPermissionsResult(requestCode, grantResults);
+        }
+    }
+
+    private void handleCaptureResult(int resultCode, @Nullable Intent data) {
+        File file = pendingCaptureFile;
+        final boolean video = pendingCaptureIsVideo;
+        pendingCaptureFile = null;
+        if (resultCode != RESULT_OK) {
+            bridge.emitEvent("common:capture", "{\"cancelled\":true}");
+            return;
+        }
+        // Some camera apps (commonly for video) ignore EXTRA_OUTPUT and instead
+        // return a content URI in the result data; copy that into our cache.
+        if ((file == null || !file.exists() || file.length() == 0)
+                && data != null && data.getData() != null) {
+            String copied = copyUriToCache(data.getData());
+            if (copied != null) file = new File(copied);
+        }
+        final File f = file;
+        if (f == null || !f.exists() || f.length() == 0) {
+            bridge.emitEvent("common:capture", "{\"cancelled\":true}");
+            return;
+        }
+        new Thread(() -> {
+            try {
+                JSONObject o = new JSONObject();
+                o.put("type", video ? "video" : "photo");
+                o.put("path", f.getAbsolutePath());
+                o.put("size", f.length());
+                if (!video) {
+                    String thumb = makePhotoThumbnail(f);
+                    if (thumb != null) o.put("thumb", thumb);
+                }
+                // Stream URL works for both: <video>/<img> load it from the cache
+                // via shouldInterceptRequest (Range-enabled), no size limit.
+                o.put("streamUrl", captureStreamUrl(f));
+                bridge.emitEvent("common:capture", o.toString());
+            } catch (Exception e) {
+                Log.e(TAG, "handleCaptureResult failed", e);
+                bridge.emitEvent("common:capture", "{\"error\":\"result processing failed\"}");
+            }
+        }).start();
+    }
+
+    /** Downscale a captured photo into a base64 JPEG data URL for display in the webview. */
+    @Nullable
+    private String makePhotoThumbnail(File file) {
+        try {
+            BitmapFactory.Options bounds = new BitmapFactory.Options();
+            bounds.inJustDecodeBounds = true;
+            BitmapFactory.decodeFile(file.getAbsolutePath(), bounds);
+            int sample = 1;
+            while (Math.max(bounds.outWidth, bounds.outHeight) / sample > 640) sample *= 2;
+            BitmapFactory.Options opts = new BitmapFactory.Options();
+            opts.inSampleSize = sample;
+            Bitmap bmp = BitmapFactory.decodeFile(file.getAbsolutePath(), opts);
+            if (bmp == null) return null;
+            ByteArrayOutputStream baos = new ByteArrayOutputStream();
+            bmp.compress(Bitmap.CompressFormat.JPEG, 70, baos);
+            bmp.recycle();
+            return "data:image/jpeg;base64," + Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP);
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    /**
+     * Build a same-origin URL the webview can stream a capture from. Served by
+     * serveCaptureFile (via shouldInterceptRequest); the path is relative to the
+     * cache dir so both camera files (captures/) and copied content URIs
+     * (wails-picker/) resolve.
+     */
+    private String captureStreamUrl(File file) {
+        String base = getCacheDir().getAbsolutePath() + File.separator;
+        String abs = file.getAbsolutePath();
+        String rel = abs.startsWith(base) ? abs.substring(base.length()) : file.getName();
+        return "/__capture__/" + Uri.encode(rel, "/");
+    }
+
+    /**
+     * Serve a captured file (under the app cache) to the webview with HTTP Range
+     * support, so &lt;video&gt; can stream and seek a clip of any length without
+     * inlining it as a data URL.
+     */
+    private WebResourceResponse serveCaptureFile(String relPath, WebResourceRequest request) {
+        try {
+            File cache = getCacheDir();
+            File file = new File(cache, Uri.decode(relPath));
+            // Path-traversal guard: only ever serve files under the cache dir.
+            if (!file.getCanonicalPath().startsWith(cache.getCanonicalPath() + File.separator)
+                    || !file.exists() || !file.isFile()) {
+                return new WebResourceResponse("text/plain", "UTF-8", 404, "Not Found",
+                        new java.util.HashMap<>(), new java.io.ByteArrayInputStream(new byte[0]));
+            }
+            String name = file.getName().toLowerCase();
+            String mime = name.endsWith(".mp4") ? "video/mp4"
+                    : name.endsWith(".mov") ? "video/quicktime"
+                    : name.endsWith(".jpg") || name.endsWith(".jpeg") ? "image/jpeg"
+                    : name.endsWith(".png") ? "image/png" : "application/octet-stream";
+            long length = file.length();
+            java.util.Map<String, String> reqHeaders = request.getRequestHeaders();
+            String range = reqHeaders != null ? reqHeaders.get("Range") : null;
+            if (range == null && reqHeaders != null) range = reqHeaders.get("range");
+
+            java.util.Map<String, String> headers = new java.util.HashMap<>();
+            headers.put("Accept-Ranges", "bytes");
+            headers.put("Cache-Control", "no-store");
+
+            if (range != null && range.startsWith("bytes=")) {
+                long start = 0, end = length - 1;
+                String spec = range.substring(6).trim();
+                int dash = spec.indexOf('-');
+                if (dash >= 0) {
+                    try {
+                        if (dash > 0) start = Long.parseLong(spec.substring(0, dash).trim());
+                        String e = spec.substring(dash + 1).trim();
+                        if (!e.isEmpty()) end = Long.parseLong(e);
+                    } catch (NumberFormatException ignored) { }
+                }
+                if (start < 0) start = 0;
+                if (end >= length) end = length - 1;
+                if (start > end) { start = 0; end = length - 1; }
+                long count = end - start + 1;
+                java.io.InputStream in = new java.io.FileInputStream(file);
+                long toSkip = start;
+                while (toSkip > 0) {
+                    long s = in.skip(toSkip);
+                    if (s <= 0) break;
+                    toSkip -= s;
+                }
+                headers.put("Content-Range", "bytes " + start + "-" + end + "/" + length);
+                headers.put("Content-Length", String.valueOf(count));
+                return new WebResourceResponse(mime, null, 206, "Partial Content",
+                        headers, new LimitedInputStream(in, count));
+            }
+            headers.put("Content-Length", String.valueOf(length));
+            return new WebResourceResponse(mime, null, 200, "OK", headers,
+                    new java.io.FileInputStream(file));
+        } catch (Exception e) {
+            Log.e(TAG, "serveCaptureFile failed", e);
+            return new WebResourceResponse("text/plain", "UTF-8", 500, "Error",
+                    new java.util.HashMap<>(), new java.io.ByteArrayInputStream(new byte[0]));
+        }
+    }
+
+    /** Wraps a stream to yield at most a fixed number of bytes (for Range responses). */
+    private static final class LimitedInputStream extends java.io.FilterInputStream {
+        private long remaining;
+        LimitedInputStream(java.io.InputStream in, long limit) {
+            super(in);
+            this.remaining = limit;
+        }
+        @Override public int read() throws java.io.IOException {
+            if (remaining <= 0) return -1;
+            int b = super.read();
+            if (b >= 0) remaining--;
+            return b;
+        }
+        @Override public int read(byte[] b, int off, int len) throws java.io.IOException {
+            if (remaining <= 0) return -1;
+            int n = super.read(b, off, (int) Math.min(len, remaining));
+            if (n > 0) remaining -= n;
+            return n;
+        }
+    }
+
+    /**
+     * Launch the system document picker. Results are copied into the app's
+     * cache directory so Go receives real filesystem paths. Called by
+     * WailsBridge on the main thread.
+     */
+    public void launchFilePicker(int callbackID, boolean multiple) {
+        synchronized (this) {
+            if (pendingFilePickerCallbackID != -1) {
+                // Only one picker can be in flight
+                bridge.filePickerDone(callbackID);
+                return;
+            }
+            pendingFilePickerCallbackID = callbackID;
+        }
+
+        Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
+        intent.addCategory(Intent.CATEGORY_OPENABLE);
+        intent.setType("*/*");
+        intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, multiple);
+        try {
+            startActivityForResult(intent, FILE_PICKER_REQUEST);
+        } catch (Exception e) {
+            Log.e(TAG, "Failed to launch file picker", e);
+            pendingFilePickerCallbackID = -1;
+            bridge.filePickerDone(callbackID);
+        }
+    }
+
+    @Override
+    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
+        super.onActivityResult(requestCode, resultCode, data);
+        if (requestCode == PHOTO_CAPTURE_REQUEST || requestCode == VIDEO_CAPTURE_REQUEST) {
+            handleCaptureResult(resultCode, data);
+            return;
+        }
+        if (requestCode != FILE_PICKER_REQUEST) {
+            return;
+        }
+        final int callbackID = pendingFilePickerCallbackID;
+        pendingFilePickerCallbackID = -1;
+        if (callbackID == -1) {
+            return;
+        }
+
+        final List<Uri> uris = new ArrayList<>();
+        if (resultCode == RESULT_OK && data != null) {
+            if (data.getClipData() != null) {
+                for (int i = 0; i < data.getClipData().getItemCount(); i++) {
+                    uris.add(data.getClipData().getItemAt(i).getUri());
+                }
+            } else if (data.getData() != null) {
+                uris.add(data.getData());
+            }
+        }
+
+        // Copy the documents off the main thread, then notify Go
+        new Thread(() -> {
+            for (Uri uri : uris) {
+                String path = copyUriToCache(uri);
+                if (path != null) {
+                    bridge.filePickerResult(callbackID, path);
+                }
+            }
+            bridge.filePickerDone(callbackID);
+        }).start();
+    }
+
+    /**
+     * Copy a content URI into the app cache and return its filesystem path.
+     */
+    @Nullable
+    private String copyUriToCache(Uri uri) {
+        String name = "document";
+        try (Cursor cursor = getContentResolver().query(uri, null, null, null, null)) {
+            if (cursor != null && cursor.moveToFirst()) {
+                int idx = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME);
+                if (idx >= 0 && cursor.getString(idx) != null) {
+                    name = new File(cursor.getString(idx)).getName();
+                }
+            }
+        } catch (Exception ignored) {
+        }
+
+        try {
+            File dir = new File(getCacheDir(), "wails-picker/" + System.nanoTime());
+            if (!dir.mkdirs()) {
+                return null;
+            }
+            File out = new File(dir, name);
+            try (InputStream in = getContentResolver().openInputStream(uri);
+                 OutputStream os = new FileOutputStream(out)) {
+                if (in == null) {
+                    return null;
+                }
+                byte[] buf = new byte[64 * 1024];
+                int n;
+                while ((n = in.read(buf)) > 0) {
+                    os.write(buf, 0, n);
+                }
+            }
+            return out.getAbsolutePath();
+        } catch (Exception e) {
+            Log.e(TAG, "Failed to copy picked document", e);
+            return null;
+        }
+    }
+
+    /**
+     * Execute JavaScript in the WebView from the Go side
+     */
+    public void executeJavaScript(final String js) {
+        runOnUiThread(() -> {
+            if (webView != null) {
+                webView.evaluateJavascript(js, null);
+            }
+        });
+    }
+
+    // ---- System events ---------------------------------------------------
+    // Battery/power, screen lock and network connectivity are surfaced to JS as
+    // "system:*" events. The OS broadcasts used here (ACTION_BATTERY_CHANGED,
+    // SCREEN_OFF, USER_PRESENT, POWER_SAVE_MODE_CHANGED) are protected system
+    // broadcasts, so dynamic registration needs no RECEIVER_* export flag.
+
+    private void registerSystemEventReceivers() {
+        // Battery + charging state (sticky broadcast: the current value is
+        // delivered to the receiver immediately on registration).
+        batteryReceiver = new BroadcastReceiver() {
+            @Override public void onReceive(Context context, Intent intent) {
+                emitBattery(intent);
+            }
+        };
+        registerReceiver(batteryReceiver, new IntentFilter(Intent.ACTION_BATTERY_CHANGED));
+
+        // Low-power (battery saver) mode toggles → re-emit battery with the flag.
+        powerSaveReceiver = new BroadcastReceiver() {
+            @Override public void onReceive(Context context, Intent intent) {
+                emitBattery(registerSticky(Intent.ACTION_BATTERY_CHANGED));
+            }
+        };
+        registerReceiver(powerSaveReceiver,
+                new IntentFilter(PowerManager.ACTION_POWER_SAVE_MODE_CHANGED));
+
+        // Screen lock / unlock. SCREEN_OFF ≈ locked; USER_PRESENT = unlocked.
+        screenReceiver = new BroadcastReceiver() {
+            @Override public void onReceive(Context context, Intent intent) {
+                String action = intent.getAction();
+                if (Intent.ACTION_SCREEN_OFF.equals(action)) {
+                    emitLock(true);
+                } else if (Intent.ACTION_USER_PRESENT.equals(action)) {
+                    emitLock(false);
+                }
+            }
+        };
+        IntentFilter screenFilter = new IntentFilter();
+        screenFilter.addAction(Intent.ACTION_SCREEN_OFF);
+        screenFilter.addAction(Intent.ACTION_USER_PRESENT);
+        registerReceiver(screenReceiver, screenFilter);
+
+        // Network connectivity / transport type / cellular signal strength.
+        connectivityManager = (ConnectivityManager) getSystemService(Context.CONNECTIVITY_SERVICE);
+        if (connectivityManager != null) {
+            networkCallback = new ConnectivityManager.NetworkCallback() {
+                @Override public void onAvailable(Network network) { emitNetwork(network); }
+                @Override public void onLost(Network network) { emitNetworkDisconnected(); }
+                @Override public void onCapabilitiesChanged(Network network, NetworkCapabilities caps) {
+                    emitNetwork(network);
+                }
+            };
+            try {
+                connectivityManager.registerDefaultNetworkCallback(networkCallback);
+            } catch (Exception e) {
+                Log.e(TAG, "registerDefaultNetworkCallback failed", e);
+            }
+        }
+    }
+
+    private void unregisterSystemEventReceivers() {
+        safeUnregister(batteryReceiver);
+        batteryReceiver = null;
+        safeUnregister(powerSaveReceiver);
+        powerSaveReceiver = null;
+        safeUnregister(screenReceiver);
+        screenReceiver = null;
+        if (connectivityManager != null && networkCallback != null) {
+            try {
+                connectivityManager.unregisterNetworkCallback(networkCallback);
+            } catch (Exception ignored) {
+            }
+            networkCallback = null;
+        }
+    }
+
+    private void safeUnregister(BroadcastReceiver r) {
+        if (r != null) {
+            try {
+                unregisterReceiver(r);
+            } catch (Exception ignored) {
+            }
+        }
+    }
+
+    /** Read the current sticky value for an action without a standing receiver. */
+    @Nullable
+    private Intent registerSticky(String action) {
+        return registerReceiver(null, new IntentFilter(action));
+    }
+
+    /** Push current battery / network / theme so a freshly-loaded UI is populated. */
+    private void emitSystemSnapshot() {
+        emitBattery(registerSticky(Intent.ACTION_BATTERY_CHANGED));
+        if (connectivityManager != null) {
+            Network active = connectivityManager.getActiveNetwork();
+            if (active != null) {
+                emitNetwork(active);
+            } else {
+                emitNetworkDisconnected();
+            }
+        }
+        emitTheme();
+    }
+
+    private void emitBattery(@Nullable Intent batteryStatus) {
+        try {
+            float level = -1f;
+            String state = "unknown";
+            if (batteryStatus != null) {
+                int lvl = batteryStatus.getIntExtra(BatteryManager.EXTRA_LEVEL, -1);
+                int scale = batteryStatus.getIntExtra(BatteryManager.EXTRA_SCALE, -1);
+                if (lvl >= 0 && scale > 0) {
+                    level = lvl / (float) scale;
+                }
+                switch (batteryStatus.getIntExtra(BatteryManager.EXTRA_STATUS, -1)) {
+                    case BatteryManager.BATTERY_STATUS_CHARGING: state = "charging"; break;
+                    case BatteryManager.BATTERY_STATUS_FULL: state = "full"; break;
+                    case BatteryManager.BATTERY_STATUS_DISCHARGING:
+                    case BatteryManager.BATTERY_STATUS_NOT_CHARGING: state = "unplugged"; break;
+                    default: state = "unknown"; break;
+                }
+            }
+            boolean lowPower = false;
+            PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE);
+            if (pm != null) {
+                lowPower = pm.isPowerSaveMode();
+            }
+            JSONObject o = new JSONObject();
+            o.put("level", (double) level);
+            o.put("state", state);
+            o.put("lowPowerMode", lowPower);
+            if (bridge != null) bridge.emitSystemEvent("android:BatteryChanged", o.toString());
+        } catch (Exception e) {
+            Log.e(TAG, "emitBattery failed", e);
+        }
+    }
+
+    private void emitNetwork(@Nullable Network network) {
+        try {
+            boolean connected = false;
+            String type = "none";
+            boolean metered = false;
+            Integer signal = null;
+            if (connectivityManager != null && network != null) {
+                NetworkCapabilities caps = connectivityManager.getNetworkCapabilities(network);
+                if (caps != null) {
+                    connected = caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET);
+                    if (caps.hasTransport(NetworkCapabilities.TRANSPORT_WIFI)) {
+                        type = "wifi";
+                    } else if (caps.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR)) {
+                        type = "cellular";
+                    } else if (caps.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET)) {
+                        type = "wired";
+                    } else {
+                        type = "other";
+                    }
+                    metered = !caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED);
+                    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+                        int s = caps.getSignalStrength();
+                        if (s != Integer.MIN_VALUE) {
+                            signal = s; // dBm; closer to 0 is a stronger signal
+                        }
+                    }
+                }
+            }
+            JSONObject o = new JSONObject();
+            o.put("connected", connected);
+            o.put("type", type);
+            o.put("metered", metered);
+            if (signal != null) {
+                o.put("signal", (int) signal);
+            }
+            if (bridge != null) bridge.emitSystemEvent("android:NetworkChanged", o.toString());
+        } catch (Exception e) {
+            Log.e(TAG, "emitNetwork failed", e);
+        }
+    }
+
+    private void emitNetworkDisconnected() {
+        try {
+            JSONObject o = new JSONObject();
+            o.put("connected", false);
+            o.put("type", "none");
+            o.put("metered", false);
+            if (bridge != null) bridge.emitSystemEvent("android:NetworkChanged", o.toString());
+        } catch (Exception ignored) {
+        }
+    }
+
+    private void emitLock(boolean locked) {
+        // Lock/unlock are signals (no payload); name carries the state.
+        if (bridge != null) {
+            bridge.emitSystemEvent(locked ? "android:ScreenLocked" : "android:ScreenUnlocked", "{}");
+        }
+    }
+
+    private void emitTheme() {
+        try {
+            int mode = getResources().getConfiguration().uiMode & Configuration.UI_MODE_NIGHT_MASK;
+            JSONObject o = new JSONObject();
+            // "isDarkMode" matches the context key the desktop platforms use.
+            o.put("isDarkMode", mode == Configuration.UI_MODE_NIGHT_YES);
+            if (bridge != null) bridge.emitSystemEvent("android:ThemeChanged", o.toString());
+        } catch (Exception ignored) {
+        }
+    }
+
+    @Override
+    public void onConfigurationChanged(Configuration newConfig) {
+        super.onConfigurationChanged(newConfig);
+        // Fires for light/dark switches because the manifest lists uiMode in
+        // android:configChanges (otherwise the activity would be recreated).
+        emitTheme();
+    }
+
+    @Override
+    protected void onStart() {
+        super.onStart();
+        // Battery: only monitor system events while the app is visible.
+        if (!systemReceiversRegistered) {
+            registerSystemEventReceivers();
+            systemReceiversRegistered = true;
+        }
+        if (bridge != null) {
+            bridge.onStart();
+        }
+    }
+
+    @Override
+    protected void onResume() {
+        super.onResume();
+        if (bridge != null) {
+            bridge.onResume();
+        }
+        // The all-files grant happens on a Settings screen in another
+        // task, so a resume is how the app finds out it was given.
+        emitStorageAccess();
+    }
+
+    @Override
+    protected void onPause() {
+        super.onPause();
+        if (bridge != null) {
+            bridge.onPause();
+        }
+    }
+
+    @Override
+    protected void onStop() {
+        super.onStop();
+        if (systemReceiversRegistered) {
+            unregisterSystemEventReceivers();
+            systemReceiversRegistered = false;
+        }
+        if (bridge != null) {
+            bridge.onStop();
+        }
+    }
+
+    @Override
+    public void onLowMemory() {
+        super.onLowMemory();
+        if (bridge != null) {
+            bridge.onLowMemory();
+        }
+    }
+
+    @Override
+    protected void onDestroy() {
+        super.onDestroy();
+        unregisterSystemEventReceivers();
+        if (bridge != null) {
+            bridge.shutdown();
+        }
+        if (webView != null) {
+            webView.destroy();
+        }
+    }
+
+    /**
+     * Keep the web content inside the safe area.
+     *
+     * <p>targetSdk 35 is Android 15, which lays every app out
+     * edge-to-edge and ignores the {@code statusBarColor} and
+     * {@code navigationBarColor} this app's theme still sets. The
+     * WebView is {@code match_parent}, so the page's bottom band -- the
+     * transport and, on a phone, the tab bar -- was drawn underneath the
+     * gesture bar and reported from a device as "I can't see the
+     * playback controls, they seem to be off screen".
+     *
+     * <p>No web-tier test can see this: a browser viewport has no system
+     * bars, so the phone specs at 390x844 render a shell that fits
+     * while the device does not.
+     *
+     * <p>The insets are applied as padding and the window insets are
+     * returned rather than consumed, so the WebView is laid out inside
+     * them. {@code ime()} is in the mask because the same reasoning
+     * covers the keyboard: a focused search box that the keyboard
+     * covers is the same bug one surface over.
+     */
+    private void applyWindowInsets() {
+        final View container = findViewById(R.id.main_container);
+
+        if (container == null) {
+            return;
+        }
+
+        ViewCompat.setOnApplyWindowInsetsListener(container, (view, windowInsets) -> {
+            Insets insets = windowInsets.getInsets(
+                    WindowInsetsCompat.Type.systemBars()
+                            | WindowInsetsCompat.Type.displayCutout()
+                            | WindowInsetsCompat.Type.ime());
+
+            view.setPadding(insets.left, insets.top, insets.right, insets.bottom);
+
+            return windowInsets;
+        });
+
+        // The padded band shows the window background, which is dark
+        // (this app's own default ramp is black), so the system's icons
+        // have to be the light set or they vanish into it. The theme is
+        // DayNight and would otherwise ask for dark icons in light mode.
+        WindowInsetsControllerCompat controller =
+                WindowCompat.getInsetsController(getWindow(), getWindow().getDecorView());
+
+        controller.setAppearanceLightStatusBars(false);
+        controller.setAppearanceLightNavigationBars(false);
+    }
+
+    @Override
+    public void onBackPressed() {
+        // The frontend records every navigation as a history entry, so
+        // this is the app's own back stack: `canGoBack()` is false only
+        // at the launch entry, which is where back should leave.
+        if (webView != null && webView.canGoBack()) {
+            webView.goBack();
+        } else {
+            super.onBackPressed();
+        }
+    }
+}

build/android/app/src/main/java/com/wails/app/WailsForegroundService.java

@@ -0,0 +1,553 @@
+package com.wails.app;
+
+import android.app.Notification;
+import android.app.NotificationChannel;
+import android.app.NotificationManager;
+import android.app.PendingIntent;
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.content.IntentFilter;
+import android.content.pm.ServiceInfo;
+import android.graphics.Bitmap;
+import android.graphics.BitmapFactory;
+import android.media.AudioAttributes;
+import android.media.AudioFocusRequest;
+import android.media.AudioManager;
+import android.media.MediaMetadata;
+import android.media.session.MediaSession;
+import android.media.session.PlaybackState;
+import android.os.Build;
+import android.os.Handler;
+import android.os.IBinder;
+import android.os.Looper;
+import android.util.Log;
+
+import androidx.annotation.Nullable;
+
+import org.json.JSONObject;
+
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+/**
+ * The foreground service that keeps playback alive with the screen off, and
+ * the app's whole media-control surface: a {@link MediaSession} for the lock
+ * screen and headset buttons, a transport notification, and audio focus.
+ *
+ * <p>The scaffold shipped this as a generic "keep the process alive" service
+ * typed {@code dataSync}. YellowJacket's reason for staying alive in the
+ * background is that a song is playing, so it is {@code mediaPlayback} — the
+ * manifest and {@code startForeground} must agree on that or the call throws.
+ *
+ * <p>It is driven entirely from Go. {@code backend/mediacontrols/android.go}
+ * pushes a JSON payload through
+ * {@link WailsBridge#startForegroundService(String)}, and every command the
+ * user gives here — a notification button, the lock screen, a headset, or the
+ * OS taking audio focus away — goes back the other way as a
+ * {@code yj:media:command} event. Nothing about playback is decided here: this
+ * class renders state and reports intent.
+ */
+public class WailsForegroundService extends android.app.Service {
+    public static final String ACTION_START = "com.wails.app.FGS_START";
+
+    // Transport actions, delivered to ourselves by the notification's
+    // PendingIntents. getService rather than a broadcast: a receiver would
+    // have to be exported or registered, and this service is already the
+    // thing that has to be running for any of them to be meaningful.
+    private static final String ACTION_PLAY = "com.wails.app.MEDIA_PLAY";
+    private static final String ACTION_PAUSE = "com.wails.app.MEDIA_PAUSE";
+    private static final String ACTION_NEXT = "com.wails.app.MEDIA_NEXT";
+    private static final String ACTION_PREVIOUS = "com.wails.app.MEDIA_PREVIOUS";
+
+    private static final String TAG = "WailsMedia";
+    private static final String CHANNEL_ID = "yellowjacket_playback";
+    private static final int NOTIFICATION_ID = 0x57A1; // "WAI"
+    private static final String COMMAND_EVENT = "yj:media:command";
+
+    /** Cover art is decoded down to this, which is larger than any lock screen. */
+    private static final int ART_MAX_PX = 512;
+
+    /**
+     * Whether an instance is alive. {@link WailsBridge} reads it to decide
+     * between startForegroundService and startService: from Android 12 an app
+     * in the background may not <em>start</em> a foreground service, but it
+     * may go on delivering intents to one it already has — and every update
+     * after the first (a track change with the screen off, most of them) is
+     * exactly that case.
+     */
+    static volatile boolean running = false;
+
+    private final Handler mainHandler = new Handler(Looper.getMainLooper());
+    private final ExecutorService artExecutor = Executors.newSingleThreadExecutor();
+
+    private MediaSession session;
+    private AudioManager audioManager;
+    private AudioFocusRequest focusRequest; // API 26+ only.
+    private AudioManager.OnAudioFocusChangeListener focusListener;
+
+    private String title = "";
+    private String artist = "";
+    private String album = "";
+    private String artPath = "";
+    private long durationMs = 0;
+    private long positionMs = 0;
+    private boolean playing = false;
+
+    private Bitmap art;
+
+    private boolean hasFocus = false;
+    /**
+     * Whether *we* paused because focus went away. Only then does regaining it
+     * resume: a user who paused during a phone call did not ask us to start
+     * again when it ended.
+     */
+    private boolean pausedByFocusLoss = false;
+
+    private boolean noisyRegistered = false;
+
+    /** Headphones pulled out. Anything else and the room hears the album. */
+    private final BroadcastReceiver noisyReceiver = new BroadcastReceiver() {
+        @Override
+        public void onReceive(Context context, Intent intent) {
+            if (AudioManager.ACTION_AUDIO_BECOMING_NOISY.equals(intent.getAction())) {
+                emitCommand("pause");
+            }
+        }
+    };
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        running = true;
+        audioManager = (AudioManager) getSystemService(AUDIO_SERVICE);
+        createChannel();
+        createSession();
+    }
+
+    @Override
+    public int onStartCommand(Intent intent, int flags, int startId) {
+        String action = intent == null ? null : intent.getAction();
+
+        if (ACTION_PLAY.equals(action)) {
+            emitCommand("play");
+        } else if (ACTION_PAUSE.equals(action)) {
+            emitCommand("pause");
+        } else if (ACTION_NEXT.equals(action)) {
+            emitCommand("next");
+        } else if (ACTION_PREVIOUS.equals(action)) {
+            emitCommand("previous");
+        } else if (intent != null) {
+            applyPayload(intent);
+        }
+
+        // Unconditionally, on every path: a service started with
+        // startForegroundService that returns from onStartCommand without
+        // calling startForeground is killed with a
+        // ForegroundServiceDidNotStartInTimeException.
+        goForeground();
+
+        return START_STICKY;
+    }
+
+    /**
+     * Read the state Go pushed. "payload" is the whole JSON document; the
+     * title/text extras are the scaffold's original contract and are kept as a
+     * fallback so a non-media caller still gets a sensible notification.
+     */
+    private void applyPayload(Intent intent) {
+        String payload = intent.getStringExtra("payload");
+        if (payload == null || payload.isEmpty()) {
+            if (intent.getStringExtra("title") != null) {
+                title = intent.getStringExtra("title");
+            }
+            if (intent.getStringExtra("text") != null) {
+                artist = intent.getStringExtra("text");
+            }
+            return;
+        }
+
+        try {
+            JSONObject o = new JSONObject(payload);
+            title = o.optString("title", "");
+            artist = o.optString("artist", "");
+            album = o.optString("album", "");
+            durationMs = o.optLong("durationSec", 0) * 1000L;
+            positionMs = o.optLong("positionSec", 0) * 1000L;
+            playing = "playing".equals(o.optString("state", "paused"));
+
+            String path = o.optString("artPath", "");
+            if (!path.equals(artPath)) {
+                artPath = path;
+                loadArt(path);
+            }
+        } catch (Exception e) {
+            Log.e(TAG, "bad media payload", e);
+            return;
+        }
+
+        if (playing) {
+            requestFocus();
+            registerNoisy();
+        } else {
+            unregisterNoisy();
+        }
+
+        updateSession();
+    }
+
+    // --- MediaSession ------------------------------------------------------
+
+    private void createSession() {
+        session = new MediaSession(this, "YellowJacket");
+        session.setFlags(MediaSession.FLAG_HANDLES_MEDIA_BUTTONS
+                | MediaSession.FLAG_HANDLES_TRANSPORT_CONTROLS);
+        session.setCallback(new MediaSession.Callback() {
+            @Override
+            public void onPlay() {
+                emitCommand("play");
+            }
+
+            @Override
+            public void onPause() {
+                emitCommand("pause");
+            }
+
+            @Override
+            public void onStop() {
+                emitCommand("stop");
+            }
+
+            @Override
+            public void onSkipToNext() {
+                emitCommand("next");
+            }
+
+            @Override
+            public void onSkipToPrevious() {
+                emitCommand("previous");
+            }
+
+            @Override
+            public void onSeekTo(long pos) {
+                try {
+                    JSONObject o = new JSONObject();
+                    o.put("command", "seek");
+                    o.put("positionSec", pos / 1000L);
+                    WailsBridge.emitFromService(COMMAND_EVENT, o.toString());
+                } catch (Exception e) {
+                    Log.e(TAG, "seek command failed", e);
+                }
+            }
+        });
+        session.setActive(true);
+    }
+
+    private void updateSession() {
+        MediaMetadata.Builder meta = new MediaMetadata.Builder()
+                .putString(MediaMetadata.METADATA_KEY_TITLE, title)
+                .putString(MediaMetadata.METADATA_KEY_ARTIST, artist)
+                .putString(MediaMetadata.METADATA_KEY_ALBUM, album)
+                .putLong(MediaMetadata.METADATA_KEY_DURATION, durationMs);
+        if (art != null) {
+            meta.putBitmap(MediaMetadata.METADATA_KEY_ALBUM_ART, art);
+        }
+        session.setMetadata(meta.build());
+
+        // The position is an anchor, not a clock: the state carries the
+        // playback speed and the OS interpolates from here, which is why the
+        // Go side only pushes on a real state change or a seek.
+        PlaybackState state = new PlaybackState.Builder()
+                .setActions(PlaybackState.ACTION_PLAY
+                        | PlaybackState.ACTION_PAUSE
+                        | PlaybackState.ACTION_PLAY_PAUSE
+                        | PlaybackState.ACTION_STOP
+                        | PlaybackState.ACTION_SKIP_TO_NEXT
+                        | PlaybackState.ACTION_SKIP_TO_PREVIOUS
+                        | PlaybackState.ACTION_SEEK_TO)
+                .setState(playing ? PlaybackState.STATE_PLAYING : PlaybackState.STATE_PAUSED,
+                        positionMs, playing ? 1.0f : 0.0f)
+                .build();
+        session.setPlaybackState(state);
+    }
+
+    // --- Notification ------------------------------------------------------
+
+    private void createChannel() {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+            return;
+        }
+        NotificationManager nm = (NotificationManager) getSystemService(NOTIFICATION_SERVICE);
+        // LOW: a transport notification is a control surface, not news, and
+        // IMPORTANCE_DEFAULT would make a sound on every track change.
+        NotificationChannel ch = new NotificationChannel(
+                CHANNEL_ID, "Playback", NotificationManager.IMPORTANCE_LOW);
+        ch.setShowBadge(false);
+        nm.createNotificationChannel(ch);
+    }
+
+    private void goForeground() {
+        Notification n = buildNotification();
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            startForeground(NOTIFICATION_ID, n, ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PLAYBACK);
+        } else {
+            startForeground(NOTIFICATION_ID, n);
+        }
+    }
+
+    @SuppressWarnings("deprecation")
+    private Notification buildNotification() {
+        Notification.Builder b = Build.VERSION.SDK_INT >= Build.VERSION_CODES.O
+                ? new Notification.Builder(this, CHANNEL_ID)
+                : new Notification.Builder(this);
+
+        b.setSmallIcon(android.R.drawable.ic_media_play)
+                .setContentTitle(title.isEmpty() ? getString(R.string.app_name) : title)
+                .setContentText(artist)
+                .setSubText(album)
+                .setOngoing(playing)
+                .setVisibility(Notification.VISIBILITY_PUBLIC)
+                .setContentIntent(launchIntent());
+
+        if (art != null) {
+            b.setLargeIcon(art);
+        }
+
+        b.addAction(new Notification.Action.Builder(
+                android.R.drawable.ic_media_previous, "Previous",
+                transportIntent(ACTION_PREVIOUS, 1)).build());
+        b.addAction(playing
+                ? new Notification.Action.Builder(android.R.drawable.ic_media_pause, "Pause",
+                        transportIntent(ACTION_PAUSE, 2)).build()
+                : new Notification.Action.Builder(android.R.drawable.ic_media_play, "Play",
+                        transportIntent(ACTION_PLAY, 3)).build());
+        b.addAction(new Notification.Action.Builder(
+                android.R.drawable.ic_media_next, "Next",
+                transportIntent(ACTION_NEXT, 4)).build());
+
+        Notification.MediaStyle style = new Notification.MediaStyle()
+                .setShowActionsInCompactView(0, 1, 2);
+        if (session != null) {
+            style.setMediaSession(session.getSessionToken());
+        }
+        b.setStyle(style);
+
+        return b.build();
+    }
+
+    private PendingIntent transportIntent(String action, int requestCode) {
+        Intent i = new Intent(this, WailsForegroundService.class).setAction(action);
+        return PendingIntent.getService(this, requestCode, i, pendingIntentFlags());
+    }
+
+    private PendingIntent launchIntent() {
+        Intent launch = getPackageManager().getLaunchIntentForPackage(getPackageName());
+        if (launch == null) {
+            return null;
+        }
+        return PendingIntent.getActivity(this, 0, launch, pendingIntentFlags());
+    }
+
+    private int pendingIntentFlags() {
+        // Mandatory from S, unavailable before M.
+        return Build.VERSION.SDK_INT >= Build.VERSION_CODES.M
+                ? PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT
+                : PendingIntent.FLAG_UPDATE_CURRENT;
+    }
+
+    // --- Cover art ---------------------------------------------------------
+
+    /**
+     * Decode the cover off the main thread and redraw when it lands. A track
+     * change must not wait on a JPEG, and the notification is correct without
+     * one — it simply has no image until this returns.
+     */
+    private void loadArt(final String path) {
+        art = null;
+        if (path == null || path.isEmpty()) {
+            return;
+        }
+
+        artExecutor.execute(() -> {
+            Bitmap decoded = decodeScaled(path);
+            mainHandler.post(() -> {
+                // The track may have changed while we decoded.
+                if (!path.equals(artPath)) {
+                    return;
+                }
+                art = decoded;
+                updateSession();
+                goForeground();
+            });
+        });
+    }
+
+    private Bitmap decodeScaled(String path) {
+        try {
+            BitmapFactory.Options bounds = new BitmapFactory.Options();
+            bounds.inJustDecodeBounds = true;
+            BitmapFactory.decodeFile(path, bounds);
+
+            int longest = Math.max(bounds.outWidth, bounds.outHeight);
+            int sample = 1;
+            while (longest / sample > ART_MAX_PX) {
+                sample *= 2;
+            }
+
+            BitmapFactory.Options opts = new BitmapFactory.Options();
+            opts.inSampleSize = sample;
+            return BitmapFactory.decodeFile(path, opts);
+        } catch (Throwable t) {
+            // OutOfMemoryError included: a missing cover is not a crash.
+            Log.w(TAG, "cover art decode failed: " + path, t);
+            return null;
+        }
+    }
+
+    // --- Audio focus -------------------------------------------------------
+
+    private void requestFocus() {
+        if (hasFocus || audioManager == null) {
+            return;
+        }
+
+        if (focusListener == null) {
+            focusListener = this::onFocusChange;
+        }
+
+        int result;
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            AudioAttributes attrs = new AudioAttributes.Builder()
+                    .setUsage(AudioAttributes.USAGE_MEDIA)
+                    .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
+                    .build();
+            // No setWillPauseWhenDucked: from Oreo the framework ducks us
+            // itself and reports no CAN_DUCK loss, so the Go-side duck below
+            // is a pre-Oreo path. Asking to be told instead would mean
+            // pausing for every notification tone.
+            focusRequest = new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
+                    .setAudioAttributes(attrs)
+                    .setOnAudioFocusChangeListener(focusListener, mainHandler)
+                    .build();
+            result = audioManager.requestAudioFocus(focusRequest);
+        } else {
+            result = requestFocusLegacy();
+        }
+
+        hasFocus = result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED;
+    }
+
+    @SuppressWarnings("deprecation")
+    private int requestFocusLegacy() {
+        return audioManager.requestAudioFocus(focusListener,
+                AudioManager.STREAM_MUSIC, AudioManager.AUDIOFOCUS_GAIN);
+    }
+
+    @SuppressWarnings("deprecation")
+    private void abandonFocus() {
+        if (!hasFocus || audioManager == null) {
+            return;
+        }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && focusRequest != null) {
+            audioManager.abandonAudioFocusRequest(focusRequest);
+        } else {
+            audioManager.abandonAudioFocus(focusListener);
+        }
+        hasFocus = false;
+    }
+
+    private void onFocusChange(int change) {
+        switch (change) {
+            case AudioManager.AUDIOFOCUS_LOSS:
+                // Someone else owns the output now, for good.
+                hasFocus = false;
+                pausedByFocusLoss = false;
+                emitCommand("pause");
+                break;
+            case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT:
+                // A phone call. Remember that the pause was ours to undo.
+                pausedByFocusLoss = playing;
+                emitCommand("pause");
+                break;
+            case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK:
+                emitDuck(true);
+                break;
+            case AudioManager.AUDIOFOCUS_GAIN:
+                hasFocus = true;
+                emitDuck(false);
+                if (pausedByFocusLoss) {
+                    pausedByFocusLoss = false;
+                    emitCommand("play");
+                }
+                break;
+            default:
+                break;
+        }
+    }
+
+    // --- Noisy (headphones) ------------------------------------------------
+
+    private void registerNoisy() {
+        if (noisyRegistered) {
+            return;
+        }
+        registerReceiver(noisyReceiver,
+                new IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY));
+        noisyRegistered = true;
+    }
+
+    private void unregisterNoisy() {
+        if (!noisyRegistered) {
+            return;
+        }
+        try {
+            unregisterReceiver(noisyReceiver);
+        } catch (IllegalArgumentException ignored) {
+            // Already gone; nothing to undo.
+        }
+        noisyRegistered = false;
+    }
+
+    // --- Talking to Go -----------------------------------------------------
+
+    private void emitCommand(String command) {
+        try {
+            JSONObject o = new JSONObject();
+            o.put("command", command);
+            WailsBridge.emitFromService(COMMAND_EVENT, o.toString());
+        } catch (Exception e) {
+            Log.e(TAG, "command emit failed: " + command, e);
+        }
+    }
+
+    private void emitDuck(boolean on) {
+        try {
+            JSONObject o = new JSONObject();
+            o.put("command", "duck");
+            o.put("on", on);
+            WailsBridge.emitFromService(COMMAND_EVENT, o.toString());
+        } catch (Exception e) {
+            Log.e(TAG, "duck emit failed", e);
+        }
+    }
+
+    @Override
+    public void onDestroy() {
+        running = false;
+        unregisterNoisy();
+        abandonFocus();
+        if (session != null) {
+            session.setActive(false);
+            session.release();
+            session = null;
+        }
+        artExecutor.shutdownNow();
+        super.onDestroy();
+    }
+
+    @Nullable
+    @Override
+    public IBinder onBind(Intent intent) {
+        return null;
+    }
+}

build/android/app/src/main/java/com/wails/app/WailsJSBridge.java

@@ -0,0 +1,151 @@
+package com.wails.app;
+
+import android.util.Log;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import android.webkit.JavascriptInterface;
+import android.webkit.WebView;
+import com.wails.app.BuildConfig;
+
+/**
+ * WailsJSBridge provides the JavaScript interface that allows the web frontend
+ * to communicate with the Go backend. This is exposed to JavaScript as the
+ * `window.wails` object.
+ *
+ * Similar to iOS's WKScriptMessageHandler but using Android's addJavascriptInterface.
+ */
+public class WailsJSBridge {
+    private static final String TAG = "WailsJSBridge";
+    private static final boolean DEBUG = BuildConfig.DEBUG;
+    // Pooled threads avoid unbounded thread creation under high call volume.
+    private static final ExecutorService executor = Executors.newCachedThreadPool();
+
+    private final WailsBridge bridge;
+    private final WebView webView;
+
+    public WailsJSBridge(WailsBridge bridge, WebView webView) {
+        this.bridge = bridge;
+        this.webView = webView;
+    }
+
+    /**
+     * Send a message to Go and return the response synchronously.
+     * Called from JavaScript: wails.invoke(message)
+     *
+     * @param message The message to send (JSON string)
+     * @return The response from Go (JSON string)
+     */
+    @JavascriptInterface
+    public String invoke(String message) {
+        if (DEBUG) Log.d(TAG, "Invoke called: " + message);
+        return bridge.handleMessage(message);
+    }
+
+    /**
+     * Send a message to Go asynchronously.
+     * The response will be sent back via a callback.
+     * Called from JavaScript: wails.invokeAsync(callbackId, message)
+     *
+     * @param callbackId The callback ID to use for the response
+     * @param message The message to send (JSON string)
+     */
+    @JavascriptInterface
+    public void invokeAsync(final String callbackId, final String payload) {
+        if (DEBUG) Log.d(TAG, "InvokeAsync called: " + payload);
+
+        // Handle off the JS thread so we don't block the WebView.
+        executor.execute(() -> {
+            try {
+                String response = bridge.handleRuntimeCall(payload);
+                sendCallback(callbackId, response, null);
+            } catch (Exception e) {
+                Log.e(TAG, "Error in async invoke", e);
+                sendCallback(callbackId, null, e.getMessage());
+            }
+        });
+    }
+
+    /**
+     * Log a message from JavaScript to Android's logcat
+     * Called from JavaScript: wails.log(level, message)
+     *
+     * @param level The log level (debug, info, warn, error)
+     * @param message The message to log
+     */
+    @JavascriptInterface
+    public void log(String level, String message) {
+        switch (level.toLowerCase()) {
+            case "debug":
+                Log.d(TAG + "/JS", message);
+                break;
+            case "info":
+                Log.i(TAG + "/JS", message);
+                break;
+            case "warn":
+                Log.w(TAG + "/JS", message);
+                break;
+            case "error":
+                Log.e(TAG + "/JS", message);
+                break;
+            default:
+                Log.v(TAG + "/JS", message);
+                break;
+        }
+    }
+
+    /**
+     * Get the platform name
+     * Called from JavaScript: wails.platform()
+     *
+     * @return "android"
+     */
+    @JavascriptInterface
+    public String platform() {
+        return "android";
+    }
+
+    /**
+     * Check if we're running in debug mode
+     * Called from JavaScript: wails.isDebug()
+     *
+     * @return true if debug build, false otherwise
+     */
+    @JavascriptInterface
+    public boolean isDebug() {
+        return BuildConfig.DEBUG;
+    }
+
+    /**
+     * Send a callback response to JavaScript
+     */
+    private void sendCallback(String callbackId, String result, String error) {
+        final String js;
+        if (error != null) {
+            js = String.format(
+                    "window._wailsAndroidCallback && window._wailsAndroidCallback('%s', null, '%s');",
+                    escapeJsString(callbackId),
+                    escapeJsString(error)
+            );
+        } else {
+            js = String.format(
+                    "window._wailsAndroidCallback && window._wailsAndroidCallback('%s', '%s', null);",
+                    escapeJsString(callbackId),
+                    escapeJsString(result != null ? result : "")
+            );
+        }
+
+        webView.post(() -> webView.evaluateJavascript(js, null));
+    }
+
+    private String escapeJsString(String str) {
+        if (str == null) return "";
+        return str.replace("\\", "\\\\")
+                .replace("'", "\\'")
+                .replace("\n", "\\n")
+                .replace("\r", "\\r")
+                // JS line terminators (U+2028/U+2029) must be escaped too; built via
+                // (char) casts so the Java lexer does not reinterpret them as newlines.
+                .replace(String.valueOf((char) 0x2028), "\\u2028")
+                .replace(String.valueOf((char) 0x2029), "\\u2029");
+    }
+}

build/android/app/src/main/java/com/wails/app/WailsPathHandler.java

@@ -0,0 +1,68 @@
+package com.wails.app;
+
+import android.net.Uri;
+import android.util.Log;
+import android.webkit.WebResourceResponse;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import androidx.webkit.WebViewAssetLoader;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * WailsPathHandler implements WebViewAssetLoader.PathHandler to serve assets
+ * from the Go asset server. This allows the WebView to load assets without
+ * using a network server, similar to iOS's WKURLSchemeHandler.
+ */
+public class WailsPathHandler implements WebViewAssetLoader.PathHandler {
+    private static final String TAG = "WailsPathHandler";
+    private static final boolean DEBUG = BuildConfig.DEBUG;
+
+    private final WailsBridge bridge;
+
+    public WailsPathHandler(WailsBridge bridge) {
+        this.bridge = bridge;
+    }
+
+    @Nullable
+    @Override
+    public WebResourceResponse handle(@NonNull String path) {
+        if (DEBUG) Log.d(TAG, "Handling path: " + path);
+
+        // Normalize path
+        if (path.isEmpty() || path.equals("/")) {
+            path = "/index.html";
+        }
+
+        // Get asset from Go
+        byte[] data = bridge.serveAsset(path, "GET", "{}");
+
+        if (data == null || data.length == 0) {
+            Log.w(TAG, "Asset not found: " + path);
+            return null; // Return null to let WebView handle 404
+        }
+
+        // Determine MIME type
+        String mimeType = bridge.getAssetMimeType(path);
+        if (DEBUG) Log.d(TAG, "Serving " + path + " with type " + mimeType + " (" + data.length + " bytes)");
+
+        // Create response
+        InputStream inputStream = new ByteArrayInputStream(data);
+        Map<String, String> headers = new HashMap<>();
+        headers.put("Access-Control-Allow-Origin", "*");
+        headers.put("Cache-Control", "no-cache");
+
+        return new WebResourceResponse(
+                mimeType,
+                "UTF-8",
+                200,
+                "OK",
+                headers,
+                inputStream
+        );
+    }
+}

build/android/app/src/main/res/layout/activity_main.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="@+id/main_container"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent">
+
+    <WebView
+        android:id="@+id/webview"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent" />
+
+</FrameLayout>