Merge pull request 'DLNA renderers, app updates told like Librarian, acquisition without Lidarr, Collection and admin rework (M502–M505, M542)' (#156 ) from dev into main

docs: two comments state the rule rather than its history (#6277 )
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 12:32:32 -04:00 · 2026-10-26 11:20:17 -04:00 · 2026-10-26 10:08:02 -04:00 · 2026-10-26 07:46:01 -04:00 · 2026-10-26 07:46:01 -04:00 · 2026-10-26 07:38:29 -04:00
1400 changed files with 96830 additions and 24185 deletions
@@ -6,9 +6,16 @@
 **/build
 web/build
-# Flutter mobile client — built separately on developer machines / Flutter CI.
+# The Android client — built by its own job, never from this context. The APK
-# Including it in the Go build context wastes ~70 files and invalidates the
+# reaches the image through client/, downloaded as a CI artifact, so nothing
-# `COPY . .` layer cache on every Flutter-only change.
+# here reads android/ sources.
 # Excluded so the Gradle project neither bloats the context nor busts the
 # `COPY . .` layer on every Android-only change.
 android/
 # Local `make build` output — an 18 MB binary the image never uses, since the
 # builder stage compiles its own.
 bin/
 # Docs and IDE noise
 docs/
@@ -26,5 +33,8 @@ docs/
 !.env.example
 # CI workflow files don't need to ship in the image.
-.forgejo/
+#
-.github/
+# This said `.forgejo/` and `.github/` — neither of which this repo has. Gitea
 # Actions reads `.gitea/`, so the one directory that actually exists was the
 # one not excluded, and every workflow edit invalidated the context.
 .gitea/
@@ -1,12 +1,11 @@
-# Minstrel environment variable overrides.
+# Environment for running the server outside Docker (`go run ./cmd/minstrel`).
-# Copy to .env for docker compose, or export before `go run ./cmd/minstrel`.
+# The values match the Postgres in docker-compose.yml.
 # Values shown are sensible defaults for the local docker-compose postgres.
-SMARTMUSIC_SERVER_ADDRESS=:4533
+MINSTREL_SERVER_ADDRESS=:4533
-SMARTMUSIC_DATABASE_URL=postgres://minstrel:minstrel@localhost:5432/minstrel?sslmode=disable
+MINSTREL_DATABASE_URL=postgres://minstrel:minstrel@localhost:5432/minstrel?sslmode=disable
-SMARTMUSIC_LOG_LEVEL=info
+MINSTREL_LOG_LEVEL=info
-SMARTMUSIC_LOG_FORMAT=text
+MINSTREL_LOG_FORMAT=text
-# Set this when running `go test ./...` without -short to exercise the
+# Runs the database tests in `go test ./...` (without -short). Use a separate
-# migration test against a running postgres.
+# database: the tests truncate every table.
-# MINSTREL_TEST_DATABASE_URL=postgres://minstrel:minstrel@localhost:5432/minstrel?sslmode=disable
+# MINSTREL_TEST_DATABASE_URL=postgres://minstrel:minstrel@localhost:5432/minstrel_test?sslmode=disable
@@ -1,95 +0,0 @@
 name: android
 # Native Android (Kotlin/Compose/Media3) — M8 rewrite, now the only client.
 # This workflow is testing only — lint + detekt + unit tests on every push
 # to dev/main, plus a debug APK artifact for main. The signed-release
 # build + asset attach + image-bundling lives in release.yml under a
 # `needs:` chain so the docker image cannot ship without the APK.
 on:
  push:
    branches: [main, dev]
    paths:
      - 'android/**'
      - '.gitea/workflows/android.yml'
 # pull_request trigger intentionally omitted — see test-web.yml for
 # the rationale (single-author repo, push covers PR-merge equivalent).
 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
 env:
  # Silences the JDK 22+ "restricted method in java.lang.System has been
  # called" warning that Gradle 9.1's bundled native-platform jar trips
  # at launch (System.load for native primitives). Affects the LAUNCHER
  # JVM, not the daemon — that's why org.gradle.jvmargs in
  # gradle.properties isn't enough. Future-compat: required opt-in once
  # JDK 25 promotes the warning to an error.
  JAVA_TOOL_OPTIONS: "--enable-native-access=ALL-UNNAMED"
 jobs:
  build:
    name: Build + lint + test
    # Using flutter-ci runner label because it's the only proven-working
    # label with docker that can pull our container.image. Switch to
    # android-ci once the operator registers that runner label.
    runs-on: flutter-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-android:36
    defaults:
      run:
        working-directory: android
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Cache Gradle dirs
        # Resolved deps + Gradle distribution + Kotlin daemon caches.
        # Saves ~3 min per CI run after the first warm-up.
        uses: actions/cache@v4
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
            ~/.kotlin
          key: gradle-${{ runner.os }}-${{ hashFiles('android/gradle/wrapper/gradle-wrapper.properties', 'android/gradle/libs.versions.toml', 'android/**/*.gradle.kts') }}
          restore-keys: |
            gradle-${{ runner.os }}-
      - name: Make gradlew executable
        run: chmod +x ./gradlew
      - name: Gradle wrapper validation
        run: ./gradlew --version
      - name: ktlint
        run: ./gradlew ktlintCheck
      - name: detekt
        run: ./gradlew detekt
      - name: Unit tests
        run: ./gradlew testDebugUnitTest
      - name: Assemble debug
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: ./gradlew assembleDebug
      - name: Upload debug APK
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        # Mirrored action, never actions/upload-artifact. @v4+ throws
        # GHESNotSupportedError client-side on the hostname (no server setting
        # reaches that check), and @v3 is worse — it reports success while Gitea
        # serves artifacts back only through the v4 API, so the upload is stored
        # and invisible to every retrieval path. @v3 is what left 72 unreachable
        # artifacts on this repo. Pinned by SHA because the mirror auto-syncs;
        # full URL because DEFAULT_ACTIONS_URL sends bare owner/repo to github.com.
        # See Scribe issues 2255 / 2270.
        uses: https://git.fabledsword.com/bvandeusen/upload-artifact@cb8afe72b42edc798abfb8fcb556cf660d894245
        with:
          name: minstrel-android-debug-${{ github.sha }}
          path: android/app/build/outputs/apk/debug/app-debug.apk
          if-no-files-found: error
@@ -2,55 +2,409 @@ name: release
 # Builds and pushes the minstrel container image to the Gitea registry.
 #
-#   push to main             → :main and :latest (latest-release APK bundled)
+#   push to dev                  → :dev            (freshly-built dev APK bundled)
-#   push tag vYYYY.MM.DD     → :vYYYY.MM.DD and :latest (freshly-built APK bundled)
+#   push to main                 → :latest + :<sha> (latest-release APK bundled)
-#   workflow_dispatch        → manual trigger (same rules based on the ref)
+#   push tag vYYYY.MM.DD.HHMM    → :latest          (fresh APK bundled)
 #   workflow_dispatch            → manual trigger (same rules based on the ref)
 #
-# Release model: per-day CalVer tags (no trailing patch digit). The day's
+# That is the whole tag map.
-# tag is intentionally mutable — if a second release happens the same day,
+#
-# move the tag with `git push -f origin vYYYY.MM.DD` and the image tag of
+# :<sha> on main is the ROLLBACK UNIT — every production commit addressable
-# the same name gets overwritten. :latest is updated by every main push
+# without a release ceremony. It is minted only on main, where rollback is
-# AND every tag push, so it always reflects the newest blessed image.
+# actually worth having: merges to main are deliberate, so they number in the
 # dozens per year, while on dev they would be one per push, forever, for a
 # channel whose entire contract is that it moves.
 #
 # There are NO :<version> image tags. Git and the build's own self-reported
 # version answer "which build is this"; a third name for the same thing is
 # upkeep for a model we do not run. Only the APK needs version numbers, for
 # its update process.
 #
 # There is no :main either. :latest tracks main's tip with no gate between
 # them, so a second name for the same image sends readers looking for a
 # distinction that does not exist.
 #
 # The dev channel exists so testing a build does not require shipping one:
 # without it the only way to get an APK onto a phone is to cut a release,
 # which makes `main` the staging area. `:dev` carries its own freshly-built
 # APK, signed with the SAME key as release builds — a different key cannot
 # install over the stable app, so anyone crossing channels would have to
 # uninstall and lose their data.
 #
 # :dev is published ALONE, with no per-commit tag. A rolling channel is
 # rolling by definition; a commit-addressable image for it would be a
 # rollback target nobody ever pulls, kept forever. Recovery on dev is to fix
 # forward.
 #
 # No cross-repo dispatch is needed to refresh a channel when its bundled APK
 # is rebuilt: Minstrel is a monorepo, so one push builds the APK and the
 # image in the same run from the same commit, and the channel cannot go
 # stale against its own artifact.
 #
 # Release model: the tag IS the artifact's version name with a `v` in front.
 # `v2026.09.10.1432` and `2026.09.10.1432` are the same string, derived from
 # the tagged commit's UTC timestamp — so there is no mismatch to reconcile
 # between what the tag says and what the APK reports, and nothing to look up
 # when minting one.
 #
 # TAGS ARE IMMUTABLE. Never move, retarget or delete a published tag. A
 # same-day second release is not a collision — HHMM makes every tag unique
 # by construction, so the answer is simply another tag. Anyone installing
 # from a moved tag would hold something the tag no longer points at, which
 # is a worse failure than an extra row in the tag list.
 #
 # :latest is updated by every main push AND every tag push, so it always
 # reflects the newest blessed image.
 #
 # APK pipeline: on tag pushes the android-release job builds + signs the
 # Android APK and uploads it as a workflow artifact. The image-release
 # job declares `needs: android-release`, so the docker image cannot
 # start building until the APK is guaranteed-ready — no polling, no
-# race, no silent-failure mode. Asset attachment to the gitea Release
+# race, no silent-failure mode. Attaching the APK to the gitea Release is
-# happens in the same android-release job, so the Release-page download
+# its own job (release-assets), behind the test gate below.
 # link and the in-image bundled APK are both populated atomically.
 #
 # :latest always carries an APK. Because every main push also moves
 # :latest (not just tags), a main build with no APK would silently strip
 # the in-app update channel off :latest until the next release. So on
 # non-tag builds image-release pulls the MOST RECENT release's signed APK
-# and reconstructs its exact versionName (tag + commit-count, the same
+# AND the version sidecar published beside it — the recorded values, not
-# formula android-release bakes in) for the version sidecar — no rebuild,
+# recomputed ones — so no rebuild is needed, just a rebundle. Tag builds
-# just rebundle. Tag builds keep bundling their own freshly-built APK.
+# keep bundling their own freshly-built APK.
 #
-# Android testing (lint + detekt + unit tests, debug APK upload on main)
+# THE GATE. Every verifying lane lives in this file —
-# lives in android.yml and runs independently on every push.
+# Go (vet, lint, short tests), the Postgres integration suite, the web app
 # (npm audit, svelte-check, vitest), Android (ktlint, detekt, unit tests) and
 # govulncheck — and every job that publishes something names each of them in
 # `needs:` and requires `success` from each, by name. Nothing publishes on red.
 #
 # One workflow, because separate workflows cannot see each other's verdict:
 # :dev would mean "it built", never "it passed", and a red test run and a
 # fresh :dev could carry the same timestamp. One graph is the only place the
 # edge can be written.
 #
 # A skipped lane is NOT a pass. The publishing conditions check
 # `result == 'success'` per lane rather than `!failure()`, so a lane that
 # never started blocks the publish exactly as a red one does. Lanes carry no
 # path filters for the same reason: a web-only push still runs the Go suite,
 # because "not run" must never read as "passed".
 #
 # What publishes, and is therefore gated: the image tags (image-release) and
 # the APK + version sidecar attached to a tag's Release (release-assets).
 # android-release only BUILDS the signed APK into a workflow artifact, which
 # nobody outside this run can pull, so it runs in parallel with the lanes
 # instead of after them; attaching it to the Release is the publishing half,
 # and that half waits for the gate.
 #
 # To watch the gate refuse: dispatch this workflow with force_red=true. The go
 # lane fails on purpose, and both publishing jobs must report skipped.
 on:
  push:
-    branches: [main]
+    branches: [main, dev]
    tags: ['v*']
    paths-ignore:
      - 'docs/**'
      - '**/*.md'
  workflow_dispatch:
    inputs:
      force_red:
        description: Fail the go lane on purpose, to check that nothing publishes on red
        type: boolean
        default: false
-# Force-moving the per-day tag (or rapidly re-pushing to main) should
+# A rapid re-push to main supersedes the in-flight build: the later commit
-# supersede the in-flight build — the operator explicitly wants the
+# wins. Tags are immutable and unique, so no tag build can be superseded by
-# later commit to win.
+# another run on the same ref.
 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  # ---------------------------------------------------------------- lanes --
  # Verifying jobs. Each one is named in the `needs:` of every publishing job
  # below; add a lane here and it must be added there in the same commit.
  go:
    runs-on: go-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-go:1.26
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Forced failure (gate check)
        if: github.event.inputs.force_red == 'true'
        run: |
          echo "::error::force_red dispatch: failing on purpose so the publishing jobs must skip"
          exit 1
      - name: Toolchain versions
        run: |
          go version
          golangci-lint --version
      - name: Generated code matches queries (sqlc)
        run: make verify-generate
      - name: go vet
        run: go vet ./...
      - name: golangci-lint
        run: golangci-lint run ./...
      - name: go test (short, race)
        run: go test -short -race ./...
  # Full `go test -race` against an ephemeral Postgres.
  #
  # DB wiring follows the act_runner shared-daemon pattern: the runner's Docker
  # daemon also runs a dev compose stack, so service containers get NO
  # published ports (collision) and no service-name DNS. We discover the
  # service container through the mounted docker socket and reach it by bridge
  # IP. The exactly-one assertion is a hard guard — pointing tests at the dev
  # Postgres would truncate it.
  #
  # The key stays `integration` with no `name:`: act_runner derives the
  # service container's name from the job's display name.
  #
  # `web/build/` has a committed placeholder index.html so go:embed succeeds
  # without the SPA being built first.
  integration:
    runs-on: go-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-go:1.26
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_USER: minstrel
          POSTGRES_PASSWORD: minstrel
          POSTGRES_DB: minstrel_test
        # No `ports:` — the runner shares the dev compose
        # Docker daemon; publishing a fixed host port collides.
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Integration suite (discover service by bridge IP, migrate, test)
        run: |
          set -eux
          # Discover THIS job's Postgres service container via the
          # mounted docker socket. act_runner attaches the job
          # container and its service container(s) to a shared per-job
          # network, so scope discovery to a postgres that sits on a
          # network THIS job container is also on. A name filter alone
          # would match EVERY concurrent integration run's postgres (a dev
          # push and a main-merge run overlapping give 2 candidates and a
          # false "expected exactly 1" abort). The dev compose
          # `minstrel-postgres-*` is never on this job's network; skip it
          # explicitly as belt-and-suspenders (a wrong target would
          # truncate real data).
          SELF=$(cat /etc/hostname)
          SELF_NETS=$(docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' "$SELF")
          test -n "$SELF_NETS"
          echo "self ($SELF) networks: $SELF_NETS"
          PG_ID=""
          PG_NAME=""
          for cid in $(docker ps --filter "ancestor=postgres:16-alpine" -q); do
            nm=$(docker inspect -f '{{.Name}}' "$cid" | sed 's#^/##')
            case "$nm" in *minstrel-postgres*|*_postgres_*) continue ;; esac
            for net in $(docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' "$cid"); do
              case " $SELF_NETS " in *" $net "*) PG_ID="$cid"; PG_NAME="$nm"; break 2 ;; esac
            done
          done
          test -n "$PG_ID" || { echo "FATAL: no postgres service container on this job's network (self nets: $SELF_NETS)"; exit 1; }
          echo "selected postgres: $PG_ID $PG_NAME"
          PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG_ID")
          test -n "$PG_IP"
          export MINSTREL_TEST_DATABASE_URL="postgres://minstrel:minstrel@${PG_IP}:5432/minstrel_test?sslmode=disable"
          # Wait for Postgres to accept connections. Asked of the service
          # container itself: the run: shell is dash, where a `/dev/tcp`
          # probe never connects and the loop would silently burn its full
          # two minutes.
          #
          # Over TCP (-h 127.0.0.1), not the unix socket. On first
          # boot the image's entrypoint runs initdb under a temporary server
          # that listens on the socket only, then stops it and starts the
          # real one. A socket probe can catch the temporary server, and the
          # next step then meets "the database system is shutting down".
          # Only the real server listens on TCP.
          ready=""
          for i in $(seq 1 60); do
            if docker exec "$PG_ID" pg_isready -h 127.0.0.1 -U minstrel -d minstrel_test -q; then ready=1; break; fi
            sleep 2
          done
          test -n "$ready" || { echo "FATAL: postgres never became ready"; exit 1; }
          # Relax durability on the throwaway CI Postgres. Our test pattern
          # is dbtest.ResetDB → TRUNCATE … RESTART IDENTITY CASCADE before
          # every test, and the per-TRUNCATE commit fsync is the dominant
          # cost of the integration suite. The CI DB is rebuilt every run so
          # fsync / full_page_writes / synchronous_commit buy nothing. Apply
          # via docker exec because:
          #  - The act_runner `services:` block can't override the container
          #    command, so `postgres -c fsync=off` at boot isn't an option.
          #  - ALTER SYSTEM cannot run inside a transaction; psql -c
          #    auto-commits each statement, which is what we need.
          #  - fsync / full_page_writes are sighup GUCs and
          #    synchronous_commit is user-context, so pg_reload_conf() picks
          #    all three up with no restart.
          # Non-fatal: a failure degrades to "slower", never red CI. But
          # slower is ~15x on internal/api, so retry a few times and
          # print what took effect.
          relaxed=""
          for i in 1 2 3 4 5; do
            if docker exec -e PGPASSWORD=minstrel "$PG_ID" psql -h 127.0.0.1 -U minstrel -d minstrel_test \
                 -c "ALTER SYSTEM SET fsync = off" \
                 -c "ALTER SYSTEM SET synchronous_commit = off" \
                 -c "ALTER SYSTEM SET full_page_writes = off" \
                 -c "SELECT pg_reload_conf()"; then relaxed=1; break; fi
            sleep 2
          done
          if [ -n "$relaxed" ]; then
            docker exec -e PGPASSWORD=minstrel "$PG_ID" psql -h 127.0.0.1 -U minstrel -d minstrel_test -At \
              -c "SELECT 'durability: ' || string_agg(name || '=' || setting, ' ' ORDER BY name) FROM pg_settings WHERE name IN ('fsync','synchronous_commit','full_page_writes')" \
              || true
          else
            echo "::warning::durability relax failed after 5 tries; the suite will run several times slower"
          fi
          # Apply embedded migrations to the fresh test DB, then run the
          # full suite (no -short → integration tests execute). -p 1:
          # every integration package TRUNCATEs the one shared test DB;
          # concurrent package binaries → TRUNCATE deadlocks. Serialize
          # package execution (the documented local invocation too).
          # -timeout 20m: internal/api alone takes several minutes under
          # -race on an idle runner, and a dev and a main run sharing the
          # runner can push it past go test's default 10m with nothing
          # hung.
          MINSTREL_DATABASE_URL="$MINSTREL_TEST_DATABASE_URL" go run ./cmd/minstrel migrate
          go test -p 1 -race -timeout 20m ./...
  web:
    runs-on: go-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-go:1.26
    defaults:
      run:
        working-directory: web
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install deps
        run: npm ci
      # The whole tree, build and test tooling included: the tooling that
      # builds the shipped bundle is held to the same bar as the bundle.
      - name: npm audit (all dependencies)
        run: npm audit --audit-level=moderate
      - name: Type-check + svelte-check
        run: npm run check
      - name: Vitest
        run: npm test
  android:
    # The flutter-ci runner label is the only proven-working label with
    # docker that can pull our container.image.
    runs-on: flutter-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-android:36
    defaults:
      run:
        working-directory: android
    env:
      # Silences the JDK 22+ "restricted method in java.lang.System has been
      # called" warning that Gradle's bundled native-platform jar trips at
      # launch. Affects the LAUNCHER JVM, not the daemon — that's why
      # org.gradle.jvmargs in gradle.properties isn't enough.
      JAVA_TOOL_OPTIONS: "--enable-native-access=ALL-UNNAMED"
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Cache Gradle dirs
        uses: actions/cache@v4
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
            ~/.kotlin
          key: gradle-${{ runner.os }}-${{ hashFiles('android/gradle/wrapper/gradle-wrapper.properties', 'android/gradle/libs.versions.toml', 'android/**/*.gradle.kts') }}
          restore-keys: |
            gradle-${{ runner.os }}-
      - name: Make gradlew executable
        run: chmod +x ./gradlew
      - name: Gradle wrapper validation
        run: ./gradlew --version
      - name: ktlint
        run: ./gradlew ktlintCheck
      - name: detekt
        run: ./gradlew detekt
      - name: Unit tests
        run: ./gradlew testDebugUnitTest
      # No debug APK is built or uploaded here: a debug build is signed by a
      # key regenerated in every container, which no install can update.
      # Phones get builds from android-release, signed with the one release
      # key, on dev and on tags.
  # Known vulnerabilities in the Go code and the standard library it is built
  # with. Runs in the SAME image the Dockerfile's builder stage uses, so the
  # standard library it checks is the one that ends up in the shipped binary;
  # the ci-go image carries its own Go and would be checking a different
  # toolchain. Keep this image and the Dockerfile's builder in step.
  #
  # govulncheck is fetched at CI time, unpinned: the vulnerability
  # database and the tool that reads it should both be current.
  govulncheck:
    runs-on: go-ci
    container:
      image: golang:1.26-bookworm
    steps:
      # Plain git, not actions/checkout: that action runs on node, which the
      # golang image does not carry. This step is dash.
      - name: Checkout
        env:
          TOKEN: ${{ github.token }}
        run: |
          set -eu
          auth=$(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)
          git init -q .
          git remote add origin "${{ github.server_url }}/${{ github.repository }}.git"
          git -c http.extraHeader="Authorization: Basic ${auth}" fetch -q --depth 1 origin "${{ github.sha }}"
          git checkout -q FETCH_HEAD
          git log -1 --format='%H %s'
      - name: govulncheck
        run: |
          go version
          go run golang.org/x/vuln/cmd/govulncheck@latest ./...
  # ------------------------------------------------------------ artifacts --
  android-release:
-    name: Build signed APK (tag releases only)
+    name: Build signed APK (releases and dev)
-    if: startsWith(github.ref, 'refs/tags/v')
+    # Also builds on `dev`, which is what makes a test channel possible at
    # all: without it the only way to get a build onto a phone is to cut a
    # release, which quietly turns `main` into the staging area.
    if: startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/dev'
    runs-on: flutter-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-android:36
@@ -75,14 +429,18 @@ jobs:
    outputs:
      version_name: ${{ steps.ver.outputs.name }}
      version_code: ${{ steps.ver.outputs.code }}
      channel: ${{ steps.ver.outputs.channel }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
-          # fetch-depth: 0 retrieves full history; default shallow clone
+          # Full history. The version name reads only the tip commit's
-          # would return 1 for `git rev-list --count HEAD`, breaking the
+          # timestamp, so a shallow clone would technically serve — but this
-          # iteration suffix.
+          # job derives a value that ships to devices, and a shallow checkout
          # changes what git-derived values resolve to WITHOUT failing. The
          # whole failure class here is a green build carrying a wrong
          # version, so the cheap guarantee is worth keeping.
          fetch-depth: 0
      - name: Compute release version
@@ -91,23 +449,35 @@ jobs:
        working-directory: ${{ github.workspace }}
        run: |
          set -euo pipefail
-          TAG="${GITHUB_REF#refs/tags/v}"
+          # The derivation lives in ci/version.sh, not here, so it can be
-          COMMIT_COUNT=$(git rev-list --count HEAD)
+          # executed by a test on every push. Anything inline in this file is
-          VERSION_NAME="${TAG}.${COMMIT_COUNT}"
+          # unverifiable until a release is already running.
-          echo "name=${VERSION_NAME}" >> "$GITHUB_OUTPUT"
+          out="$(ci/version.sh --apk HEAD)"
-          echo "code=${COMMIT_COUNT}" >> "$GITHUB_OUTPUT"
+          printf '%s\n' "${out}" >> "$GITHUB_OUTPUT"
-          echo "::notice::APK version: ${VERSION_NAME} (code=${COMMIT_COUNT})"
+
          # The channel is a property of the LANE, not of the commit, which is
          # why it is derived here rather than in version.sh. Same commit built
          # on dev and on main reports the same NAME and differs only here —
          # that is the whole point of separating the two values.
          if [ "${GITHUB_REF}" = "refs/heads/dev" ]; then
            channel=dev
          else
            channel=stable
          fi
          echo "channel=${channel}" >> "$GITHUB_OUTPUT"
          echo "::notice::APK $(printf '%s' "${out}" | tr '\n' ' ') channel=${channel}"
      # Checked BEFORE the expensive work, not after it. "Attach APK to gitea
      # Release" below resolves the release by tag and fails if it is absent —
-      # but that is the final step, so a tag pushed without a release built an
+      # but that is the final step, so a tag pushed without a release would
-      # APK for several minutes first and only then discovered it had nowhere to
+      # build an APK for several minutes first and only then find it has
-      # put it. Same check, seconds in instead of minutes.
+      # nowhere to put it. Same check, seconds in instead of minutes.
      #
      # Releases are normally created through the API (which creates the tag and
      # the release together, so this passes). A bare `git push origin vX` is the
      # case this catches.
      - name: Release must exist for this tag
        if: startsWith(github.ref, 'refs/tags/v')
        shell: bash
        working-directory: ${{ github.workspace }}
        env:
@@ -155,14 +525,47 @@ jobs:
            -PMINSTREL_VERSION_NAME=${{ steps.ver.outputs.name }} \
            -PMINSTREL_VERSION_CODE=${{ steps.ver.outputs.code }}
      # The APK every phone updates from must carry THE release key: Android
      # updates an app in place only when the signer matches, so an APK
      # signed by any other key (debug, a regenerated keystore, a swapped
      # secret) reaches no installed phone. The certificate's digest is
      # pinned below; it is public, not a secret. Gradle signs with the
      # release key or leaves the APK unsigned, and an unsigned build fails
      # here too, as there is no app-release.apk to verify. apksigner, not
      # keytool: keytool prints nothing for a v2-only APK.
      #
      # Rotating the key on purpose means every install must be removed and
      # reinstalled; change the digest here in the same commit.
      - name: The APK carries the release key
        shell: bash
        env:
          # CN=Minstrel, O=FabledSword.
          RELEASE_CERT_SHA256: 43d183307bc46b821789d90444a960b137f78f2166ff431efb2406d0fceaf612
        run: |
          set -euo pipefail
          sdk="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-}}"
          signer="$(ls "$sdk"/build-tools/*/apksigner 2>/dev/null | sort -V | tail -1 || true)"
          test -n "$signer" || { echo "::error::no apksigner under '$sdk/build-tools'"; exit 1; }
          certs="$("$signer" verify --print-certs app/build/outputs/apk/release/app-release.apk)"
          printf '%s\n' "$certs" | grep -E '^Signer #[0-9]+ certificate (DN|SHA-256 digest)'
          # One signer, and it is ours. A second signer would be a lineage or
          # a mistake; either way not something to ship unexamined.
          digests="$(printf '%s\n' "$certs" | sed -n 's/^Signer #[0-9]* certificate SHA-256 digest: //p')"
          if [ "$digests" != "$RELEASE_CERT_SHA256" ]; then
            if printf '%s' "$certs" | grep -q 'CN=Android Debug'; then
              echo "::error::the release APK is signed with a debug key"
            else
              echo "::error::the release APK is not signed by the release key: got '${digests//$'\n'/ }', want ${RELEASE_CERT_SHA256}"
            fi
            exit 1
          fi
      - name: Upload APK as workflow artifact
-        # Mirrored action, never actions/upload-artifact — @v4+ refuses on the
+        # Stock action — never @v3, which uploads something Gitea will never
-        # hostname, @v3 uploads something Gitea will never serve back. This is
+        # serve back. This is the producing half of a pair: image-release
-        # the producing half of a pair: image-release downloads `minstrel-apk`
+        # downloads `minstrel-apk` below. Any upload v4+ pairs with any
-        # below with the matching download-artifact mirror. Both must stay on
+        # download v4+ on this forge, so the two pins need not move together.
-        # the v4 protocol — mixing a v3 upload with a v4 download (or the
+        uses: actions/upload-artifact@v7
        # reverse) yields an empty listing, not an error. See Scribe 2255 / 2270.
        uses: https://git.fabledsword.com/bvandeusen/upload-artifact@cb8afe72b42edc798abfb8fcb556cf660d894245
        with:
          name: minstrel-apk
          path: android/app/build/outputs/apk/release/app-release.apk
@@ -170,17 +573,63 @@ jobs:
          # artifact existing, so an empty upload must fail here, not there.
          if-no-files-found: error
  # Publishes the signed APK and its version sidecar on the tag's Release.
  # Split out of android-release so the APK can be BUILT in parallel with the
  # lanes while being PUBLISHED only once they have all passed.
  release-assets:
    name: Attach APK to the Release (tag releases only)
    needs: [go, integration, web, android, govulncheck, android-release]
    if: >-
      ${{
      !cancelled()
      && needs.go.result == 'success'
      && needs.integration.result == 'success'
      && needs.web.result == 'success'
      && needs.android.result == 'success'
      && needs.govulncheck.result == 'success'
      && needs.android-release.result == 'success'
      && startsWith(github.ref, 'refs/tags/v') }}
    runs-on: go-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-go:1.26
    steps:
      - name: Download signed APK artifact
        uses: actions/download-artifact@v8
        with:
          name: minstrel-apk
          path: release-apk/
      - name: Attach APK to gitea Release
        # Tag releases only. A dev build has no Release to hang assets on and
        # does not need one — the :dev image bundles the APK, and the server
        # serves it from /api/client/apk like any other.
        shell: bash
        env:
          CI_TOKEN: ${{ secrets.CI_TOKEN }}
          VERSION_NAME: ${{ needs.android-release.outputs.version_name }}
          VERSION_CODE: ${{ needs.android-release.outputs.version_code }}
        run: |
          set -euxo pipefail
          TAG="${GITHUB_REF#refs/tags/}"
          REPO="${GITHUB_REPOSITORY}"
-          APK_PATH="app/build/outputs/apk/release/app-release.apk"
+          APK_PATH="release-apk/app-release.apk"
          ls -lh "${APK_PATH}"
          # Publish the version sidecar as a release asset next to the APK.
          #
          # This is what lets a later :latest build stop RECONSTRUCTING the
          # bundled APK's version and simply read what was recorded. The
          # ordering key in particular cannot be re-derived after the fact —
          # it is build-time minutes, so once this job ends the value exists
          # nowhere else. Reconstruction could only ever recover the name,
          # and only by duplicating a formula that then has to be kept in
          # step across two files.
          SIDECAR_PATH="/tmp/minstrel.apk.version"
          printf '{"name":"%s","code":%s,"channel":"stable"}\n' \
            "${VERSION_NAME}" "${VERSION_CODE}" > "${SIDECAR_PATH}"
          cat "${SIDECAR_PATH}"
          RELEASE_JSON="$(curl -fsSL \
            -H "Authorization: token ${CI_TOKEN}" \
            "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/tags/${TAG}")"
@@ -202,15 +651,37 @@ jobs:
            exit 1
          fi
          # Same treatment for the sidecar. Named `.apk.version` so the
          # downloader's `\.apk$` match cannot pick it up by mistake.
          SIDECAR_HTTP=$(curl -sS -L -o /tmp/upload-sidecar.out -w '%{http_code}' \
            -H "Authorization: token ${CI_TOKEN}" \
            -F "attachment=@${SIDECAR_PATH}" \
            "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets?name=minstrel-${TAG}.apk.version")
          echo "sidecar_upload_http=${SIDECAR_HTTP}"
          cat /tmp/upload-sidecar.out || true
          echo
          if [ "${SIDECAR_HTTP}" -lt 200 ] || [ "${SIDECAR_HTTP}" -ge 300 ]; then
            echo "::error::version sidecar upload returned HTTP ${SIDECAR_HTTP}"
            exit 1
          fi
  image-release:
    name: Build + push container image
-    # `needs:` waits for android-release. For tag pushes android-release
+    # Every lane must have SUCCEEDED, each named here. Then the
-    # runs and must succeed before this job starts — guaranteeing the
+    # APK: tag and dev pushes build one and it must have succeeded; main
-    # APK artifact is present. For main pushes android-release is
+    # pushes skip android-release and bundle the latest release's APK
-    # skipped; the `if: ...` below lets this job run anyway and the
+    # instead, so for main alone a skipped android-release is expected.
-    # download/copy steps gate themselves on the tag context.
+    needs: [go, integration, web, android, govulncheck, android-release]
-    needs: [android-release]
+    if: >-
-    if: ${{ !failure() && !cancelled() }}
+      ${{
      !cancelled()
      && needs.go.result == 'success'
      && needs.integration.result == 'success'
      && needs.web.result == 'success'
      && needs.android.result == 'success'
      && needs.govulncheck.result == 'success'
      && (needs.android-release.result == 'success'
      || (needs.android-release.result == 'skipped' && github.ref == 'refs/heads/main')) }}
    runs-on: go-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-go:1.26
@@ -222,11 +693,14 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v4
        with:
-          # Full history + tags so non-tag :latest builds can resolve the
+          # Full history: any job that DERIVES the version name needs it,
-          # latest release tag's commit count and reconstruct the bundled
+          # because a shallow clone changes what git-derived values resolve to
-          # APK's exact versionName (see "Bundle latest release APK" below).
+          # WITHOUT failing — a too-low value, silently, with every lane green.
          #
          # This job runs ci/version.sh itself: with no :<version> image tags,
          # the server's self-reported version is the only thing that says which
          # build an image is.
          fetch-depth: 0
          fetch-tags: true
      - name: Detect buildable project
        id: guard
@@ -244,21 +718,62 @@ jobs:
        if: steps.guard.outputs.ready == 'true'
        shell: bash
        run: |
-          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
+          set -euo pipefail
-            VERSION="${GITHUB_REF#refs/tags/}"
+
-            echo "args=-t ${IMAGE}:${VERSION} -t ${IMAGE}:latest" >> "$GITHUB_OUTPUT"
+          # THE VERSION, and it is derived the same way on every ref — the
-            echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          # branch decides the CHANNEL, never the version.
-            echo "::notice::Release build: ${VERSION} + latest"
+          #
-          else
+          # A per-ref string ("main", "dev", the tag name) would not order, and
-            # Main is the protected, post-PR-merge branch. Treat it as the
+          # "dev" would be the same string forever — two dev images eight weeks
-            # rolling stable channel — every main push moves :latest.
+          # apart indistinguishable in the UI. With no version image tags, this
-            # Pinned consumers can target :vYYYY.MM.DD; everyone else
+          # is how an admin tells which build a container is running.
-            # gets the newest main.
+          #
-            echo "args=-t ${IMAGE}:main -t ${IMAGE}:latest" >> "$GITHUB_OUTPUT"
+          # `sed -n s///p` rather than `grep`: it exits 0 when nothing matches,
-            echo "version=main" >> "$GITHUB_OUTPUT"
+          # so the empty check below is actually reachable. A grep here would
-            echo "::notice::Main-branch build: :main + :latest"
+          # kill the step at the assignment under the runner's pipefail.
          VERSION="$(ci/version.sh HEAD | sed -n 's/^name=//p')"
          if [ -z "${VERSION}" ]; then
            echo "::error::could not derive a build version from ci/version.sh"
            exit 1
          fi
          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
            # A release refreshes the CHANNEL and mints nothing else.
            #
            # The tag build exists to produce the signed APK and attach it to
            # the release; the image it rebuilds is the SAME SOURCE as the main
            # build minutes earlier, differing only in which APK is baked in.
            # When the same source is rebuilt with different contents,
            # publish the moving channel tag and never a commit-addressable
            # one.
            #
            # :latest must move here rather than waiting for the next main
            # push, or the channel would carry the PREVIOUS release's APK
            # indefinitely — a channel that cannot refresh itself.
            CHANNEL=stable
            echo "args=-t ${IMAGE}:latest" >> "$GITHUB_OUTPUT"
            echo "::notice::Release build ${VERSION}: refreshing :latest around the new APK"
          elif [[ "${GITHUB_REF}" == "refs/heads/dev" ]]; then
            # The rolling test channel, and :dev ALONE — deliberately no
            # per-commit tag. A rolling channel is rolling by definition, so a
            # commit-addressable image here would be a rollback target nobody
            # has ever pulled, accumulating in the registry forever. Recovery
            # on dev is to fix forward.
            CHANNEL=dev
            echo "args=-t ${IMAGE}:dev" >> "$GITHUB_OUTPUT"
            echo "::notice::Dev-branch build ${VERSION}: :dev"
          else
            # The production line: :latest tracks main's tip and :<sha> is
            # the rollback unit. Full 40-char SHA, so a rollback target is
            # addressable straight from the commit anyone is reading.
            CHANNEL=stable
            echo "args=-t ${IMAGE}:latest -t ${IMAGE}:${GITHUB_SHA}" >> "$GITHUB_OUTPUT"
            echo "::notice::Main-branch build ${VERSION}: :latest + :${GITHUB_SHA}"
          fi
          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
          echo "channel=${CHANNEL}" >> "$GITHUB_OUTPUT"
      - name: Registry login
        if: steps.guard.outputs.ready == 'true'
        shell: bash
@@ -267,54 +782,57 @@ jobs:
            | docker login git.fabledsword.com -u "${{ github.actor }}" --password-stdin
      - name: Download signed APK artifact
-        # Tag pushes only — android-release just produced this. Non-tag
+        # Tag and dev pushes — android-release just produced this. Only `main`
-        # builds take the "Bundle latest release APK" path below instead.
+        # takes the "Bundle latest release APK" path below, because it is the
-        if: steps.guard.outputs.ready == 'true' && startsWith(github.ref, 'refs/tags/v')
+        # one ref that moves a channel without building an APK of its own.
-        # Consuming half of the pair — never actions/download-artifact. Same fork,
+        if: >-
-        # same reason: upstream's client-side GHES check rejects this hostname
+          steps.guard.outputs.ready == 'true' &&
-        # before it connects. bvandeusen/download-artifact mirrors
+          (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/dev')
-        # code.forgejo.org/forgejo/download-artifact.
+        # Consuming half of the pair: stock download-artifact, which works here for
-        #
+        # the same reason as the upload (gitea/runner 3.x edits the GHES refusal
-        # SHA below is that fork's `v6` tag. Match on @actions/artifact, NOT on
+        # out of the bundle). v8 runs on node24, which every CI-runner image
-        # the action's own version number — the two actions release on unrelated
+        # carries — the runner uses the image's own node.
-        # cadences, and download v5 would pair a ^2.3.2 client with this file's
+        uses: actions/download-artifact@v8
        # ^4.0.0 uploader. v6 is the tag whose bundled library major (^4.0.0) is
        # the same one proven against this instance by the upload side.
        # Deliberately NOT v7: it moves to node24 and upstream requires runner
        # >= 2.327.1 for it, which act_runner does not claim to satisfy.
        # Pinned, not tagged — the mirror auto-syncs every 8h.
        uses: https://git.fabledsword.com/bvandeusen/download-artifact@8d4e9521a5f7e5f8b6351f341f719f9f45a92a3a
        with:
          name: minstrel-apk
          path: client/
      - name: Stage bundled APK + version sidecar
-        if: steps.guard.outputs.ready == 'true' && startsWith(github.ref, 'refs/tags/v')
+        if: >-
          steps.guard.outputs.ready == 'true' &&
          (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/dev')
        shell: bash
        env:
-          # Pulled from android-release.outputs.version_name so the
+          # All three pulled from android-release's outputs so the sidecar the
-          # sidecar string the server hands clients matches the
+          # server hands clients matches exactly what is baked into the APK
-          # versionName baked into the APK they're comparing against.
+          # they are comparing against.
          APK_VERSION_NAME: ${{ needs.android-release.outputs.version_name }}
          APK_VERSION_CODE: ${{ needs.android-release.outputs.version_code }}
          APK_CHANNEL: ${{ needs.android-release.outputs.channel }}
        run: |
          set -euxo pipefail
          # The artifact lands as `app-release.apk` (the original Gradle
          # output name). The Dockerfile COPYs client/* into /app/client/
          # and the server reads minstrel.apk + minstrel.apk.version.
          mv client/app-release.apk client/minstrel.apk
-          echo "${APK_VERSION_NAME}" > client/minstrel.apk.version
+          printf '{"name":"%s","code":%s,"channel":"%s"}\n' \
            "${APK_VERSION_NAME}" "${APK_VERSION_CODE}" "${APK_CHANNEL}" \
            > client/minstrel.apk.version
          cat client/minstrel.apk.version
          ls -lh client/
      - name: Bundle latest release APK (non-tag :latest builds)
        # Main pushes don't build an APK, but they DO move :latest — so
        # without this the in-app update channel would vanish from :latest
        # until the next tag. Pull the most-recent release's signed APK and
-        # reconstruct its exact versionName (${TAG#v}.$(git rev-list --count
+        # the sidecar published beside it, so what the server reports is what
-        # TAG) — identical to android-release's formula) so the version
+        # that build actually recorded rather than something re-derived here.
        # sidecar the server hands clients matches the installed build.
        # Degrades to an empty client/ (404 update channel) — never a wrong
-        # version — if no release / APK asset / tag-count can be resolved.
+        # version — if no release or APK asset can be resolved. That
-        if: steps.guard.outputs.ready == 'true' && !startsWith(github.ref, 'refs/tags/v')
+        # degradation only actually works because the greps below carry
        # `|| true`; under the runner's default pipefail a non-matching grep
        # kills the step instead of falling through to the empty-case branch.
        if: steps.guard.outputs.ready == 'true' && github.ref == 'refs/heads/main'
        shell: bash
        env:
          CI_TOKEN: ${{ secrets.CI_TOKEN }}
@@ -326,49 +844,73 @@ jobs:
          if [ -z "${REL_JSON}" ]; then
            echo "::notice::no published release — image ships without bundled APK"; exit 0
          fi
-          TAG="$(printf '%s' "${REL_JSON}" | grep -oP '"tag_name":\s*"\K[^"]+' | head -1)"
+          # `|| true` on every one of these, and it is load-bearing rather
-          APK_URL="$(printf '%s' "${REL_JSON}" | grep -oP '"browser_download_url":\s*"\K[^"]+' | grep -E '\.apk$' | head -1)"
+          # than defensive habit. The runner already invokes this shell as
          # `bash -e -o pipefail`, so a pipeline whose grep matches NOTHING
          # exits non-zero even though `head` succeeded — and the step dies at
          # the assignment, before ever reaching the `if` written to handle the
          # empty case. Every "degrades gracefully" branch below is unreachable
          # without this.
          TAG="$(printf '%s' "${REL_JSON}" | grep -oP '"tag_name":\s*"\K[^"]+' | head -1)" || true
          APK_URL="$(printf '%s' "${REL_JSON}" | grep -oP '"browser_download_url":\s*"\K[^"]+' | grep -E '\.apk$' | head -1)" || true
          if [ -z "${TAG}" ] || [ -z "${APK_URL}" ]; then
            echo "::notice::latest release '${TAG:-?}' has no APK asset — image ships without bundled APK"; exit 0
          fi
          COUNT="$(git rev-list --count "${TAG}" 2>/dev/null || true)"
          if [ -z "${COUNT}" ]; then
            echo "::notice::could not resolve commit count for ${TAG} (tag not fetched?) — skipping APK bundle"; exit 0
          fi
          VERSION_NAME="${TAG#v}.${COUNT}"
          curl -fsSL -H "Authorization: token ${CI_TOKEN}" -o client/minstrel.apk "${APK_URL}"
-          echo "${VERSION_NAME}" > client/minstrel.apk.version
+
-          echo "::notice::bundled release APK ${TAG} as version ${VERSION_NAME}"
+          # Take the version the release RECORDED rather than recomputing it.
          # Re-deriving it from the tagged commit would keep the formula in two
          # files that must stay in step, and could only ever recover the name —
          # the ordering key is build-time minutes and exists nowhere after that
          # build ends.
          SIDECAR_URL="$(printf '%s' "${REL_JSON}" | grep -oP '"browser_download_url":\s*"\K[^"]+' | grep -E '\.apk\.version$' | head -1)" || true
          if [ -n "${SIDECAR_URL}" ]; then
            curl -fsSL -H "Authorization: token ${CI_TOKEN}" -o client/minstrel.apk.version "${SIDECAR_URL}"
            cat client/minstrel.apk.version
          else
            # Releases published before sidecars were attached. Their name is
            # still recoverable from the tag, but their ordering key genuinely
            # is not — so it is reported ABSENT rather than guessed. A wrong
            # key is an install the platform refuses; an absent one just tells
            # the client to fall back to comparing names, which is exactly
            # what those builds already do.
            echo "::notice::release ${TAG} predates the version sidecar — bundling with name only, no ordering key"
            printf '{"name":"%s","code":null,"channel":"stable"}\n' "${TAG#v}" > client/minstrel.apk.version
          fi
          echo "::notice::bundled release APK from ${TAG}"
          ls -lh client/
      - name: Build and push
        if: steps.guard.outputs.ready == 'true'
        # --pull: the Dockerfile's base images are floating tags (golang:1.26,
        # debian:bookworm-slim). Without it the runner's daemon reuses
        # whatever it cached, and the shipped binary can sit on a Go patch
        # release govulncheck already flagged while the lane, which pulls
        # fresh, reports clean.
        run: |
-          docker buildx build \
+          docker buildx build --pull \
            --build-arg MINSTREL_VERSION="${{ steps.tags.outputs.version }}" \
            --build-arg MINSTREL_CHANNEL="${{ steps.tags.outputs.channel }}" \
            --push ${{ steps.tags.outputs.args }} .
  # Verifies a tag release actually ended up complete, and names the specific
  # thing that's missing if not.
  #
-  # Added 2026-08-07 after v2026.08.07 was re-cut. The android-release job never
+  # A release can be incomplete while looking fine. If android-release never
-  # started — no log was written at all — so all eight of its steps reported
+  # starts (a runner failing to launch), its steps all report `failure` with
-  # `failure` with none executed and image-release showed `skipped`. The run was
+  # none executed and image-release shows `skipped`. The run is red, but the
-  # red, but the *release page rendered fine*, and `main`'s own push build had
+  # release page renders and main's own push build has already moved
-  # already moved `:latest`, so the code was deployable and nothing looked
+  # `:latest`, so a release missing its APK and its image is easy to skim
-  # obviously wrong. The release was simply missing its APK and its immutable
+  # past.
  # `:vYYYY.MM.DD` image, which is easy to skim past.
  #
-  # This job cannot prevent that (the cause was a runner failing to launch, not
+  # This job cannot prevent that; it turns an incomplete release into an
-  # anything in this file). What it does is turn an incomplete release into an
+  # explicit, named error instead of a row of mystery step failures.
  # explicit, named error instead of eight mystery step failures — so the
  # consequence is legible without having to infer it.
  #
  # `if: always()` is the whole point: it has to report precisely when the jobs
  # above did NOT succeed.
  verify-release:
    name: Verify release artifacts (tag releases only)
-    needs: [android-release, image-release]
+    needs: [android-release, release-assets, image-release]
    if: ${{ always() && startsWith(github.ref, 'refs/tags/v') }}
    runs-on: go-ci
    container:
@@ -404,22 +946,28 @@ jobs:
          echo "::notice::APK attached: ${APK}"
      # The other half. Checking only the APK would report success on a release
-      # whose image push failed — which is precisely the second thing that was
+      # whose image push failed. `always()` on this job means it runs even when
-      # missing when v2026.08.07 had to be re-cut. `always()` on this job means
+      # image-release failed, so without this the guard would cheerfully verify
-      # it runs even when image-release failed, so without this the guard would
+      # an incomplete release.
-      # cheerfully verify an incomplete release.
+      #
-      - name: Immutable image tag must exist
+      # The image checked is the :<sha> rollback target, which main's own build
      # published for this same commit before the tag was cut (there are no
      # version image tags). It catches an image push that silently did not
      # happen, and it proves the ORDERING — a tag cut on a commit whose main
      # build never completed has no rollback target, and that is worth failing
      # on rather than discovering during an incident.
      - name: Rollback image must exist for the tagged commit
        shell: bash
        run: |
          set -euo pipefail
          TAG="${GITHUB_REF#refs/tags/}"
          IMAGE="git.fabledsword.com/bvandeusen/minstrel"
          echo "${{ secrets.CI_TOKEN }}" \
            | docker login git.fabledsword.com -u "${{ github.actor }}" --password-stdin
-          if ! docker manifest inspect "${IMAGE}:${TAG}" > /dev/null 2>&1; then
+          if ! docker manifest inspect "${IMAGE}:${GITHUB_SHA}" > /dev/null 2>&1; then
-            echo "::error::image ${IMAGE}:${TAG} was never pushed — the release tag has no immutable image, so there is nothing to pin or roll back to. Re-run this workflow run."
+            echo "::error::image ${IMAGE}:${GITHUB_SHA} does not exist — this commit has no rollback target."
            echo "::error::That image is published by the MAIN build of this commit, not by the tag build. If main's build never ran or failed, fix that first; a release whose commit cannot be rolled back to is the thing this check exists to refuse."
            exit 1
          fi
-          echo "::notice::image verified: ${IMAGE}:${TAG}"
+          echo "::notice::rollback target verified: ${IMAGE}:${GITHUB_SHA}"
@@ -1,150 +0,0 @@
 name: test-go
 # Go server: vet + golangci-lint + short race tests. Runs on push to
 # dev/main and PRs to main, scoped to Go-side files only — web-only or
 # Flutter-only diffs don't trigger this workflow.
 #
 # Two jobs: `test` (fast — vet + lint + `go test -short -race`, no DB) and
 # `integration` (full `go test -race` against an ephemeral Postgres).
 #
 # Integration-job DB wiring follows the act_runner shared-daemon pattern:
 # the runner's Docker daemon also runs the operator's dev compose stack,
 # so service containers get NO published ports (collision) and no
 # service-name DNS. We discover the service container by the job-scoped
 # name filter via the mounted docker socket and reach it by bridge IP.
 # The exactly-one assertion is a hard guard — pointing tests at the dev
 # Postgres would truncate it (the disaster Fable #339 exists to prevent).
 #
 # `web/build/` has a committed placeholder index.html so go:embed succeeds
 # without needing the SPA to be freshly built. Real builds happen in
 # release.yml (container) and locally during dev.
 on:
  push:
    branches: [dev, main]
    paths:
      - '**/*.go'
      - 'go.mod'
      - 'go.sum'
      - 'sqlc.yaml'
      - 'Makefile'
      - 'internal/**'
      - 'cmd/**'
      - '.golangci.yml'
      - '.gitea/workflows/test-go.yml'
 # pull_request trigger intentionally omitted — see test-web.yml for
 # the rationale (single-author repo, push covers PR-merge equivalent).
 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  test:
    runs-on: go-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-go:1.26
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Toolchain versions
        run: |
          go version
          golangci-lint --version
      - name: Generated code matches queries (sqlc)
        run: make verify-generate
      - name: go vet
        run: go vet ./...
      - name: golangci-lint
        run: golangci-lint run ./...
      - name: go test (short, race)
        run: go test -short -race ./...
  integration:
    runs-on: go-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-go:1.26
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_USER: minstrel
          POSTGRES_PASSWORD: minstrel
          POSTGRES_DB: minstrel_test
        # No `ports:` — the runner shares the operator's dev compose
        # Docker daemon; publishing a fixed host port collides.
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Integration suite (discover service by bridge IP, migrate, test)
        run: |
          set -eux
          # Discover THIS job's Postgres service container via the
          # mounted docker socket. act_runner attaches the job
          # container and its service container(s) to a shared per-job
          # network, so scope discovery to a postgres that sits on a
          # network THIS job container is also on. The old
          # `--filter name=integration` matched EVERY concurrent
          # integration run's postgres (a dev push + the main-merge run
          # overlap → 2 candidates → false "expected exactly 1" abort).
          # The operator's dev compose `minstrel-postgres-*` is never on
          # this job's network; skip it explicitly as belt-and-suspenders
          # (a wrong target would truncate real data).
          SELF=$(cat /etc/hostname)
          SELF_NETS=$(docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' "$SELF")
          test -n "$SELF_NETS"
          echo "self ($SELF) networks: $SELF_NETS"
          PG_ID=""
          PG_NAME=""
          for cid in $(docker ps --filter "ancestor=postgres:16-alpine" -q); do
            nm=$(docker inspect -f '{{.Name}}' "$cid" | sed 's#^/##')
            case "$nm" in *minstrel-postgres*|*_postgres_*) continue ;; esac
            for net in $(docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' "$cid"); do
              case " $SELF_NETS " in *" $net "*) PG_ID="$cid"; PG_NAME="$nm"; break 2 ;; esac
            done
          done
          test -n "$PG_ID" || { echo "FATAL: no postgres service container on this job's network (self nets: $SELF_NETS)"; exit 1; }
          echo "selected postgres: $PG_ID $PG_NAME"
          PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG_ID")
          test -n "$PG_IP"
          export MINSTREL_TEST_DATABASE_URL="postgres://minstrel:minstrel@${PG_IP}:5432/minstrel_test?sslmode=disable"
          # Wait for Postgres to accept TCP (no health-check dependency).
          for i in $(seq 1 60); do (echo > "/dev/tcp/${PG_IP}/5432") 2>/dev/null && break; sleep 2; done
          # Relax durability on the throwaway CI Postgres. Our test pattern
          # is dbtest.ResetDB → TRUNCATE … RESTART IDENTITY CASCADE before
          # every test, and the per-TRUNCATE commit fsync is the dominant
          # cost of the integration suite. The CI DB is rebuilt every run so
          # fsync / full_page_writes / synchronous_commit buy nothing. Apply
          # via docker exec because:
          #  - The act_runner `services:` block can't override the container
          #    command, so `postgres -c fsync=off` at boot isn't an option.
          #  - ALTER SYSTEM cannot run inside a transaction; psql -c
          #    auto-commits each statement, which is what we need.
          #  - fsync / full_page_writes are sighup GUCs and
          #    synchronous_commit is user-context, so pg_reload_conf() picks
          #    all three up with no restart.
          # Non-fatal: a perms surprise degrades to "slower", never red CI.
          docker exec "$PG_ID" psql -U minstrel -d minstrel_test \
            -c "ALTER SYSTEM SET fsync = off" \
            -c "ALTER SYSTEM SET synchronous_commit = off" \
            -c "ALTER SYSTEM SET full_page_writes = off" \
            -c "SELECT pg_reload_conf()" \
            || echo "WARN: durability relax failed; continuing"
          # Apply embedded migrations to the fresh test DB, then run the
          # full suite (no -short → integration tests execute). -p 1:
          # every integration package TRUNCATEs the one shared test DB;
          # concurrent package binaries → TRUNCATE deadlocks. Serialize
          # package execution (the documented local invocation too).
          MINSTREL_DATABASE_URL="$MINSTREL_TEST_DATABASE_URL" go run ./cmd/minstrel migrate
          go test -p 1 -race ./...
@@ -1,44 +0,0 @@
 name: test-web
 # Web SPA: vitest + svelte-check. Runs on push to dev/main only —
 # the `pull_request` trigger is intentionally omitted because every
 # branch on this repo is local-only (no fork PRs), so the dev push
 # fully covers what a PR run would re-execute. Keeping both events
 # doubled CI cost on every commit.
 on:
  push:
    branches: [dev, main]
    paths:
      - 'web/**'
      - '.gitea/workflows/test-web.yml'
 # Cancel an earlier in-flight run for the same ref when a newer
 # commit arrives. With cancel-in-progress, rapid re-pushes don't
 # pile up zombie runs.
 concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  test:
    runs-on: go-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-go:1.26
    defaults:
      run:
        working-directory: web
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install deps
        run: npm ci
      - name: Type-check + svelte-check
        run: npm run check
      - name: Vitest
        run: npm test
@@ -12,8 +12,11 @@
 # Test binary, built with `go test -c`
 *.test
-# Bundled Android APK + version sidecar (#397). Populated by CI for
+# `make build` output — an 18 MB binary that is never committed.
-# tag releases; never committed. README in client/ explains the flow.
+bin/
 # Bundled Android APK + version sidecar. Populated by CI on every image
 # build; never committed. README in client/ explains the flow.
 client/minstrel.apk
 client/minstrel.apk.version
@@ -39,10 +42,9 @@ go.work.sum
 docs/superpowers/
 # Per-machine Claude Code settings + remember-skill memory artifacts +
-# project-level Claude/AI instruction files. All operator-scoped; the
+# project-level Claude/AI instruction files. All per-machine;
-# canonical project memory lives under ~/.claude/projects/ outside the
+# CLAUDE.md/AGENTS.md/GEMINI.md are tool-specific working notes, not
-# repo. CLAUDE.md/AGENTS.md/GEMINI.md stay on the operator's machine
+# project artifacts.
 # only — they're tool-specific working notes, not project artifacts.
 .claude/
 .remember/
 CLAUDE.md
@@ -7,7 +7,7 @@ RUN npm ci
 COPY web/ ./
 RUN npm run build
-FROM golang:1.25-bookworm AS builder
+FROM golang:1.26-bookworm AS builder
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
@@ -15,17 +15,31 @@ COPY . .
 # Overwrite the committed placeholder with the freshly-built SPA assets.
 COPY --from=web /web/build ./web/build
 ENV CGO_ENABLED=0
-# Version stamping: release.yml passes the git tag via MINSTREL_VERSION
+# Version stamping. release.yml passes the DERIVED version name
-# build-arg; local `docker build` falls back to "dev". Surfaced at
+# (YYYY.MM.DD.HHMM) and the lane's channel; a local `docker build` falls back
-# /healthz for operator-side image-version verification.
+# to "dev"/"local". Both are surfaced at /healthz.
 #
 # These are two values on purpose: the same commit built on dev and on main
 # reports the same NAME and differs only in CHANNEL. Folding the channel
 # into the version string would make two dev images eight weeks apart
 # indistinguishable.
 ARG MINSTREL_VERSION=dev
 ARG MINSTREL_CHANNEL=local
 RUN go build -trimpath \
-    -ldflags="-s -w -X 'git.fabledsword.com/bvandeusen/minstrel/internal/server.ServerVersion=${MINSTREL_VERSION}'" \
+    -ldflags="-s -w \
      -X 'git.fabledsword.com/bvandeusen/minstrel/internal/buildinfo.Version=${MINSTREL_VERSION}' \
      -X 'git.fabledsword.com/bvandeusen/minstrel/internal/buildinfo.Channel=${MINSTREL_CHANNEL}'" \
    -o /out/minstrel ./cmd/minstrel
 FROM debian:bookworm-slim
 # ffmpeg: duration probes and the exact-tier audio hash (a SHA-256 of the
 # encoded audio packets, so no decode). libchromaprint-tools: fpcalc, the
 # acoustic fingerprint that tells the same recording at two bitrates apart
 # from two different recordings. Both are baked in at build time so a
 # deployed instance never fetches either; fpcalc is shelled out
 # rather than bound because CGO_ENABLED=0 above rules out cgo.
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends ca-certificates ffmpeg \
+    && apt-get install -y --no-install-recommends ca-certificates ffmpeg libchromaprint-tools \
    && rm -rf /var/lib/apt/lists/*
 RUN groupadd --system --gid 1000 minstrel \
@@ -42,10 +56,12 @@ COPY config.example.yaml /etc/smartmusic/config.yaml
 RUN mkdir -p /app/data /app/client && chown -R minstrel:minstrel /app
 WORKDIR /app
-# In-app update channel (#397). client/ in the build context holds
+# In-app update channel. client/ in the build context holds
-# minstrel.apk + minstrel.apk.version (populated by release.yml on tag
+# minstrel.apk + minstrel.apk.version, which release.yml fills on every
-# pushes; .gitkeep + README otherwise). Endpoints return 404 when the
+# build (dev and tag pushes bundle their own APK, main bundles the latest
-# APK files aren't present, so non-tag images degrade gracefully.
+# release's); a local build has only .gitkeep + README. Endpoints return
 # 404 when the APK files aren't present, so such an image degrades
 # gracefully.
 COPY --chown=minstrel:minstrel client/ /app/client/
 USER minstrel
@@ -13,11 +13,8 @@ generate:
 generate-go:
 	go run github.com/sqlc-dev/sqlc/cmd/sqlc@v$(SQLC_VERSION) generate
-# Fail if the committed generated code no longer matches the .sql sources.
+# Fail if the committed generated code no longer matches the .sql sources:
-#
+# a hand-edit, a half-applied regen, or a schema change without a regen.
 # Nothing verified this before, so internal/db/dbq could silently drift from
 # internal/db/queries — a hand-edit, a half-applied regen, or a schema change
 # without a regen would all pass CI while the typed layer lied about the SQL.
 #
 # The diff is printed BEFORE the exit-code check on purpose: when this fails,
 # the log then contains sqlc's exact expected output, which is what you commit.
@@ -36,8 +33,8 @@ test-short:
 	go test -short -race ./...
 # Full suite incl. integration tests, against the dedicated minstrel_test
-# DB so a run never truncates the dev `minstrel` DB (Fable #339). Ensures
+# DB so a run never truncates the dev `minstrel` DB. Ensures the test DB
-# the test DB exists (idempotent — createdb errors if present, ignored).
+# exists (createdb fails harmlessly if it is already there).
 test-integration:
 	docker compose up -d postgres
 	-docker compose exec -T postgres createdb -U minstrel minstrel_test
@@ -1,33 +1,14 @@
-# Minstrel
+<p align="center"><img src="web/static/brand/mark.svg" width="120" alt="Minstrel logo"></p>
-A self-hosted music server that thinks for you. Smart shuffle, contextual likes, ListenBrainz-aware radio, and Lidarr automation — server-side, so every client (web, mobile, Subsonic third-party) gets the same intelligence.
+<h1 align="center">Minstrel</h1>
-> State and intelligence belong on the server, not the client.
+<p align="center">A self-hosted music server that picks what to play next.</p>
 Minstrel serves your music library to the web, to its own Android app, and to any Subsonic client. Shuffle, radio, likes and play history are worked out on the server, so every device gets the same mixes and the same history. It can also find, download and file the albums you want, through a search service and a download client you run yourself. It is for anyone who keeps their own music collection and wants it to sound like more than a random shuffle.
 <a href="docs/screenshots/home.png"><img src="docs/screenshots/home.png" width="820" alt="Minstrel home — your library at a glance"></a>
-## Highlights
+## Quick start
 - **OpenSubsonic-compatible.** Existing Subsonic clients (DSub, Symfonium, play:Sub, etc.) connect with no special configuration.
 - **Server-side smart shuffle.** Track-similarity vectors, dual-like model (general + contextual), and session memory keep mixes coherent across devices.
 - **ListenBrainz radio.** Session-aware "more like this" pulls from ListenBrainz similarity data, not a static genre tag.
 - **Lidarr integration.** Triggered scans, request-driven album imports, and a quarantine flow when something doesn't fit — against a Lidarr instance *you* run and configure. Optional, and off until you supply a URL and API key.
 - **Built-in web SPA.** Full-feature library, search, queue, playlists, and admin — no separate frontend container to deploy.
 - **Native Android client, shipped with the server.** The signed APK is bundled into every image and attached to each [release](https://git.fabledsword.com/bvandeusen/minstrel/releases) — sideload it once, then the app self-updates straight from your own server (no app store, no separate download to track).
 ## Scope and responsible use
 **Minstrel serves music you already have.** It is a library server: it indexes files on disk you point it at, and streams them to your own clients. It does not source, search for, or acquire content, and it has no opinion about where your files came from.
 Concretely, Minstrel ships **no** indexers, **no** trackers, **no** torrent / Usenet / NZB client, and **no** DRM circumvention of any kind. There is nothing to point at a content source because Minstrel has no such subsystem.
 The **Lidarr integration is optional and inert until you configure it.** You supply the URL and API key of a Lidarr instance you are already running; Minstrel then calls that instance's API to trigger scans, submit album requests, and reconcile imports. Minstrel neither bundles nor installs Lidarr, and configures no indexers on your behalf — Lidarr ships with none either, and any it uses are ones you added yourself.
 **What you put in your library, and what sources you configure in your own Lidarr, are your responsibility.** Copyright law applies to your collection the same way it applies to any other software that plays a file. Please respect it, and respect the terms of any service you connect.
 Minstrel is not affiliated with or endorsed by Lidarr, ListenBrainz, MusicBrainz, or Subsonic.
 ## Quickstart
 ```yaml
 # compose.yaml
@@ -36,18 +17,10 @@ services:
    image: git.fabledsword.com/bvandeusen/minstrel:latest
    ports: ['4533:4533']
    volumes:
-      # Your music library. Point ./music at wherever your audio files
+      - ./music:/music              # your library; must be writable by uid 1000
-      # live. Mounted read-only — Minstrel never writes to your library.
+      - minstrel-data:/app/data     # art and caches
      - ./music:/music:ro
      # Generated data: playlist cover collages, artist art, caches.
      # The path must match MINSTREL_STORAGE_DATA_DIR, which the image
      # sets to /app/data — keep this mount on /app/data or your cache
      # won't survive a container recreate.
      - minstrel-data:/app/data
    environment:
      MINSTREL_DATABASE_URL: postgres://minstrel:minstrel@db:5432/minstrel?sslmode=disable
      # Colon-separated library roots to scan; must match the container
      # path of the read-only music mount above (/music here).
      MINSTREL_LIBRARY_SCAN_PATHS: /music
    depends_on: [db]
@@ -57,9 +30,7 @@ services:
      POSTGRES_USER: minstrel
      POSTGRES_PASSWORD: minstrel
      POSTGRES_DB: minstrel
-    # Postgres data dir — users, likes, play history, sessions, settings.
+    volumes: [pgdata:/var/lib/postgresql/data]   # users, likes, history: back this up
    # The one volume you must never lose; back it up with pg_dump.
    volumes: [pgdata:/var/lib/postgresql/data]
 volumes:
  minstrel-data:
@@ -68,92 +39,101 @@ volumes:
 ```bash
 docker compose up -d
 docker compose logs minstrel | grep setup_token
 ```
-## First run
+Open `http://<host>:4533/register` and create the first account with that setup token. The first account is the administrator.
-With the stack up, a handful of in-app steps get you to a working library. Use your own host in place of `localhost` if you're reaching the server over a LAN/VPN address (plain `http://` is fine — no TLS required).
+### First run
-**1. Create your admin account.** Visit `http://localhost:4533/register`. The first account on a fresh instance is automatically the administrator; later users join through the same form or an invite token (step 5).
+1. **Let the first scan finish.** Minstrel scans the library on startup. Watch it, or scan again, on the **Admin** page (`/admin`). Later scans only pick up what changed.
-
+2. **Install the Android app.** In **Settings** (`/settings`), the *Install the Android app* card downloads the app this server ships. It updates itself from your server after that.
-<a href="docs/screenshots/register.png"><img src="docs/screenshots/register.png" width="320" alt="Creating the first (admin) account on a fresh instance"></a>
+3. **Invite the household.** In **Admin › Users** (`/admin/users`), make an invite token or turn on open registration. Each person gets their own likes, history and recommendations.
-
+4. **Optional: connect services.** Add a search service and a download client in **Admin › Acquisition** (`/admin/acquisition`). Each person adds their own ListenBrainz token in **Settings › Connections**.
 **2. Let the first library scan finish.** `scan_on_startup` is on by default, so Minstrel walks your mounted library on boot and imports artists, albums, and tracks — no button to press. Watch progress (and re-scan any time) on the **Admin** page (`/admin`); the scan runs in stages and is incremental, so later restarts only pick up what changed.
 <a href="docs/screenshots/library-scan.png"><img src="docs/screenshots/library-scan.png" width="820" alt="The Admin page, where the library scan runs and reports progress"></a>
 **3. (Optional) Name the instance and wire up integrations.** In admin **Settings → Integrations** (`/admin/integrations`), add a ListenBrainz token (scrobbling + similarity radio) and/or a Lidarr URL + API key (the request flow). These live in the UI and apply without a restart; the display name can also be set via `MINSTREL_BRANDING_APP_NAME`.
 <a href="docs/screenshots/integrations.png"><img src="docs/screenshots/integrations.png" width="820" alt="ListenBrainz and Lidarr integration cards in admin Settings"></a>
 **4. Install the Android app.** Open **Settings** (`/settings`) and use the *Install the Android app* card to download the APK that ships inside this server image, then sign in with the same account. From then on the app self-updates straight from your server.
 <a href="docs/screenshots/android-download.png"><img src="docs/screenshots/android-download.png" width="820" alt="The &quot;Install the Android app&quot; download card in Settings"></a>
 **5. Invite the rest of the household.** From admin **Users** (`/admin/users`), generate an invite token (or enable open registration). Each person gets their own account, so likes, play history, and recommendations stay per-user.
 <a href="docs/screenshots/invite-users.png"><img src="docs/screenshots/invite-users.png" width="820" alt="Generating an invite token in admin Users"></a>
 For the full configuration surface, see [`config.example.yaml`](./config.example.yaml).
 ## Configuration
-Most operators only need the env vars in the quickstart above. A few extras worth knowing:
+The quick start sets everything that's required. These are the settings people most often change:
- `MINSTREL_BRANDING_APP_NAME` — rename the instance ("Family Jukebox", "Office Music"). Surfaces in the header, browser tab, and OG share previews.
+| Variable | What it does |
- `MINSTREL_STORAGE_DATA_DIR` — where generated artefacts (playlist cover collages, artist art, caches) are written. The container image sets this to `/app/data`, which is why the quickstart mounts the `minstrel-data` volume there.
+|---|---|
- `MINSTREL_LIBRARY_SCAN_PATHS` — colon-separated list of music library roots to scan. Supports multiple roots (`/music:/podcasts`).
+| `MINSTREL_DATABASE_URL` | Postgres connection string. Required. |
 | `MINSTREL_LIBRARY_SCAN_PATHS` | Library folders inside the container, colon-separated (`/music:/audiobooks`). They are used on first start only; after that, change them in **Admin › Library**. |
 | `MINSTREL_BRANDING_APP_NAME` | The name shown in the header, the browser tab and link previews. |
 | `MINSTREL_LOG_LEVEL` | `debug`, `info`, `warn` or `error`. |
-ListenBrainz integration (per-user scrobble + similarity tokens) and Lidarr integration (URL + API key) are configured through the admin Settings UI rather than env vars or yaml — per Minstrel's "config in UI" rule, integration settings live where operators can edit them without restarting.
+Search services, download clients, ListenBrainz, email and recommendation tuning are set in the web UI and take effect without a restart. The full file-based surface is in [`config.example.yaml`](./config.example.yaml); to use it, mount your copy at `/etc/smartmusic/config.yaml`.
-Most operational keys have a `MINSTREL_<SECTION>_<FIELD>` env override. Recommendation and events tuning are yaml-only. See [`config.example.yaml`](./config.example.yaml) for the authoritative surface.
+## Setup pitfalls
-## Updating
+- **The library mount has to be writable by uid 1000.** Minstrel files the albums it downloads into the library, and it deletes a file when an admin asks it to. It never moves, renames or retags files that were already there. Mount the library `:ro` to forbid writes: those actions then refuse and say why.
 - **`MINSTREL_LIBRARY_SCAN_PATHS` names the path inside the container** (`/music`), not the folder on your host.
 - **On the internet, put it behind HTTPS.** Plain `http://` is fine on a network you trust. For a public server, bind the port to `127.0.0.1` and put a reverse proxy in front: see [docs/hosting.md](docs/hosting.md).
-Image tags (`git.fabledsword.com/bvandeusen/minstrel:<tag>`):
+## Updating and backups
- `:latest` — the newest blessed image. Moves on every `main` push **and** every release. Recommended for most operators.
+```bash
- `:vYYYY.MM.DD` — immutable per-day release tags. Pin one of these for a deployment you don't want moving under you. (Per-day CalVer — no trailing patch digit; a same-day re-cut moves the tag forward.)
+docker compose pull && docker compose up -d
- `:main` — the rolling post-merge tip. Same image as `:latest` at push time; choose it if you want to track `main` explicitly rather than the release line.
+```
-Every `:latest` and every `:vYYYY.MM.DD` bundles the current signed Android APK, so the in-app update channel is always live. Database migrations run automatically at startup; rollbacks require restoring a Postgres dump.
+Database migrations run at startup. Image tags:
-## Specs
+- `:latest`: the stable release. Most people should run this.
 - `:<commit-sha>`: one fixed build. Pin one to stop updates, or to roll back.
 - `:dev`: the test channel, rebuilt on every change. It may break, and the fix is the next build.
-Authoritative scope lives under [`docs/`](./docs):
+Every image carries a signed Android app, all with the same key, so a phone can move between channels without reinstalling. Rolling back a SHA tag rolls back the app it carries too.
- [Server spec](./docs/smart-music-server-spec.md) — current implementation focus.
+**Back up the Postgres volume** with `pg_dump`. It holds accounts, likes, play history, playlists and settings, and a migration can only be undone by restoring a dump. The `minstrel-data` volume holds artwork and caches that Minstrel rebuilds if lost.
- [Client spec](./docs/smart-music-client-spec.md) — Flutter companion app.
+
 ## Features
 **Listening**
 - Smart shuffle that weighs what you like, what you skip and what you've heard lately, instead of picking at random.
 - Two kinds of like: a song you love, and a song that's right for what you're listening to now.
 - Radio that starts from any song, using ListenBrainz similarity as well as your own history.
 - Daily mixes and system playlists built from your listening.
 - Playback on Sonos and other UPnP speakers from the Android app.
 - Loudness levelling between tracks, so you never reach for the volume.
 **Your library**
 - Browse by artist, album, genre and year, with search across everything.
 - Duplicates, missing files and suspect copies are found and listed under **Collection** for an admin to fix.
 - Missing album art and MusicBrainz ids are filled in automatically.
 **Getting music**
 - A wanted list: requests from the household, artists you follow, and albums whose files went missing.
 - Minstrel searches the indexers you configure, hands the best release to your download client, checks what arrives against MusicBrainz, tags it, and files it. A better copy replaces a poor one.
 - Off until you add a search service and a download client.
 **Clients and accounts**
 - A full web app, built into the server.
 - A native Android app that ships inside the server image, keeps playing what it has cached when the server is out of reach, and updates itself from your server.
 - OpenSubsonic-compatible, so existing clients such as DSub, Symfonium and play:Sub connect as they are.
 - Separate accounts for each person, with invites, and an inbox for what happened while you were away.
 ## Scope and responsible use
 Minstrel indexes the files you point it at and streams them to your own clients. It ships no indexers, no trackers, no torrent, Usenet or NZB engine of its own, and no DRM circumvention.
 Getting music is optional and does nothing until you configure it. It searches only the search service (Prowlarr or a Torznab indexer) and the download client (qBittorrent) you add yourself.
 What you put in your library, and the sources you configure, are your responsibility. Copyright law applies to your collection as it does to any other software that plays a file; please respect it, and the terms of any service you connect.
 Minstrel is not affiliated with or endorsed by ListenBrainz, MusicBrainz, Prowlarr, qBittorrent or Subsonic.
 ## Development
-Two concurrent dev processes:
+- **Backend:** `docker compose up` in this repo runs Postgres and Minstrel on `:4533`.
 - **Web:** `cd web && npm install && npm run dev` starts Vite on `:5173`. It proxies `/api/*` and `/rest/*` to `:4533`.
 - **Tests:** `make test-short` runs the unit tests. `make test-integration` also runs the database tests, against a separate `minstrel_test` database so your dev data is never truncated.
 - **Image:** `docker build -t minstrel .` builds the web app and embeds it in the server binary.
 - **Branches:** work lands on `dev`; `main` changes through pull requests from `dev`.
-1. **Backend:** `docker compose up` — Postgres + Minstrel on `:4533`.
+How accounts and sessions are protected: [docs/security.md](docs/security.md).
 2. **Frontend:** `cd web && npm install && npm run dev` — Vite dev server on `:5173` with HMR. The Vite server proxies `/api/*` and `/rest/*` to `:4533` so session cookies work.
 ### Testing
 - Unit + race (no DB): `make test-short`.
 - Full suite incl. integration tests: `make test-integration`. This runs
  against a dedicated `minstrel_test` database so a test run never
  truncates your dev `minstrel` data (admin user, library, likes). It
  brings up the compose Postgres and creates the test DB if missing.
 - CI runs both: a fast `go test -short -race` gate plus an integration
  job with its own ephemeral Postgres (`.gitea/workflows/test-go.yml`).
 ### Production build
 `docker build -t minstrel .` runs the SvelteKit build inside a `node` stage, copies the output into the `golang` stage, and `//go:embed`s it into the final binary. The container serves the SPA from `/` alongside the API surfaces; no separate static-file server is required.
 ### Branches
 - Day-to-day work happens on `dev` (or feature branches merged into `dev`).
 - `main` is **protected** — changes land via PR from `dev`.
 - Releases are cut by tagging `v*` off `main`; the release workflow builds and pushes the container image to the Gitea registry.
 Task and milestone tracking: Fable (`Minstrel` project, id 12).
 ## License
-See [LICENSE](./LICENSE).
+MIT. See [LICENSE](./LICENSE).
@@ -1,9 +1,9 @@
 plugins {
    alias(libs.plugins.android.application)
    // kotlin-android NOT applied: AGP 9 enables built-in Kotlin by default,
-    // and KSP 2.3.x supports it (PR #2674, merged Oct 2025). serialization
+    // and KSP 2.3.x supports it. serialization + compose-compiler are
-    // + compose-compiler are language-level Kotlin compiler plugins and
+    // language-level Kotlin compiler plugins and still need explicit
-    // still need explicit application.
+    // application.
    alias(libs.plugins.kotlin.serialization)
    alias(libs.plugins.compose.compiler)
    alias(libs.plugins.ksp)
@@ -21,13 +21,19 @@ android {
        applicationId = "com.fabledsword.minstrel"
        minSdk = 26
        targetSdk = 36
-        // versionName / versionCode are released-build values injected by
+        // versionName / versionCode are released-build values injected by CI.
-        // CI from the git tag + commit count. Local / debug builds fall
+        // Local / debug builds fall back to "dev" so the About card reads
-        // back to "dev" so the About card reads honestly. Releases ship
+        // honestly.
-        // versionName="YYYY.MM.DD.<commits>" (e.g. "2026.06.02.142") and
+        //
-        // versionCode=<commits>, which is monotonic forever and lets the
+        // versionName is "YYYY.MM.DD.HHMM" from the COMMIT's timestamp, so
-        // shared isVersionNewer comparator distinguish two same-day
+        // every lane building this source reports the same string and the
-        // re-cuts (the iteration suffix differs).
+        // channel is the only thing that differs between them.
        //
        // versionCode is minutes since 2020-01-01 at BUILD time. It is the
        // value the platform decides installs by, so it must be monotonic by
        // construction. Not a commit count: that runs ahead on `dev`, so a dev
        // build would outrank the `main` release meant to replace it and
        // Android would refuse the install as a downgrade.
        val versionNameOverride =
            (project.findProperty("MINSTREL_VERSION_NAME") as String?)?.takeIf { it.isNotBlank() }
        val versionCodeOverride =
@@ -61,9 +67,13 @@ android {
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro",
            )
            // Signed with the release key or not at all. Falling back to the
            // debug key would turn a missing secret into a published APK that no
            // install could ever update. An unsigned build installs nowhere, so
            // the gap shows at once.
            signingConfig =
                if (System.getenv("ANDROID_KEYSTORE_PATH").isNullOrEmpty()) {
-                    signingConfigs.getByName("debug")
+                    null
                } else {
                    signingConfigs.getByName("release")
                }
@@ -150,7 +160,6 @@ dependencies {
    implementation(libs.compose.ui)
    implementation(libs.compose.ui.graphics)
    implementation(libs.compose.material3)
    implementation(libs.compose.ui.text.google.fonts)
    debugImplementation(libs.compose.ui.tooling)
    implementation(libs.compose.ui.tooling.preview)
@@ -8,6 +8,10 @@
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <!-- Notifications when the app is closed: the delivery
         service, and starting it again after a reboot or an update. -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
    <!-- In-app self-update. REQUEST_INSTALL_PACKAGES lets us hand an APK to the
         platform installer at all; UPDATE_PACKAGES_WITHOUT_USER_ACTION (API 31+)
         is what lets that install happen with NO confirm dialog. The platform
@@ -57,11 +61,31 @@
            </intent-filter>
        </service>
-        <!-- The FileProvider that used to live here existed solely to expose the
+        <!-- Keeps the process alive so notifications arrive with the app
-             downloaded update APK as a content:// URI for the old ACTION_VIEW
+             closed. specialUse: dataSync is stopped after six hours on
-             install intent. A PackageInstaller session takes a stream instead,
+             Android 15, and shortService after three minutes. -->
-             so both the provider and res/xml/file_paths.xml are gone — nothing
+        <service
-             else in the app ever used that authority. -->
+            android:name=".notifications.delivery.DeliveryService"
            android:exported="false"
            android:foregroundServiceType="specialUse">
            <property
                android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
                android:value="Maintains the connection to the user's own Minstrel server that delivers their notifications, in place of a third-party push service." />
        </service>
        <!-- Starts delivery after a reboot or an update; both broadcasts may
             start a foreground service from the background. -->
        <receiver
            android:name=".notifications.delivery.BootReceiver"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.BOOT_COMPLETED" />
                <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
            </intent-filter>
        </receiver>
        <!-- No FileProvider: the self-update streams the downloaded APK into a
             PackageInstaller session, so nothing needs a content:// URI. -->
        <!-- On-demand WorkManager initialization: MinstrelApplication
             implements Configuration.Provider and supplies the
@@ -1,10 +1,14 @@
 package com.fabledsword.minstrel
 import android.Manifest
 import android.content.Intent
 import android.content.pm.PackageManager
 import android.os.Build
 import android.os.Bundle
 import androidx.activity.ComponentActivity
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
 import androidx.activity.result.contract.ActivityResultContracts
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.material3.CircularProgressIndicator
@@ -16,9 +20,12 @@ import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.core.content.ContextCompat
 import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.lifecycle.lifecycleScope
 import androidx.navigation.compose.rememberNavController
 import com.fabledsword.minstrel.auth.AuthStore
 import com.fabledsword.minstrel.auth.ui.AuthGateViewModel
 import com.fabledsword.minstrel.cache.CachedTrackIds
 import com.fabledsword.minstrel.connectivity.LocalServerHealth
@@ -27,7 +34,10 @@ import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.nav.DetailSeedCache
 import com.fabledsword.minstrel.nav.LocalDetailSeedCache
 import com.fabledsword.minstrel.nav.MinstrelNavGraph
 import com.fabledsword.minstrel.nav.Notifications
 import com.fabledsword.minstrel.nav.NowPlaying
 import com.fabledsword.minstrel.notifications.delivery.deliveryWanted
 import com.fabledsword.minstrel.notifications.ui.routeForLink
 import com.fabledsword.minstrel.shared.widgets.LocalCachedTrackIds
 import com.fabledsword.minstrel.theme.MinstrelTheme
 import com.fabledsword.minstrel.theme.ThemePreferenceViewModel
@@ -35,6 +45,10 @@ import dagger.hilt.android.AndroidEntryPoint
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.launch
 import javax.inject.Inject
@AndroidEntryPoint
@@ -42,41 +56,72 @@ class MainActivity : ComponentActivity() {
    @Inject lateinit var seedCache: DetailSeedCache
    @Inject lateinit var cachedTrackIds: CachedTrackIds
    @Inject lateinit var serverHealth: NetworkStatusController
    @Inject lateinit var authStore: AuthStore
-    // Flipped to true when the user taps the media notification (or
+    // Set when the user taps a notification: the media one asks for the full
-    // any other entry point that asks for the full player). The App
+    // player, a Minstrel notice for what it is about. The App composable
-    // composable observes this, navigates to NowPlaying once the
+    // navigates there once the NavHost is ready, then calls back to clear it
-    // NavHost is ready, then calls back to reset the flag so the
+    // so the navigation doesn't re-fire on the next recomposition.
-    // navigation doesn't re-fire on the next recomposition.
+    private val pendingRoute = MutableStateFlow<Any?>(null)
-    private val pendingOpenNowPlaying = MutableStateFlow(false)
+
    // The answer needs no handling: the system remembers it, and the
    // notification settings screen reads it on every resume.
    private val askToNotify = registerForActivityResult(ActivityResultContracts.RequestPermission()) { }
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
-        consumeOpenNowPlayingIntent(intent)
+        consumeRouteIntent(intent)
        askToNotifyOnceWanted()
        setContent {
            App(
                seedCache = seedCache,
                cachedTrackIds = cachedTrackIds,
                serverHealth = serverHealth,
-                pendingOpenNowPlaying = pendingOpenNowPlaying.asStateFlow(),
+                pendingRoute = pendingRoute.asStateFlow(),
-                onOpenedNowPlaying = { pendingOpenNowPlaying.value = false },
+                onOpenedRoute = { pendingRoute.value = null },
            )
        }
    }
    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
-        consumeOpenNowPlayingIntent(intent)
+        consumeRouteIntent(intent)
    }
-    private fun consumeOpenNowPlayingIntent(intent: Intent?) {
+    private fun consumeRouteIntent(intent: Intent?) {
-        if (intent?.getBooleanExtra(EXTRA_OPEN_NOW_PLAYING, false) == true) {
+        if (intent == null) return
-            pendingOpenNowPlaying.value = true
+        if (intent.getBooleanExtra(EXTRA_OPEN_NOW_PLAYING, false)) {
            pendingRoute.value = NowPlaying
            // Strip the extra so a subsequent config-change recreation
            // doesn't re-trigger the navigation.
            intent.removeExtra(EXTRA_OPEN_NOW_PLAYING)
        }
        intent.getStringExtra(EXTRA_NOTIFICATION_LINK)?.let { link ->
            // A notice the app has no screen for, or a pile of them, opens
            // the inbox.
            pendingRoute.value = routeForLink(link) ?: Notifications
            intent.removeExtra(EXTRA_NOTIFICATION_LINK)
        }
    }
    /**
     * Android 13+ asks before an app may post notifications.
     * Asked once delivery is wanted (signed in, background delivery on),
     * each launch until answered: after a second "no" the system stops
     * showing the prompt by itself, and Settings → Notifications links to
     * the system page.
     */
    private fun askToNotifyOnceWanted() {
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) return
        lifecycleScope.launch {
            val signedIn = authStore.sessionCookie.map { !it.isNullOrEmpty() }
            combine(signedIn, authStore.backgroundDelivery, ::deliveryWanted).first { it }
            val permission = Manifest.permission.POST_NOTIFICATIONS
            val granted = ContextCompat.checkSelfPermission(this@MainActivity, permission) ==
                PackageManager.PERMISSION_GRANTED
            if (!granted) askToNotify.launch(permission)
        }
    }
    companion object {
@@ -84,6 +129,10 @@ class MainActivity : ComponentActivity() {
         *  so a media-notification tap lands on the full NowPlaying screen
         *  instead of whatever shell route MainActivity last rendered. */
        const val EXTRA_OPEN_NOW_PLAYING = "com.fabledsword.minstrel.action.OPEN_NOW_PLAYING"
        /** PendingIntent extra on a Minstrel notice: the web path it links to,
         *  or empty for a pile, which opens the inbox. */
        const val EXTRA_NOTIFICATION_LINK = "com.fabledsword.minstrel.action.NOTIFICATION_LINK"
    }
 }
@@ -92,15 +141,15 @@ private fun App(
    seedCache: DetailSeedCache,
    cachedTrackIds: CachedTrackIds,
    serverHealth: NetworkStatusController,
-    pendingOpenNowPlaying: StateFlow<Boolean>,
+    pendingRoute: StateFlow<Any?>,
-    onOpenedNowPlaying: () -> Unit,
+    onOpenedRoute: () -> Unit,
    themeVm: ThemePreferenceViewModel = hiltViewModel(),
    gate: AuthGateViewModel = hiltViewModel(),
 ) {
    val theme by themeVm.themeMode.collectAsStateWithLifecycle()
    val cached by cachedTrackIds.ids.collectAsStateWithLifecycle()
    val health: ServerHealth by serverHealth.state.collectAsStateWithLifecycle()
-    val pending by pendingOpenNowPlaying.collectAsStateWithLifecycle()
+    val pending by pendingRoute.collectAsStateWithLifecycle()
    MinstrelTheme(darkOverride = theme.toDarkOverride()) {
        CompositionLocalProvider(
            LocalDetailSeedCache provides seedCache,
@@ -119,16 +168,14 @@ private fun App(
                // Queue / unauthenticated) bypass the shell entirely.
                val navController = rememberNavController()
                // Honour a pending notification-tap once the NavHost is
-                // mounted. launchSingleTop avoids stacking copies of
+                // mounted. launchSingleTop avoids stacking copies of a
-                // NowPlaying if the user taps the notification while
+                // screen if the user taps the notification while already
-                // already on it; the callback clears the flag so a later
+                // on it; the callback clears it so a later recomposition
-                // recomposition (config change, theme switch) doesn't
+                // (config change, theme switch) doesn't re-navigate.
                // re-navigate.
                LaunchedEffect(pending, navController) {
-                    if (pending) {
+                    val route = pending ?: return@LaunchedEffect
-                        navController.navigate(NowPlaying) { launchSingleTop = true }
+                    navController.navigate(route) { launchSingleTop = true }
-                        onOpenedNowPlaying()
+                    onOpenedRoute()
                    }
                }
                MinstrelNavGraph(
                    navController = navController,
@@ -8,6 +8,7 @@ import coil3.SingletonImageLoader
 import coil3.network.okhttp.OkHttpNetworkFetcherFactory
 import coil3.request.crossfade
 import com.fabledsword.minstrel.cache.CacheIndexer
 import com.fabledsword.minstrel.cache.audiocache.CacheBudgetSync
 import com.fabledsword.minstrel.cache.mutations.MutationReplayer
 import com.fabledsword.minstrel.cache.sync.SyncController
 import com.fabledsword.minstrel.di.ApplicationScope
@@ -16,12 +17,13 @@ import com.fabledsword.minstrel.diagnostics.DiagnosticsUploader
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.events.LiveEventsDispatcher
 import com.fabledsword.minstrel.metadata.FreshnessSweeper
 import com.fabledsword.minstrel.notifications.delivery.DeliveryLauncher
 import com.fabledsword.minstrel.player.AudioPrefetcher
 import com.fabledsword.minstrel.player.CoverPrefetcher
 import com.fabledsword.minstrel.player.LikedAudioPinner
 import com.fabledsword.minstrel.player.PlayEventsReporter
 import com.fabledsword.minstrel.player.PlaybackErrorReporter
 import com.fabledsword.minstrel.player.ResumeController
 import com.fabledsword.minstrel.update.data.UpdateBannerController
 import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import dagger.hilt.android.HiltAndroidApp
 import kotlinx.coroutines.CoroutineScope
@@ -75,6 +77,14 @@ class MinstrelApplication :
     */
    @Suppress("unused") @Inject lateinit var mutationReplayer: MutationReplayer
    /**
     * Same construct-the-singleton trick — DeliveryLauncher starts and stops
     * the background-delivery service and runs the notification catch-up on
     * every nudge and reconnect. Without this @Inject no phone
     * notification would ever be posted.
     */
    @Suppress("unused") @Inject lateinit var deliveryLauncher: DeliveryLauncher
    /**
     * Same construct-the-singleton trick — PlayEventsReporter's init
     * block subscribes to PlayerController.uiState and reports the
@@ -111,6 +121,21 @@ class MinstrelApplication :
     */
    @Suppress("unused") @Inject lateinit var cacheIndexer: CacheIndexer
    /**
     * Same construct-the-singleton trick — CacheBudgetSync's init block
     * feeds the audio cache's evictor the liked set and the Storage caps.
     * Without this @Inject the evictor would never arm, and the cache
     * would grow without a limit.
     */
    @Suppress("unused") @Inject lateinit var cacheBudgetSync: CacheBudgetSync
    /**
     * Same construct-the-singleton trick — LikedAudioPinner's init block
     * downloads liked tracks into the Liked songs budget. Without this
     * @Inject, liking a track would not keep it offline.
     */
    @Suppress("unused") @Inject lateinit var likedAudioPinner: LikedAudioPinner
    /**
     * Same construct-the-singleton trick — AudioPrefetcher's init
     * block subscribes to PlayerController.uiState +
@@ -129,14 +154,6 @@ class MinstrelApplication :
     */
    @Suppress("unused") @Inject lateinit var networkStatusController: NetworkStatusController
    /**
     * Same construct-the-singleton trick — UpdateBannerController polls
     * /api/client/version at launch + every 24h and drives the shell's
     * soft "update available" banner. Without this @Inject the poll
     * loop would never start and the banner would never surface.
     */
    @Suppress("unused") @Inject lateinit var updateBannerController: UpdateBannerController
    /**
     * Same construct-the-singleton trick — FreshnessSweeper's init
     * block starts a 30-min sweep loop that re-fetches cached
@@ -162,7 +179,7 @@ class MinstrelApplication :
     */
    @Suppress("unused") @Inject lateinit var liveEventsDispatcher: LiveEventsDispatcher
-    // Device diagnostics (M9). The reporter gates itself on the account's
+    // Device diagnostics. The reporter gates itself on the account's
    // debug flag; the uploader drains its buffer on a tick / recovery.
    @Suppress("unused") @Inject lateinit var diagnosticsReporter: DiagnosticsReporter
    @Suppress("unused") @Inject lateinit var diagnosticsUploader: DiagnosticsUploader
@@ -172,7 +189,7 @@ class MinstrelApplication :
    override fun onCreate() {
        super.onCreate()
        // Debug builds get the full DebugTree (verbose). Release builds
-        // get a WARN+ tree so operator-driven diagnosis via `adb logcat`
+        // get a WARN+ tree so diagnosis via `adb logcat`
        // still surfaces UPnP / cast failures, OkHttp errors, and our
        // own Timber.w / Timber.e calls — without the chatty DEBUG /
        // INFO traffic flooding the buffer in production.
@@ -220,10 +237,9 @@ class MinstrelApplication :
     * before Coil makes its first request.
     *
     * Crossfade is set here rather than per-call so every cover surface
-     * in the app fades its artwork in instead of snapping it. Art
+     * in the app fades its artwork in instead of snapping it, and
-     * landing a beat after its tile was the most visible pop-in on Home
+     * `ServerImage` fades its placeholder out over the same window so the
-     * (issue #2327); `ServerImage` fades its placeholder out over the
+     * two read as one cross-dissolve.
     * same window so the two read as one cross-dissolve.
     */
    override fun newImageLoader(context: android.content.Context): ImageLoader =
        ImageLoader.Builder(context)
@@ -11,10 +11,9 @@ import javax.inject.Inject
 import javax.inject.Singleton
 /**
- * Read-through accessor for the admin quarantine queue. Mirrors the
+ * Read-through accessor for the admin quarantine queue. No Room cache —
- * Flutter `AdminQuarantineController`. No Room cache — same rationale
+ * same rationale as AdminRequests. Three resolution actions all delete
- * as AdminRequests. Three resolution actions all delete the row from
+ * the row from the queue once the server accepts them.
 * the queue once the server accepts them.
 */
@Singleton
 class AdminQuarantineRepository @Inject constructor(
@@ -27,8 +26,6 @@ class AdminQuarantineRepository @Inject constructor(
    suspend fun resolve(trackId: String) = api.resolve(trackId)
    suspend fun deleteFile(trackId: String) = api.deleteFile(trackId)
    suspend fun deleteViaLidarr(trackId: String) = api.deleteViaLidarr(trackId)
 }
 // ── Mappers ──
@@ -49,7 +46,6 @@ private fun AdminQuarantineItemWire.toDomain(): AdminQuarantineItemRef =
        artistName = artistName,
        albumTitle = albumTitle,
        albumId = albumId,
        lidarrAlbumMbid = lidarrAlbumMbid,
        reportCount = reportCount,
        latestAt = latestAt,
        reasonCounts = reasonCounts,
@@ -14,7 +14,7 @@ import javax.inject.Singleton
 *
 * No Room caching — admin actions are infrequent and don't benefit
 * from offline scrollback. `approve` and `reject` fire direct REST
- * (no mutation queue) because operator confirmation is point-and-shoot;
+ * (no mutation queue) because admin confirmation is point-and-shoot;
 * if the request fails the UI surfaces the error and rolls back.
 */
@Singleton
@@ -33,6 +33,7 @@ class AdminRequestsRepository @Inject constructor(
 private fun RequestWire.toDomain(): RequestRef = RequestRef(
    id = id,
    userId = userId,
    username = username,
    status = RequestStatus.fromWire(status),
    kind = kind,
    artistName = artistName,
@@ -12,7 +12,7 @@ import javax.inject.Inject
 import javax.inject.Singleton
 /**
- * Read-through accessor for the tag-enrichment provider settings (#1521).
+ * Read-through accessor for the tag-enrichment provider settings.
 * No Room caching — admin settings are infrequent point-and-shoot edits;
 * mutations fire direct REST and the ViewModel reconciles on failure.
 * Exceptions propagate to the ViewModel (which maps them via ErrorCopy).
@@ -13,8 +13,8 @@ import javax.inject.Singleton
 /**
 * Read-through accessor for the admin users list + the four per-user
- * mutations. Mirrors Flutter's `AdminUsersController`. Same
+ * mutations. Same no-Room-cache, no-MutationQueue pattern as the other
- * no-Room-cache, no-MutationQueue pattern as the other admin slices.
+ * admin repositories.
 */
@Singleton
 class AdminUsersRepository @Inject constructor(
@@ -39,7 +39,7 @@ class AdminInvitesViewModel @Inject constructor(
    init {
        refresh()
-        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // Screen-level auto-recovery: reload a failed list
        // when server health returns instead of waiting for a manual pull.
        viewModelScope.launch {
            networkStatus.recoveries().collect {
@@ -154,7 +154,7 @@ private fun SectionList(counts: AdminCounts, navController: NavHostController) {
            SectionCard(
                icon = Lucide.Inbox,
                title = "Requests",
-                subtitle = "Approve or reject Lidarr requests",
+                subtitle = "Approve or reject requests for new music",
                count = counts.requests,
                onClick = { navController.navigate(AdminRequests) },
            )
@@ -9,16 +9,19 @@ import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.lazy.LazyColumn
 import androidx.compose.foundation.lazy.items
 import androidx.compose.material3.AssistChip
 import androidx.compose.material3.Button
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.HorizontalDivider
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.OutlinedButton
 import androidx.compose.material3.Scaffold
 import androidx.compose.material3.SnackbarHost
 import androidx.compose.material3.SnackbarHostState
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.remember
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.text.style.TextOverflow
@@ -42,6 +45,12 @@ fun AdminQuarantineScreen(
    viewModel: AdminQuarantineViewModel = hiltViewModel(),
 ) {
    val state by viewModel.uiState.collectAsStateWithLifecycle()
    val snackbarHostState = remember { SnackbarHostState() }
    LaunchedEffect(Unit) {
        viewModel.transientMessages.collect { msg ->
            snackbarHostState.showSnackbar(msg)
        }
    }
    Scaffold(
        contentWindowInsets = ShellContentWindowInsets,
        modifier = Modifier.fillMaxSize(),
@@ -53,6 +62,7 @@ fun AdminQuarantineScreen(
                onBack = { navController.popBackStack() },
            )
        },
        snackbarHost = { SnackbarHost(snackbarHostState) },
    ) { inner ->
        PullToRefreshScaffold(
            onRefresh = { viewModel.refresh().join() },
@@ -74,7 +84,6 @@ fun AdminQuarantineScreen(
                    rows = s.rows,
                    onResolve = viewModel::resolve,
                    onDeleteFile = viewModel::deleteFile,
                    onDeleteViaLidarr = viewModel::deleteViaLidarr,
                )
            }
        }
@@ -86,7 +95,6 @@ private fun QueueList(
    rows: List<AdminQuarantineItemRef>,
    onResolve: (String) -> Unit,
    onDeleteFile: (String) -> Unit,
    onDeleteViaLidarr: (String) -> Unit,
 ) {
    LazyColumn(modifier = Modifier.fillMaxSize()) {
        items(items = rows, key = { it.trackId }) { row ->
@@ -94,7 +102,6 @@ private fun QueueList(
                row = row,
                onResolve = { onResolve(row.trackId) },
                onDeleteFile = { onDeleteFile(row.trackId) },
                onDeleteViaLidarr = { onDeleteViaLidarr(row.trackId) },
            )
            HorizontalDivider()
        }
@@ -106,7 +113,6 @@ private fun QuarantineRow(
    row: AdminQuarantineItemRef,
    onResolve: () -> Unit,
    onDeleteFile: () -> Unit,
    onDeleteViaLidarr: () -> Unit,
 ) {
    Column(
        modifier = Modifier
@@ -155,7 +161,6 @@ private fun QuarantineRow(
        ActionButtons(
            onResolve = onResolve,
            onDeleteFile = onDeleteFile,
            onDeleteViaLidarr = onDeleteViaLidarr,
        )
    }
 }
@@ -164,7 +169,6 @@ private fun QuarantineRow(
 private fun ActionButtons(
    onResolve: () -> Unit,
    onDeleteFile: () -> Unit,
    onDeleteViaLidarr: () -> Unit,
 ) {
    Row(
        modifier = Modifier.fillMaxWidth(),
@@ -172,6 +176,5 @@ private fun ActionButtons(
    ) {
        TextButton(onClick = onResolve) { Text("Resolve") }
        OutlinedButton(onClick = onDeleteFile) { Text("Delete file") }
        Button(onClick = onDeleteViaLidarr) { Text("Delete + Lidarr") }
    }
 }
@@ -10,10 +10,13 @@ import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.AdminQuarantineItemRef
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.channels.Channel
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.receiveAsFlow
 import kotlinx.coroutines.launch
 import javax.inject.Inject
@@ -34,6 +37,15 @@ class AdminQuarantineViewModel @Inject constructor(
    private val internal = MutableStateFlow<AdminQuarantineUiState>(AdminQuarantineUiState.Loading)
    val uiState: StateFlow<AdminQuarantineUiState> = internal.asStateFlow()
    /**
     * One-shot messages for the screen's snackbar. A failed action has to say
     * why: the row quietly reappearing reads as a glitch, and for a Delete
     * file refused by a read-only library it hides the one thing an
     * admin can fix.
     */
    private val transientMessagesChannel = Channel<String>(Channel.BUFFERED)
    val transientMessages: Flow<String> = transientMessagesChannel.receiveAsFlow()
    init {
        refresh()
        viewModelScope.launch {
@@ -41,7 +53,7 @@ class AdminQuarantineViewModel @Inject constructor(
                .filter { it.kind.startsWith("quarantine.") }
                .collect { refresh() }
        }
-        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // Screen-level auto-recovery: reload a failed list
        // when server health returns instead of waiting for a manual pull.
        viewModelScope.launch {
            networkStatus.recoveries().collect {
@@ -70,7 +82,6 @@ class AdminQuarantineViewModel @Inject constructor(
    fun resolve(trackId: String) = act(trackId) { repository.resolve(it) }
    fun deleteFile(trackId: String) = act(trackId) { repository.deleteFile(it) }
    fun deleteViaLidarr(trackId: String) = act(trackId) { repository.deleteViaLidarr(it) }
    private fun act(trackId: String, action: suspend (String) -> Unit) {
        val before = internal.value
@@ -86,8 +97,9 @@ class AdminQuarantineViewModel @Inject constructor(
            try {
                action(trackId)
            } catch (
-                @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
+                @Suppress("TooGenericExceptionCaught") e: Throwable,
            ) {
                transientMessagesChannel.trySend(ErrorCopy.fromThrowable(e))
                refresh()
            }
        }
@@ -61,7 +61,7 @@ fun AdminRequestsScreen(
                AdminRequestsUiState.Loading -> LoadingCentered()
                AdminRequestsUiState.Empty -> EmptyState(
                    title = "No requests waiting",
-                    body = "When users ask Lidarr for new music, their pending " +
+                    body = "When users ask for new music, their pending " +
                        "requests show up here for approval.",
                )
                is AdminRequestsUiState.Error -> ErrorRetry(
@@ -71,7 +71,6 @@ fun AdminRequestsScreen(
                )
                is AdminRequestsUiState.Success -> RequestList(
                    rows = s.rows,
                    usernames = s.usernames,
                    onApprove = viewModel::approve,
                    onReject = viewModel::reject,
                )
@@ -83,7 +82,6 @@ fun AdminRequestsScreen(
@Composable
 private fun RequestList(
    rows: List<RequestRef>,
    usernames: Map<String, String>,
    onApprove: (String) -> Unit,
    onReject: (String) -> Unit,
 ) {
@@ -91,9 +89,9 @@ private fun RequestList(
        items(items = rows, key = { it.id }) { req ->
            AdminRequestRow(
                req = req,
-                requester = usernames[req.userId]
+                requester = req.username.ifEmpty {
-                    ?: req.userId.takeIf { it.isNotEmpty() }?.take(USER_ID_PREFIX_LEN)
+                    req.userId.take(USER_ID_PREFIX_LEN).ifEmpty { "unknown" }
-                    ?: "unknown",
+                },
                onApprove = { onApprove(req.id) },
                onReject = { onReject(req.id) },
            )
@@ -160,6 +158,6 @@ private fun AdminRequestRow(
    }
 }
-// UUID prefix length used as a friendlier-than-raw-UUID fallback when
+// UUID prefix length used as a friendlier-than-raw-UUID fallback when a
-// the admin users list fetch fails and we can't resolve userId → name.
+// row comes back without the requester's username.
 private const val USER_ID_PREFIX_LEN = 8
@@ -3,7 +3,6 @@ package com.fabledsword.minstrel.admin.ui
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.admin.data.AdminRequestsRepository
 import com.fabledsword.minstrel.admin.data.AdminUsersRepository
 import com.fabledsword.minstrel.api.ErrorCopy
 import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.connectivity.recoveries
@@ -11,8 +10,6 @@ import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.RequestRef
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.async
 import kotlinx.coroutines.coroutineScope
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
@@ -25,17 +22,13 @@ private val RELEVANT_EVENT_KINDS = setOf("request.status_changed")
 sealed interface AdminRequestsUiState {
    data object Loading : AdminRequestsUiState
    data object Empty : AdminRequestsUiState
-    data class Success(
+    data class Success(val rows: List<RequestRef>) : AdminRequestsUiState
        val rows: List<RequestRef>,
        val usernames: Map<String, String>,
    ) : AdminRequestsUiState
    data class Error(val message: String) : AdminRequestsUiState
 }
@HiltViewModel
 class AdminRequestsViewModel @Inject constructor(
    private val repository: AdminRequestsRepository,
    private val usersRepository: AdminUsersRepository,
    private val eventsStream: EventsStream,
    networkStatus: NetworkStatusController,
 ) : ViewModel() {
@@ -50,7 +43,7 @@ class AdminRequestsViewModel @Inject constructor(
                .filter { it.kind in RELEVANT_EVENT_KINDS }
                .collect { refresh() }
        }
-        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // Screen-level auto-recovery: reload a failed list
        // when server health returns instead of waiting for a manual pull.
        viewModelScope.launch {
            networkStatus.recoveries().collect {
@@ -62,19 +55,11 @@ class AdminRequestsViewModel @Inject constructor(
    fun refresh(): Job = viewModelScope.launch {
        internal.value = AdminRequestsUiState.Loading
        try {
-            val (rows, usernames) = coroutineScope {
+            val rows = repository.list()
                val requestsJob = async { repository.list() }
                val usernamesJob = async {
                    runCatching {
                        usersRepository.list().associate { it.id to it.username }
                    }.getOrDefault(emptyMap())
                }
                requestsJob.await() to usernamesJob.await()
            }
            internal.value = if (rows.isEmpty()) {
                AdminRequestsUiState.Empty
            } else {
-                AdminRequestsUiState.Success(rows = rows, usernames = usernames)
+                AdminRequestsUiState.Success(rows = rows)
            }
        } catch (
            @Suppress("TooGenericExceptionCaught") e: Throwable,
@@ -101,7 +86,7 @@ class AdminRequestsViewModel @Inject constructor(
            internal.value = if (filtered.isEmpty()) {
                AdminRequestsUiState.Empty
            } else {
-                AdminRequestsUiState.Success(rows = filtered, usernames = before.usernames)
+                AdminRequestsUiState.Success(rows = filtered)
            }
        }
        viewModelScope.launch {
@@ -38,7 +38,7 @@ class AdminTagSourcesViewModel @Inject constructor(
    init {
        refresh()
        // Screen-level auto-recovery: reload a failed list when server
-        // health returns instead of waiting for a manual pull (issue #1245).
+        // health returns instead of waiting for a manual pull.
        viewModelScope.launch {
            networkStatus.recoveries().collect {
                if (internal.value is AdminTagSourcesUiState.Error) refresh()
@@ -33,7 +33,7 @@ class AdminUsersViewModel @Inject constructor(
    init {
        refresh()
-        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // Screen-level auto-recovery: reload a failed list
        // when server health returns instead of waiting for a manual pull.
        viewModelScope.launch {
            networkStatus.recoveries().collect {
@@ -12,18 +12,12 @@ import javax.inject.Singleton
 * flow), and clears the store on 401 so downstream code can react
 * to logout.
 *
 * Mirrors the Flutter Dio interceptor pattern.
 *
 * Scoped to the [BaseUrlInterceptor.PLACEHOLDER_HOST] sentinel host
- * the same way BaseUrlInterceptor is. Drift #568 / #569 caught two
+ * the same way BaseUrlInterceptor is. The shared OkHttpClient also
- * leaks here: (1) the session cookie was being attached to every
+ * serves Coil's image fetches to external hosts such as
- * external request the shared OkHttpClient services — including
+ * artwork.musicbrainz.org and coverartarchive.org; unscoped, this
- * Coil image fetches to artwork.musicbrainz.org / coverartarchive.org
+ * would hand the session identifier to third-party logging, and a 401
- * / Lidarr's /MediaCover endpoints — exposing the session
+ * from any of those hosts would sign the user out of Minstrel.
 * identifier to third-party logging; (2) a 401 from any of those
 * external hosts silently wiped the user's Minstrel session.
 * Restricting both attach + clear to placeholder-host requests
 * closes both gaps.
 */
@Singleton
 class AuthCookieInterceptor @Inject constructor(
@@ -17,15 +17,14 @@ import javax.inject.Singleton
 *
 * This interceptor closes the gap: Retrofit can stay built with the
 * placeholder forever, and every actual Minstrel-bound request gets
- * retargeted at the live AuthStore value. Lets the user change
+ * retargeted at the live AuthStore value, so the user can change the
- * server URL in Settings without an app relaunch (Phase 11 wiring).
+ * server URL in Settings without an app relaunch.
 *
 * Only requests whose host is the [PLACEHOLDER_HOST] sentinel are
- * rewritten. Absolute external URLs — Lidarr-surfaced artwork from
+ * rewritten. Absolute external URLs — artwork from
 * artwork.musicbrainz.org / coverartarchive.org, for example — must
- * reach their authored host unchanged; rewriting them to the
+ * reach their authored host unchanged: rewritten to the Minstrel host
- * Minstrel host produced 404s the user saw as missing Discover
+ * they 404, and Discover suggestions show no covers.
 * suggestion covers.
 *
 * No-op when the stored base URL is unparseable (falls through to
 * whatever Retrofit had) — that case shows up as a transport-level
@@ -50,7 +49,14 @@ class BaseUrlInterceptor @Inject constructor(
                .port(baseUrl.port)
                .build()
        } ?: original.url
-        return chain.proceed(original.newBuilder().url(rewritten).build())
+        return chain.proceed(
            original.newBuilder()
                .url(rewritten)
                // Lets CleartextGuardInterceptor tell server requests from
                // external fetches once the placeholder host is gone.
                .tag(MinstrelServerRequest::class.java, MinstrelServerRequest)
                .build(),
        )
    }
    companion object {
@@ -0,0 +1,83 @@
 package com.fabledsword.minstrel.api
 import okhttp3.Interceptor
 import okhttp3.Response
 import java.io.IOException
 import java.net.Inet4Address
 import java.net.Inet6Address
 import java.net.InetAddress
 /**
 * Marks a request as bound for the Minstrel server, set by
 * [BaseUrlInterceptor] when it retargets the placeholder host. Those are the
 * requests that carry the session cookie and the password.
 */
 object MinstrelServerRequest
 /**
 * Plain `http://` to the Minstrel server is allowed only when the connection
 * actually lands on a private address.
 *
 * Cleartext stays permitted app-wide for LAN servers and UPnP
 * (network_security_config.xml), but a password or session cookie sent
 * over plain HTTP to a public address can be read by anyone on the path.
 *
 * Checked per connection, on the address the socket really reached, not on
 * the URL when it was typed: a name that resolved to the home network when it
 * was entered resolves to a public address once the phone leaves home, and
 * that is exactly when the password would go out in the clear. A network
 * interceptor runs after the connection is made and before any request byte
 * is written, so nothing is sent.
 */
 class CleartextGuardInterceptor(
    // The policy is a parameter so a test can refuse loopback, the only
    // address a test server can listen on.
    private val allows: (InetAddress) -> Boolean = CleartextPolicy::allows,
 ) : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        if (request.isHttps || request.tag(MinstrelServerRequest::class.java) == null) {
            return chain.proceed(request)
        }
        val address = chain.connection()?.route()?.socketAddress?.address
        if (address != null && !allows(address)) {
            throw CleartextToPublicHostException(request.url.host)
        }
        return chain.proceed(request)
    }
 }
 /** The server was reached over plain HTTP at a public address, and refused. */
 class CleartextToPublicHostException(host: String) :
    IOException("refusing plain http:// to $host: it is a public address")
 /** Which addresses plain HTTP may reach: the home network, never the internet. */
 object CleartextPolicy {
    private const val CGNAT_FIRST_OCTET = 100
    private const val CGNAT_SECOND_MASK = 0xC0
    private const val CGNAT_SECOND_PREFIX = 64
    private const val ULA_MASK = 0xFE
    private const val ULA_PREFIX = 0xFC
    private const val BYTE = 0xFF
    fun allows(address: InetAddress): Boolean =
        address.isLoopbackAddress ||
            address.isSiteLocalAddress || // 10/8, 172.16/12, 192.168/16
            address.isLinkLocalAddress || // 169.254/16, fe80::/10
            address.isAnyLocalAddress ||
            isCarrierGradeNat(address) ||
            isUniqueLocal(address)
    // 100.64/10. Tailscale and other overlay VPNs hand these out; the overlay
    // encrypts the traffic itself.
    private fun isCarrierGradeNat(address: InetAddress): Boolean {
        if (address !is Inet4Address) return false
        val b = address.address
        return (b[0].toInt() and BYTE) == CGNAT_FIRST_OCTET &&
            (b[1].toInt() and CGNAT_SECOND_MASK) == CGNAT_SECOND_PREFIX
    }
    // fc00::/7, IPv6's private range.
    private fun isUniqueLocal(address: InetAddress): Boolean =
        address is Inet6Address && (address.address[0].toInt() and ULA_MASK) == ULA_PREFIX
 }
@@ -37,18 +37,36 @@ object ErrorCopy {
     * as connection failures.
     */
    fun fromThrowable(t: Throwable): String = when (t) {
-        is HttpException -> messageFor(codeFromHttp(t))
+        is HttpException -> fromHttp(t)
        is CleartextToPublicHostException -> messageFor("cleartext_public")
        is IOException -> messageFor("connection_refused")
        else -> TABLE.getValue("unknown")
    }
-    private fun codeFromHttp(e: HttpException): String {
+    /**
     * Codes whose server message carries specifics an admin needs in
     * order to act — which directory, which uid — that fixed copy cannot say.
     * For these the message follows the copy. Kept to a named set on
     * purpose: most server messages are internal detail. Mirrors web's
     * errors.ts.
     */
    private val DETAIL_CODES = setOf("library_not_writable", "file_delete_failed")
    private fun fromHttp(e: HttpException): String {
        val body = bodyFromHttp(e)
        val copy = messageFor(body.code.ifEmpty { "unknown" })
        return if (body.code in DETAIL_CODES && body.message.isNotBlank()) {
            "$copy ${body.message}"
        } else {
            copy
        }
    }
    private fun bodyFromHttp(e: HttpException): Body {
        val raw = runCatching { e.response()?.errorBody()?.string() }.getOrNull()
-            ?: return "unknown"
+            ?: return Body()
-        val code = runCatching { json.decodeFromString<Envelope>(raw).error?.code }
+        return runCatching { json.decodeFromString<Envelope>(raw).error }
-            .getOrNull()
+            .getOrNull() ?: Body()
            .orEmpty()
        return code.ifEmpty { "unknown" }
    }
    private val TABLE: Map<String, String> = mapOf(
@@ -58,6 +76,7 @@ object ErrorCopy {
        "forbidden" to "You don't have permission to do that.",
        "not_authorized" to "You don't have permission to do that.",
        "invalid_credentials" to "Wrong username or password.",
        "rate_limited" to "Too many attempts. Wait a few minutes and try again.",
        "wrong_password" to "Current password is incorrect.",
        "password_too_short" to "Password must be at least 8 characters.",
        "username_invalid" to "That username isn't valid.",
@@ -83,22 +102,16 @@ object ErrorCopy {
        "mbid_required" to "An MBID is required for this lookup.",
        "system_playlist_readonly" to "System playlists can't be edited directly.",
        "connection_refused" to "Couldn't reach the server. Check the URL and try again.",
-        "lidarr_unreachable" to
+        "cleartext_public" to
-            "Lidarr is unreachable right now. Try again, or check Admin → Integrations.",
+            "This server is on the internet, so its URL must start with https://. " +
-        "lidarr_disabled" to "Lidarr integration is not enabled.",
+            "Plain http:// only works on your home network.",
        "lidarr_auth_failed" to "Lidarr authentication failed.",
        "lidarr_defaults_incomplete" to
            "Lidarr is missing a default quality profile or root folder. " +
            "Set them in Admin → Integrations.",
        "lidarr_server_error" to "Lidarr returned an error. Check Lidarr's logs for the cause.",
        "lidarr_rejected" to
            "Lidarr rejected the request. Check the server logs for the field-level reason.",
        "lidarr_album_lookup_failed" to
            "Lidarr doesn't recognize this album. Try Resolve or Delete file instead.",
        "album_mbid_missing" to "This track has no Lidarr album to remove.",
        "request_not_pending" to "This request is no longer pending.",
        "request_not_found" to "That request no longer exists.",
        "not_followable" to "Various Artists and MusicBrainz placeholders can't be followed.",
        "profile_not_found" to "That release-type profile no longer exists.",
        "track_not_found" to "That track no longer exists.",
        "library_not_writable" to "The music library isn't writable by the server.",
        "file_delete_failed" to "The file couldn't be deleted.",
        "album_not_found" to "That album no longer exists.",
        "artist_not_found" to "That artist no longer exists.",
        "playlist_not_found" to "That playlist no longer exists.",
@@ -57,19 +57,21 @@ object NetworkModule {
            .addInterceptor(reachability)
            // AuthCookieInterceptor MUST run before BaseUrlInterceptor.
            // Both scope on `host == PLACEHOLDER_HOST` to distinguish
-            // Minstrel-server requests from external image fetches
+            // Minstrel-server requests from external image fetches. If
-            // (drift #568 / #569). If BaseUrlInterceptor runs first it
+            // BaseUrlInterceptor runs first it rewrites the host to the real
-            // rewrites the host to the real server before auth sees the
+            // server before auth sees the request, auth's placeholder check
-            // request, auth's placeholder check fails, and the session
+            // fails, and the session cookie is neither attached on outgoing
-            // cookie is neither attached on outgoing requests nor
+            // requests nor captured from Set-Cookie on login — fresh installs
-            // captured from Set-Cookie on login — fresh installs get
+            // get stuck at the Welcome screen. Auth first means it sees
            // stuck at the Welcome screen. Auth first means it sees
            // placeholder.invalid, attaches/captures correctly, then
-            // BaseUrlInterceptor retargets to the live AuthStore host
+            // BaseUrlInterceptor retargets to the live AuthStore host for
-            // for transport.
+            // transport.
            .addInterceptor(auth)
            .addInterceptor(baseUrl)
            .addInterceptor(logging)
            // A network interceptor, so it sees the address the connection
            // really reached and runs before any request byte is written.
            .addNetworkInterceptor(CleartextGuardInterceptor())
            .connectTimeout(CONNECT_TIMEOUT_SECONDS, TimeUnit.SECONDS)
            .readTimeout(READ_TIMEOUT_SECONDS, TimeUnit.SECONDS)
            .build()
@@ -27,9 +27,8 @@ interface AdminInvitesApi {
 }
 /**
- * Body for `POST /api/admin/invites`. The Flutter client omits the
+ * Body for `POST /api/admin/invites`. An empty note is sent as null,
- * field when note is empty; Kotlin/serialization just serializes
+ * which the server treats the same as an absent field.
 * null which the server treats identically.
 */
@Serializable
 data class CreateInviteBody(val note: String? = null)
@@ -8,10 +8,9 @@ import retrofit2.http.Path
 /**
 * Retrofit interface for `/api/admin/quarantine`.
 *
- * Three resolution endpoints:
+ * Two resolution endpoints:
- *   - `resolve`        → admin reviewed, no action taken (clears flags).
+ *   - `resolve`     → admin reviewed, no action taken (clears flags).
- *   - `delete-file`    → drop the local file; Lidarr keeps the track.
+ *   - `delete-file` → delete the track's file and row.
 *   - `delete-via-lidarr` → ask Lidarr to remove the track upstream too.
 */
 interface AdminQuarantineApi {
    @GET("api/admin/quarantine")
@@ -22,7 +21,4 @@ interface AdminQuarantineApi {
    @POST("api/admin/quarantine/{trackId}/delete-file")
    suspend fun deleteFile(@Path("trackId") trackId: String)
    @POST("api/admin/quarantine/{trackId}/delete-via-lidarr")
    suspend fun deleteViaLidarr(@Path("trackId") trackId: String)
 }
@@ -12,9 +12,9 @@ import retrofit2.http.POST
 import retrofit2.http.Path
 /**
- * Retrofit interface for `/api/admin/tag-sources` (#1521) — the admin
+ * Retrofit interface for `/api/admin/tag-sources` — the admin surface
- * surface for the tag-enrichment provider settings (#1490). Mirrors the
+ * for the tag-enrichment provider settings. Mirrors the web
- * web integrations "Tag enrichment sources" card. Same shape as the
+ * integrations "Tag enrichment sources" card. Same shape as the
 * cover-sources admin surface; kept independent so a new tag source is
 * added without touching art settings.
 */
@@ -29,11 +29,20 @@ interface CastApi {
 * Request body. [expSeconds] is clamped server-side to [60, 86400];
 * the 21_600 default (6h) is long enough to play through any typical
 * track without re-minting mid-playback.
 *
 * [level] asks for the leveled stream: the track rendered at
 * the user's loudness gain, which the server works out from their setting.
 * [asAlbum] says the track plays among its album in order, which picks
 * album gain in auto mode. [prerender] says the speaker will fetch it
 * soon, so the server renders it ahead.
 */
@Serializable
 data class StreamTokenRequest(
    val trackId: String,
    val expSeconds: Int = 21_600,
    val level: Boolean = false,
    val asAlbum: Boolean = false,
    val prerender: Boolean = false,
 )
 /**
@@ -53,4 +62,6 @@ data class StreamTokenResponse(
    val url: String,
    val mime: String = "audio/mpeg",
    val title: String = "",
    /** [url] is the leveled stream; false when leveling is off or changes nothing. */
    val leveled: Boolean = false,
 )
@@ -7,7 +7,7 @@ import retrofit2.http.Body
 import retrofit2.http.POST
 /**
- * Retrofit interface for device diagnostics ingest (M9). One call
+ * Retrofit interface for device diagnostics ingest. One call
 * uploads a batch of buffered events. The server stores them only when
 * the account's debug_mode_enabled flag is on (it returns 204 otherwise,
 * which the uploader treats as success so it can drop the batch).
@@ -2,7 +2,7 @@ package com.fabledsword.minstrel.api.endpoints
 import com.fabledsword.minstrel.models.wire.ArtistSuggestionWire
 import com.fabledsword.minstrel.models.wire.CreateRequestBody
-import com.fabledsword.minstrel.models.wire.LidarrSearchResultWire
+import com.fabledsword.minstrel.models.wire.CatalogueSearchResultWire
 import com.fabledsword.minstrel.models.wire.SnoozeSuggestionBody
 import com.fabledsword.minstrel.models.wire.SuggestionSnoozeWire
 import retrofit2.http.Body
@@ -13,23 +13,23 @@ import retrofit2.http.Path
 import retrofit2.http.Query
 /**
- * Retrofit interface for Discover / Lidarr search / request creation.
+ * Retrofit interface for Discover / catalogue search / request creation.
 *
- * `/api/lidarr/search` has a 60s LRU on the server so quick re-types
+ * `/api/catalogue/search` asks MusicBrainz, which allows one request a
- * of the same query are cheap.
+ * second, so the Discover screen searches when the query is submitted,
 * not on every keystroke.
 *
- * Cancel + my-requests-list endpoints live on RequestsApi (Phase 10
+ * Cancel + my-requests-list endpoints live on RequestsApi, not here.
 * Commit B), not here.
 */
 interface DiscoverApi {
    @GET("api/discover/suggestions")
    suspend fun listSuggestions(): List<ArtistSuggestionWire>
-    @GET("api/lidarr/search")
+    @GET("api/catalogue/search")
    suspend fun search(
        @Query("q") query: String,
        @Query("kind") kind: String,
-    ): List<LidarrSearchResultWire>
+    ): List<CatalogueSearchResultWire>
    @POST("api/requests")
    suspend fun createRequest(@Body body: CreateRequestBody)
@@ -56,16 +56,15 @@ interface LibraryApi {
    @GET("api/library/shuffle")
    suspend fun shuffleLibrary(@Query("limit") limit: Int = 100): List<TrackWire>
-    // Browse axes (#367). Both indexes are unpaged by design: the client needs
+    // Browse axes. Both indexes are unpaged by design: the client needs
    // the whole set to render a browsable picker, and even a messy library
    // yields hundreds of rows, not thousands.
    //
-    // These read the server rather than the local cache on purpose. The cache
+    // These read the server rather than the local cache on purpose: the
-    // is a full mirror of the library, but /api/library/sync ships tracks whose
+    // server's index leaves out tracks whose files are missing and is the
-    // files are missing and carries no flag for it (#2704), while the browse
+    // one the web client shows, so the two clients agree. The cache carries
-    // index filters them out -- so a locally-computed index would disagree with
+    // the same mark (cached_tracks.missing), but an index built from it
-    // the server's and with the web client. One source of truth wins over
+    // would be a second copy of the server's grouping that could drift.
    // offline capability here until #2704 is resolved.
    @GET("api/library/genres")
    suspend fun getGenres(): List<GenreCountWire>
@@ -3,6 +3,7 @@ package com.fabledsword.minstrel.api.endpoints
 import com.fabledsword.minstrel.models.wire.ListenBrainzStatusWire
 import com.fabledsword.minstrel.models.wire.MyProfileWire
 import com.fabledsword.minstrel.models.wire.SystemPlaylistsStatusWire
 import com.fabledsword.minstrel.settings.data.NormalizationPrefs
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import retrofit2.http.Body
@@ -59,6 +60,14 @@ interface MeApi {
     */
    @PUT("api/me/listenbrainz")
    suspend fun setListenBrainz(@Body body: ListenBrainzPutBody): ListenBrainzStatusWire
    /** The caller's loudness-normalization preference, or the defaults if never set. */
    @GET("api/me/normalization")
    suspend fun getNormalization(): NormalizationPrefs
    /** Replaces the whole preference; returns what the server stored. */
    @PUT("api/me/normalization")
    suspend fun putNormalization(@Body body: NormalizationPrefs): NormalizationPrefs
 }
 /**
@@ -83,9 +92,7 @@ data class ChangePasswordRequest(
 /**
 * Body for `PUT /api/me/listenbrainz`. Either `token` or `enabled`
- * is set; the server treats other fields as untouched. Mirrors
+ * is set; the server treats other fields as untouched.
 * Flutter's `setListenBrainzToken` / `setListenBrainzEnabled` split
 * over a single endpoint shape.
 */
@Serializable
 data class ListenBrainzPutBody(
@@ -0,0 +1,90 @@
 package com.fabledsword.minstrel.api.endpoints
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import retrofit2.http.Body
 import retrofit2.http.GET
 import retrofit2.http.POST
 import retrofit2.http.PUT
 import retrofit2.http.Path
 import retrofit2.http.Query
 /**
 * The notifications inbox and its per-user settings. The server
 * renders each notice's title, body and link, so the app shows them as given.
 */
 interface NotificationsApi {
    @GET("api/me/notifications")
    suspend fun list(@Query("limit") limit: Int): NotificationsPageWire
    /** 204; 404 when the notice is gone, which a replay treats as done. */
    @POST("api/me/notifications/{id}/read")
    suspend fun markRead(@Path("id") id: String)
    @POST("api/me/notifications/read-all")
    suspend fun readAll(@Body body: ReadAllBody)
    @GET("api/me/notification-settings")
    suspend fun getSettings(): NotificationSettingsWire
    @PUT("api/me/notification-settings")
    suspend fun putSettings(@Body body: PutNotificationSettingsBody): NotificationSettingsWire
 }
@Serializable
 data class NotificationWire(
    val id: String,
    val kind: String,
    val title: String,
    val body: String,
    val link: String,
    @SerialName("created_at") val createdAt: String,
    @SerialName("read_at") val readAt: String? = null,
 )
@Serializable
 data class NotificationsPageWire(
    val items: List<NotificationWire>,
    @SerialName("unread_count") val unreadCount: Long,
    @SerialName("next_before") val nextBefore: String? = null,
 )
 /**
 * `upTo` limits "mark all read" to what existed when the user asked, so a
 * replay landing later leaves newer notices unread. No default on purpose:
 * the app's Json drops default-valued fields.
 */
@Serializable
 data class ReadAllBody(@SerialName("up_to") val upTo: String?)
@Serializable
 data class NotificationKindSettingWire(
    val kind: String,
    @SerialName("admin_only") val adminOnly: Boolean,
    val inbox: Boolean,
    val phone: Boolean,
    val email: Boolean,
 )
@Serializable
 data class NotificationSettingsWire(
    val kinds: List<NotificationKindSettingWire>,
    @SerialName("email_available") val emailAvailable: Boolean,
    @SerialName("email_unavailable_reason") val emailUnavailableReason: String? = null,
 )
 /**
 * One kind's change. Untouched channels stay null and, being equal to their
 * default, are left out of the JSON, so the server changes only the channel
 * the user touched.
 */
@Serializable
 data class NotificationSettingChangeWire(
    val kind: String,
    val inbox: Boolean? = null,
    val phone: Boolean? = null,
    val email: Boolean? = null,
 )
@Serializable
 data class PutNotificationSettingsBody(val kinds: List<NotificationSettingChangeWire>)
@@ -49,7 +49,7 @@ interface PlaylistsApi {
    suspend fun refreshSystem(@Path("kind") variant: String): RefreshSystemResponse
    /**
-     * GET /api/playlists/system/{kind}/shuffle (#415 / #411 R2). Returns
+     * GET /api/playlists/system/{kind}/shuffle. Returns
     * the system playlist's tracks in rotation-aware order without
     * rebuilding — used by the Home play-button overlay so taps on For
     * You / Discover / Today's mix advance rotation rather than picking
@@ -60,8 +60,8 @@ interface PlaylistsApi {
 }
 /**
- * POST /api/playlists/{id}/tracks body. Server expects snake_case
+ * POST /api/playlists/{id}/tracks body. The server expects snake_case
- * `track_ids` per the Flutter wire shape.
+ * `track_ids`.
 */
@Serializable
 data class AppendTracksRequest(
@@ -13,7 +13,7 @@ import retrofit2.http.Path
 *
 * Both flag and unflag are user-scoped — callers act on their own
 * quarantine entries. The cross-user admin surface is a separate
- * `/api/admin/quarantine` route (Phase 10 Commit D).
+ * `/api/admin/quarantine` route.
 */
 interface QuarantineApi {
    @GET("api/quarantine/mine")
@@ -0,0 +1,15 @@
 package com.fabledsword.minstrel.api.endpoints
 import com.fabledsword.minstrel.models.wire.ReplayGainResponseWire
 import retrofit2.http.GET
 import retrofit2.http.Query
 /** The player's loudness lookup, kept apart from the browse surface in [LibraryApi]. */
 interface ReplayGainApi {
    /**
     * ReplayGain values for up to 200 comma-separated track ids. An id
     * missing from `items` has not been measured yet.
     */
    @GET("api/tracks/replay-gain")
    suspend fun getReplayGain(@Query("ids") ids: String): ReplayGainResponseWire
 }
@@ -10,7 +10,7 @@ import retrofit2.http.Path
 *
 * Server scopes results to the caller — admins see only their own
 * requests through this endpoint. The cross-user admin view lives on
- * a separate `/api/admin/requests` route (Phase 10 Commit D).
+ * a separate `/api/admin/requests` route.
 *
 * The DELETE endpoint returns the cancelled row (not 204) so the UI
 * can patch local state without a refetch.
@@ -6,7 +6,7 @@ import retrofit2.http.GET
 import retrofit2.http.Query
 /**
- * Retrofit interface for `/api/library/sync` (#357). The endpoint
+ * Retrofit interface for `/api/library/sync`. The endpoint
 * returns three possible status codes that the SyncController
 * branches on:
 *   - 200: parsed body with cursor + upserts + deletes
@@ -57,7 +57,7 @@ class AuthController @Inject constructor(
            }
        }
        // Refresh from /api/me on startup so a remotely-changed account
-        // flag (e.g. admin enabling debug mode, M9) reaches the device
+        // flag (e.g. an admin enabling debug mode) reaches the device
        // without a re-login. Best-effort; failures keep the cached value.
        scope.launch { refreshProfile() }
    }
@@ -4,12 +4,19 @@ import com.fabledsword.minstrel.cache.audiocache.CacheSettings
 import com.fabledsword.minstrel.cache.db.dao.AuthSessionDao
 import com.fabledsword.minstrel.cache.db.entities.AuthSessionEntity
 import com.fabledsword.minstrel.di.ApplicationScope
 import com.fabledsword.minstrel.settings.data.NormalizationPrefs
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Deferred
 import kotlinx.coroutines.async
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withTimeoutOrNull
 import kotlinx.serialization.json.Json
 import timber.log.Timber
 import javax.inject.Inject
 import javax.inject.Singleton
@@ -27,6 +34,14 @@ import javax.inject.Singleton
 * in-memory state changes synchronously so the next interceptor read
 * sees the new value immediately; the DAO write coroutine catches up
 * shortly after.
 *
 * **The session cookie is the exception**: it is persisted through
 * [SessionVault] (Keystore-encrypted), not the Room row. A cookie still
 * in the row is moved into the vault on launch and the column cleared,
 * so nobody is signed out by the move. If the Keystore cannot be used
 * on a device, the cookie stays in the row rather than being lost.
 * [awaitSessionHydrated] lets a caller that needs a definitive answer
 * (the auth gate) wait for this.
 */
 // AuthStore is the single-row facade over auth_session (de-facto
 // app_preferences — see entity comment). It legitimately owns one
@@ -39,6 +54,7 @@ import javax.inject.Singleton
@Singleton
 class AuthStore @Inject constructor(
    private val dao: AuthSessionDao,
    private val vault: SessionVault,
    @ApplicationScope private val scope: CoroutineScope,
 ) {
    private val sessionCookieState = MutableStateFlow<String?>(null)
@@ -62,18 +78,39 @@ class AuthStore @Inject constructor(
    private val diagnosticsOptOutState = MutableStateFlow(false)
    val diagnosticsOptOut: StateFlow<Boolean> = diagnosticsOptOutState.asStateFlow()
    private val normalizationState = MutableStateFlow(NormalizationPrefs.DEFAULT)
    val normalization: StateFlow<NormalizationPrefs> = normalizationState.asStateFlow()
    // Background delivery: the device's choice, on by default.
    // The shade's high-water mark lives in the same row but is read and
    // written through the DAO by NotificationSync, awaited, never cached here.
    private val backgroundDeliveryState = MutableStateFlow(true)
    val backgroundDelivery: StateFlow<Boolean> = backgroundDeliveryState.asStateFlow()
    private val json = Json { ignoreUnknownKeys = true }
    // Serialises every cookie persist with the one-time hydration, so a
    // sign-in or a 401 that lands while hydration runs is never overwritten
    // by the stale value hydration read.
    private val cookieLock = Mutex()
    // Set by setSessionCookie. Once something has written the cookie this
    // process, that value wins over whatever hydration finds on disk.
    @Volatile private var cookieTouched = false
    private val cookieHydration: Deferred<Unit> = scope.async { hydrateSessionCookie() }
    init {
        scope.launch {
            dao.observe().collect { row ->
                sessionCookieState.value = row?.sessionCookie
                baseUrlState.value = row?.baseUrl ?: DEFAULT_BASE_URL
                userJsonState.value = row?.userJson
                themeModeState.value = row?.themeMode
                clientIdState.value = row?.clientId
                cacheSettingsState.value = decodeCacheSettings(row?.cacheSettingsJson)
                diagnosticsOptOutState.value = row?.diagnosticsOptOut ?: false
                normalizationState.value = decodeNormalization(row?.normalizationJson)
                backgroundDeliveryState.value = row?.backgroundDelivery ?: true
            }
        }
    }
@@ -85,9 +122,57 @@ class AuthStore @Inject constructor(
        }.getOrDefault(CacheSettings.DEFAULT)
    }
    private fun decodeNormalization(raw: String?): NormalizationPrefs {
        if (raw.isNullOrEmpty()) return NormalizationPrefs.DEFAULT
        return runCatching {
            json.decodeFromString(NormalizationPrefs.serializer(), raw)
        }.getOrDefault(NormalizationPrefs.DEFAULT)
    }
    /**
     * Suspends until the stored session cookie has been loaded into
     * [sessionCookie], or [HYDRATION_DEADLINE_MS] passes, so a wedged
     * Keystore cannot leave the start screen spinning. Returns false on
     * the deadline; the caller then decides from whatever has loaded, and a
     * late hydration still lands in [sessionCookie].
     */
    suspend fun awaitSessionHydrated(): Boolean {
        val done = withTimeoutOrNull(HYDRATION_DEADLINE_MS) { cookieHydration.await() } != null
        if (!done) Timber.w("auth store: session hydration passed its deadline; deciding without it")
        return done
    }
    fun setSessionCookie(value: String?) {
        cookieTouched = true
        sessionCookieState.value = value
-        scope.launch { persistCookie(value) }
+        scope.launch { cookieLock.withLock { storeCookie(value) } }
    }
    private suspend fun hydrateSessionCookie() = cookieLock.withLock {
        val legacy = runCatching { dao.get()?.sessionCookie }.getOrNull()
        if (cookieTouched) return@withLock
        // A cookie in the row is the newer one when both exist: the row is
        // only written when the vault failed, and an install upgrading from
        // before the vault has nothing in the vault yet.
        val cookie = legacy ?: vault.read()
        // Best-effort: if moving it fails, the session still loads this time
        // and the move is retried on the next launch. Hydration must never
        // throw, or awaitSessionHydrated would leave the auth gate stuck.
        if (legacy != null) {
            runCatching { storeCookie(legacy) }
                .onFailure { Timber.w(it, "auth store: could not move the session cookie into the vault") }
        }
        sessionCookieState.value = cookie
    }
    // Vault first; the Room row only when the Keystore is unusable, so a
    // broken Keystore degrades to the old storage rather than a sign-out.
    private suspend fun storeCookie(value: String?) {
        if (vault.write(value)) {
            if (dao.get()?.sessionCookie != null) dao.setSessionCookie(null)
        } else {
            persistLegacyCookie(value)
        }
    }
    fun setBaseUrl(value: String) {
@@ -121,7 +206,24 @@ class AuthStore @Inject constructor(
        scope.launch { persistDiagnosticsOptOut(value) }
    }
-    private suspend fun persistCookie(value: String?) {
+    fun setNormalization(value: NormalizationPrefs) {
        normalizationState.value = value
        val encoded = json.encodeToString(NormalizationPrefs.serializer(), value)
        scope.launch { persistNormalization(encoded) }
    }
    fun setBackgroundDelivery(value: Boolean) {
        backgroundDeliveryState.value = value
        scope.launch {
            if (dao.get() == null) {
                dao.upsert(currentEntity().copy(backgroundDelivery = value))
            } else {
                dao.setBackgroundDelivery(value)
            }
        }
    }
    private suspend fun persistLegacyCookie(value: String?) {
        if (dao.get() == null) {
            dao.upsert(currentEntity().copy(sessionCookie = value))
        } else {
@@ -177,9 +279,19 @@ class AuthStore @Inject constructor(
        }
    }
    private suspend fun persistNormalization(json: String) {
        if (dao.get() == null) {
            dao.upsert(currentEntity().copy(normalizationJson = json))
        } else {
            dao.setNormalizationJson(json)
        }
    }
    private fun currentEntity(): AuthSessionEntity = AuthSessionEntity(
        id = ROW_ID,
-        sessionCookie = sessionCookieState.value,
+        // Never copied into the row: the cookie lives in the vault, and
        // persistLegacyCookie sets it explicitly on the fallback path.
        sessionCookie = null,
        baseUrl = baseUrlState.value,
        userJson = userJsonState.value,
        themeMode = themeModeState.value,
@@ -189,10 +301,19 @@ class AuthStore @Inject constructor(
            cacheSettingsState.value,
        ),
        diagnosticsOptOut = diagnosticsOptOutState.value,
        normalizationJson = json.encodeToString(
            NormalizationPrefs.serializer(),
            normalizationState.value,
        ),
        backgroundDelivery = backgroundDeliveryState.value,
    )
    companion object {
        const val DEFAULT_BASE_URL: String = "http://localhost:8080"
        // Generous on purpose: hydration is one local row read and one
        // Keystore decrypt, normally milliseconds. This only bounds "never".
        const val HYDRATION_DEADLINE_MS: Long = 10_000
        private const val ROW_ID = 0
    }
 }
@@ -0,0 +1,146 @@
 package com.fabledsword.minstrel.auth
 import android.content.Context
 import android.security.keystore.KeyGenParameterSpec
 import android.security.keystore.KeyProperties
 import dagger.Binds
 import dagger.Module
 import dagger.hilt.InstallIn
 import dagger.hilt.android.qualifiers.ApplicationContext
 import dagger.hilt.components.SingletonComponent
 import timber.log.Timber
 import java.security.KeyStore
 import java.util.Base64
 import javax.crypto.Cipher
 import javax.crypto.KeyGenerator
 import javax.crypto.SecretKey
 import javax.crypto.spec.GCMParameterSpec
 import javax.inject.Inject
 import javax.inject.Singleton
 /**
 * Where the session cookie lives at rest.
 *
 * The cookie is a bearer credential: anyone holding it is signed in as the
 * user until the server expires or revokes it. In plain text it would be
 * readable from any copy of the app's data directory (a rooted device, an
 * adb backup of a debuggable build, a forensic image). Only ciphertext is
 * stored, under an AES key that lives in the Android Keystore and never
 * leaves it, so a copy of the files alone yields nothing usable.
 */
 interface SessionVault {
    /** The stored cookie, or null when none is stored or it can't be decrypted. */
    fun read(): String?
    /**
     * Stores [value], or clears the stored cookie when null. Returns false
     * when the Keystore could not be used, so the caller can fall back
     * rather than lose the session.
     */
    fun write(value: String?): Boolean
 }
 /**
 * AES-GCM sealing of a short string, framed as base64(iv || ciphertext+tag).
 * Kept apart from the Keystore so the framing can be unit-tested on the JVM
 * with an ordinary key; the Android Keystore has no JVM implementation.
 */
 internal object SealedBox {
    private const val TRANSFORMATION = "AES/GCM/NoPadding"
    private const val TAG_BITS = 128
    private const val IV_BYTES = 12
    // Binds a sealed value to its purpose: a blob sealed for something else
    // under the same key will not open as a session cookie.
    private val AAD = "minstrel-session-cookie-v1".toByteArray(Charsets.UTF_8)
    fun seal(key: SecretKey, plaintext: String): String {
        val cipher = Cipher.getInstance(TRANSFORMATION)
        // No IV passed: the provider generates a fresh random one. Keystore
        // keys refuse a caller-chosen IV for encryption by default.
        cipher.init(Cipher.ENCRYPT_MODE, key)
        cipher.updateAAD(AAD)
        val sealed = cipher.iv + cipher.doFinal(plaintext.toByteArray(Charsets.UTF_8))
        return Base64.getEncoder().encodeToString(sealed)
    }
    fun open(key: SecretKey, sealed: String): String {
        val bytes = Base64.getDecoder().decode(sealed)
        require(bytes.size > IV_BYTES) { "sealed value too short" }
        val cipher = Cipher.getInstance(TRANSFORMATION)
        cipher.init(Cipher.DECRYPT_MODE, key, GCMParameterSpec(TAG_BITS, bytes, 0, IV_BYTES))
        cipher.updateAAD(AAD)
        return String(cipher.doFinal(bytes, IV_BYTES, bytes.size - IV_BYTES), Charsets.UTF_8)
    }
 }
 /**
 * [SessionVault] backed by a Keystore AES key and a private prefs file that
 * holds only the sealed value.
 *
 * A value that will not open (the key was wiped by a factory-reset of the
 * Keystore, or the file was restored onto another device; app backup is off,
 * but a vendor transfer tool may still copy files) is discarded and reported
 * as absent. The user signs in again, which is the right outcome for a
 * credential that no longer verifies.
 */
@Singleton
 class KeystoreSessionVault @Inject constructor(
    @ApplicationContext context: Context,
 ) : SessionVault {
    private val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
    override fun read(): String? {
        val sealed = prefs.getString(KEY_COOKIE, null) ?: return null
        return runCatching { SealedBox.open(key(), sealed) }
            .onFailure {
                Timber.w(it, "session vault: stored cookie would not decrypt; discarding it")
                prefs.edit().remove(KEY_COOKIE).commit()
            }
            .getOrNull()
    }
    override fun write(value: String?): Boolean = runCatching {
        val editor = prefs.edit()
        if (value == null) {
            editor.remove(KEY_COOKIE)
        } else {
            editor.putString(KEY_COOKIE, SealedBox.seal(key(), value))
        }
        editor.commit()
    }.onFailure {
        Timber.w(it, "session vault: Keystore unavailable; cookie not stored in the vault")
    }.getOrDefault(false)
    private fun key(): SecretKey {
        val keyStore = KeyStore.getInstance(ANDROID_KEYSTORE).apply { load(null) }
        (keyStore.getKey(KEY_ALIAS, null) as? SecretKey)?.let { return it }
        val generator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, ANDROID_KEYSTORE)
        generator.init(
            KeyGenParameterSpec.Builder(
                KEY_ALIAS,
                KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT,
            )
                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
                .setKeySize(KEY_BITS)
                .build(),
        )
        return generator.generateKey()
    }
    private companion object {
        const val ANDROID_KEYSTORE = "AndroidKeyStore"
        const val KEY_ALIAS = "minstrel_session_cookie"
        const val KEY_BITS = 256
        const val PREFS_NAME = "session_vault"
        const val KEY_COOKIE = "sealed_cookie"
    }
 }
@Module
@InstallIn(SingletonComponent::class)
 abstract class SessionVaultModule {
    @Binds
    abstract fun bindSessionVault(impl: KeystoreSessionVault): SessionVault
 }
@@ -16,10 +16,11 @@ import javax.inject.Inject
 /**
 * Computes the initial startDestination for the root NavHost based on
- * persisted auth state. Sits on top of AuthSessionDao directly rather
+ * persisted auth state. Reads the row from AuthSessionDao directly, and
- * than AuthStore's StateFlow because the StateFlow defaults to null
+ * the session cookie only after [AuthStore.awaitSessionHydrated]: both
- * until Room's first async emission — we need a definitive answer
+ * StateFlows default to null until their async load lands, and we need a
- * before drawing any nav graph.
+ * definitive answer before drawing any nav graph. The cookie lives in the
 * Keystore-backed SessionVault, not the row.
 *
 *   - no row at all          → ServerUrl   (first launch)
 *   - row with baseUrl, no cookie → Login   (URL configured, not yet signed in)
@@ -31,6 +32,7 @@ import javax.inject.Inject
@HiltViewModel
 class AuthGateViewModel @Inject constructor(
    private val dao: AuthSessionDao,
    private val authStore: AuthStore,
 ) : ViewModel() {
    private val internal = MutableStateFlow<Any?>(null)
@@ -38,12 +40,13 @@ class AuthGateViewModel @Inject constructor(
    init {
        viewModelScope.launch {
            authStore.awaitSessionHydrated()
            val signedIn = !authStore.sessionCookie.value.isNullOrEmpty()
            val row = dao.get()
            internal.value = when {
                row == null -> ServerUrl
-                row.baseUrl == AuthStore.DEFAULT_BASE_URL && row.sessionCookie.isNullOrEmpty() ->
+                row.baseUrl == AuthStore.DEFAULT_BASE_URL && !signedIn -> ServerUrl
-                    ServerUrl
+                !signedIn -> Login
                row.sessionCookie.isNullOrEmpty() -> Login
                else -> Home
            }
        }
@@ -18,15 +18,13 @@ import javax.inject.Singleton
 * Populates `audio_cache_index` from playback so the offline pools
 * ([ShuffleSource]) and the cached indicator have a data source.
 *
- * Mirrors the user-visible behavior of Flutter's `AudioCacheManager`
+ * A track you play gets cached as a side effect of streaming, and
- * (`registerStreamCache` + `touch`): a track you play gets cached as a
+ * playing it bumps its recency. Media3's `SimpleCache` is the real byte
- * side effect of streaming, and playing it bumps its recency. The
+ * store (span-based, keyed by trackId via the MediaItem's custom cache
- * Android idiom differs intentionally — Media3's `SimpleCache` is the
+ * key), so this index is a lightweight *play-recency* record
- * real byte store (span-based, keyed by trackId via the MediaItem's
+ * (source = INCIDENTAL), not a file-per-track table. SimpleCache stays
- * custom cache key), so this index is a lightweight *play-recency*
+ * the source of truth for "is it actually on disk"; this index orders
- * record (source = INCIDENTAL) rather than Flutter's file-per-track
+ * "recently played" for the offline pools.
 * table. SimpleCache stays the source of truth for "is it actually on
 * disk"; this index orders "recently played" for the offline pools.
 *
 * State observed against [PlayerController.uiState], deduped by track
 * id so each entry into the player records once. Eager-constructed via
@@ -19,11 +19,10 @@ private const val POOL_LIMIT = 100
 * storage/eviction-only and never filters playback — exactly what
 * this relies on.
 *
- * Divergence note: Flutter's `audioCacheIndex` only holds fully-cached
+ * The index records plays (see `CacheIndexer`), not residency, so the
- * tracks, so its pools are inherently resident. Android's index records
+ * recency list is intersected with true Media3 SimpleCache residency
- * plays (see `CacheIndexer`), so the recency list is intersected with
+ * here — the pool never offers a played-then-evicted track that would
- * true Media3 SimpleCache residency here — the pool never offers a
+ * fail to play offline.
 * played-then-evicted track that would fail to play offline.
 *
 * Surfaced on Home's Playlists row only when offline; tap shuffles +
 * plays the pool from the cache.
@@ -58,7 +57,7 @@ class ShuffleSource @Inject constructor(
        if (orderedIds.isEmpty()) return emptyList()
        val byId = trackDao.getByIds(orderedIds).associateBy { it.id }
        return orderedIds.mapNotNull { id ->
-            // Clear the server's missing mark (#2704). Every id reaching here
+            // Clear the server's missing mark. Every id reaching here
            // came through residentIdsByRecency, which already proved the
            // AUDIO is in the local cache — so these play regardless of what
            // the server has lost, and the queue filter in PlayerController
@@ -0,0 +1,122 @@
 package com.fabledsword.minstrel.cache.audiocache
 import java.util.TreeSet
 /** Which budget a cached track's bytes count against. */
 enum class CacheBucket { LIKED, RECENT }
 /**
 * The bookkeeping behind [TwoBucketCacheEvictor]: which budget each cached
 * span counts against, how full each budget is, and which span to drop
 * next. It knows nothing of Media3, so it is tested directly.
 *
 * A span belongs to [CacheBucket.LIKED] when its key (the track id) is in
 * the liked set, and to [CacheBucket.RECENT] otherwise. A track that is
 * liked and also recently played is therefore charged to Liked only; the
 * two budgets never count the same bytes. Each bucket drops its own
 * least-recently-used span first, so filling one never evicts the other.
 *
 * Nothing is evicted until [setLiked] has been called once. Before then
 * every span would read as Recently played, and trimming at the Recently
 * played cap would throw away liked audio at startup.
 *
 * Not thread-safe; the evictor serialises every call.
 */
 class BucketLedger<S : Any>(
    private val keyOf: (S) -> String,
    private val lengthOf: (S) -> Long,
    lruOrder: Comparator<S>,
 ) {
    private val spans = mapOf(
        CacheBucket.LIKED to TreeSet(lruOrder),
        CacheBucket.RECENT to TreeSet(lruOrder),
    )
    private val bytes = mutableMapOf(CacheBucket.LIKED to 0L, CacheBucket.RECENT to 0L)
    private val spansByKey = HashMap<String, MutableSet<S>>()
    private val bucketByKey = HashMap<String, CacheBucket>()
    private var liked: Set<String> = emptySet()
    private var armed = false
    /** Cap on Liked bytes; 0 means unlimited. */
    var likedCapBytes: Long = 0L
    /** Cap on Recently played bytes; 0 means unlimited. */
    var recentCapBytes: Long = 0L
    fun bucketOf(key: String): CacheBucket =
        if (key in liked) CacheBucket.LIKED else CacheBucket.RECENT
    fun bytesIn(bucket: CacheBucket): Long = bytes.getValue(bucket)
    /** Bytes the Liked budget can still take; [Long.MAX_VALUE] when unlimited. */
    fun likedRoomBytes(): Long = when {
        likedCapBytes <= 0L -> Long.MAX_VALUE
        else -> (likedCapBytes - bytesIn(CacheBucket.LIKED)).coerceAtLeast(0L)
    }
    fun add(span: S) {
        val key = keyOf(span)
        val bucket = bucketByKey[key] ?: bucketOf(key).also { bucketByKey[key] = it }
        if (spans.getValue(bucket).add(span)) {
            bytes[bucket] = bytesIn(bucket) + lengthOf(span)
            spansByKey.getOrPut(key) { HashSet() }.add(span)
        }
    }
    fun remove(span: S) {
        val key = keyOf(span)
        val bucket = bucketByKey[key] ?: return
        if (spans.getValue(bucket).remove(span)) {
            bytes[bucket] = bytesIn(bucket) - lengthOf(span)
        }
        val forKey = spansByKey[key] ?: return
        forKey.remove(span)
        if (forKey.isEmpty()) {
            spansByKey.remove(key)
            bucketByKey.remove(key)
        }
    }
    /**
     * Replace the liked set and move every cached track whose bucket
     * changed: a newly liked track's bytes leave Recently played for Liked,
     * an unliked track's go the other way. Arms eviction.
     */
    fun setLiked(ids: Set<String>) {
        liked = ids
        armed = true
        val moves = bucketByKey.filter { (key, bucket) -> bucketOf(key) != bucket }.keys.toList()
        for (key in moves) {
            val from = bucketByKey.getValue(key)
            val to = bucketOf(key)
            for (span in spansByKey[key].orEmpty()) {
                if (spans.getValue(from).remove(span)) {
                    bytes[from] = bytesIn(from) - lengthOf(span)
                    spans.getValue(to).add(span)
                    bytes[to] = bytesIn(to) + lengthOf(span)
                }
            }
            bucketByKey[key] = to
        }
    }
    /**
     * The span to drop next, or null when both budgets fit. [pendingKey] and
     * [pendingBytes] describe a write about to start, so room is made for it
     * in its own bucket first. Recently played is trimmed before Liked.
     */
    fun nextEviction(pendingKey: String? = null, pendingBytes: Long = 0L): S? {
        if (!armed) return null
        val pendingBucket = pendingKey?.let(::bucketOf)
        return listOf(CacheBucket.RECENT, CacheBucket.LIKED).firstNotNullOfOrNull { bucket ->
            val incoming = if (bucket == pendingBucket) pendingBytes.coerceAtLeast(0L) else 0L
            oldestIfOver(bucket, incoming)
        }
    }
    private fun oldestIfOver(bucket: CacheBucket, incoming: Long): S? {
        val cap = if (bucket == CacheBucket.LIKED) likedCapBytes else recentCapBytes
        val over = cap > 0L && bytesIn(bucket) + incoming > cap
        return if (over) spans.getValue(bucket).firstOrNull() else null
    }
 }
@@ -0,0 +1,40 @@
 package com.fabledsword.minstrel.cache.audiocache
 import com.fabledsword.minstrel.auth.AuthStore
 import com.fabledsword.minstrel.di.ApplicationScope
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.launch
 import javax.inject.Inject
 import javax.inject.Singleton
 /**
 * Keeps [TwoBucketCacheEvictor] in step with the signed-in user's liked
 * tracks and the Storage caps. A like moves that track's cached audio into
 * the Liked budget, an unlike moves it out, and a cap change trims at once.
 *
 * The liked set only flows once a user is signed in, and the evictor drops
 * nothing until it has one, so liked audio is never trimmed as Recently
 * played while the session is still loading.
 *
 * Eager-constructed via the construct-the-singleton trick in
 * `MinstrelApplication`.
 */
@Singleton
 class CacheBudgetSync @Inject constructor(
    likes: LikesRepository,
    authStore: AuthStore,
    evictor: TwoBucketCacheEvictor,
    @ApplicationScope scope: CoroutineScope,
 ) {
    init {
        scope.launch(Dispatchers.IO) {
            combine(likes.observeSignedInLikedTrackIds(), authStore.cacheSettings, ::Pair)
                .collect { (ids, settings) ->
                    evictor.update(ids, settings.likedCapBytes, settings.rollingCapBytes)
                }
        }
    }
 }
@@ -1,23 +0,0 @@
 package com.fabledsword.minstrel.cache.audiocache
 /**
 * Defaults for the 2-bucket audio cache.
 *
 *  - `likedCapBytes`: cap for the protected bucket — cached files for
 *    tracks the user has liked. Evicted only after the rolling bucket
 *    is fully drained (almost never under normal use).
 *  - `rollingCapBytes`: cap for the unprotected bucket — incidental /
 *    auto-prefetch downloads. LRU within this bucket.
 *
 * Phase 11 (Settings) will allow user overrides; the values are kept
 * generous so first-time installs work well without configuration.
 */
 data class CacheConfig(
    val likedCapBytes: Long = DEFAULT_LIKED_CAP_BYTES,
    val rollingCapBytes: Long = DEFAULT_ROLLING_CAP_BYTES,
 ) {
    companion object {
        const val DEFAULT_LIKED_CAP_BYTES: Long = 200L * 1024 * 1024 // 200 MiB
        const val DEFAULT_ROLLING_CAP_BYTES: Long = 150L * 1024 * 1024 // 150 MiB
    }
 }
@@ -9,19 +9,19 @@ private const val DEFAULT_PREFETCH_WINDOW = 5
 * User-tunable audio cache settings. Persisted as a JSON
 * blob on the auth_session single-row table via [AuthStore].
 *
- * - [likedCapBytes]: budget for cached files of liked tracks. 0 means
+ * - [likedCapBytes]: the Liked songs budget, for the cached audio of
- *   unlimited. Effective at next app start (SimpleCache is built once
+ *   liked tracks. 0 means unlimited.
- *   per process).
+ * - [rollingCapBytes]: the Recently played budget, for everything else
- * - [rollingCapBytes]: budget for incidental / auto-prefetch downloads.
+ *   streamed or prefetched. 0 means unlimited.
- *   Same 0=unlimited / restart-to-apply caveat.
+ *   A track that is liked and also recently played counts against Liked
- * - [prefetchWindow]: 1..10. Number of next-tracks the prefetcher
+ *   only. Both caps apply as soon as they change ([TwoBucketCacheEvictor]).
- *   pre-downloads. Has no effect until the prefetcher lands (separate
+ * - [prefetchWindow]: 1..10. Number of next-tracks `AudioPrefetcher`
- *   audit follow-up) — persisted now so the user can pre-configure.
+ *   pre-downloads.
- * - [cacheLikedTracks]: when true, liking a track should also pin its
+ * - [cacheLikedTracks]: "Keep liked songs offline". When true,
- *   audio to the liked-cache bucket. Has no effect until pin-on-like
+ *   `LikedAudioPinner` downloads liked tracks into the Liked budget on
- *   lands (separate follow-up).
+ *   Wi-Fi, most recently liked first, while the budget has room.
 *
- * Defaults match Flutter: 5 GiB per bucket, prefetch=5, cache-liked=true.
+ * Defaults: 5 GiB per bucket, prefetch=5, cache-liked=true.
 */
@Serializable
 data class CacheSettings(
@@ -0,0 +1,112 @@
 package com.fabledsword.minstrel.cache.audiocache
 import androidx.media3.common.C
 import androidx.media3.datasource.cache.Cache
 import androidx.media3.datasource.cache.CacheEvictor
 import androidx.media3.datasource.cache.CacheSpan
 import javax.inject.Inject
 import javax.inject.Singleton
 /**
 * Bytes held against each audio-cache budget, and how much more the Liked
 * budget can take ([Long.MAX_VALUE] when it is unlimited).
 */
 data class CacheUsage(val likedBytes: Long, val recentBytes: Long, val likedRoomBytes: Long)
 /**
 * The audio cache's eviction policy: two budgets, Liked songs and Recently
 * played, each with its own cap and its own least-recently-used order (see
 * [BucketLedger]). SimpleCache takes exactly one evictor, so this one
 * carries both budgets.
 *
 * [CacheBudgetSync] feeds it the signed-in user's liked set and the caps
 * from Storage settings, so a like, an unlike or a cap change applies at
 * once, without restarting the app.
 *
 * Locking: SimpleCache calls every [CacheEvictor] method while holding its
 * own monitor. Outside calls take the cache's monitor first and the
 * ledger's second, the same order as those callbacks, so the two never
 * deadlock.
 */
@Singleton
 class TwoBucketCacheEvictor @Inject constructor() : CacheEvictor {
    private val ledger = BucketLedger<CacheSpan>(
        keyOf = { it.key },
        lengthOf = { it.length },
        lruOrder = compareBy<CacheSpan> { it.lastTouchTimestamp }.then(naturalOrder()),
    )
    @Volatile private var cache: Cache? = null
    /** Called once the SimpleCache exists, so updates can trim it. */
    fun attach(cache: Cache) {
        this.cache = cache
    }
    /** Apply a new liked set and caps, then trim whatever no longer fits. */
    fun update(likedIds: Set<String>, likedCapBytes: Long, recentCapBytes: Long) {
        val c = cache
        val apply = {
            ledger.likedCapBytes = likedCapBytes
            ledger.recentCapBytes = recentCapBytes
            ledger.setLiked(likedIds)
        }
        if (c == null) {
            synchronized(ledger) { apply() }
        } else {
            synchronized(c) {
                synchronized(ledger) {
                    apply()
                    evict(c, pendingKey = null, pendingBytes = 0L)
                }
            }
        }
    }
    fun usage(): CacheUsage = synchronized(ledger) {
        CacheUsage(
            likedBytes = ledger.bytesIn(CacheBucket.LIKED),
            recentBytes = ledger.bytesIn(CacheBucket.RECENT),
            likedRoomBytes = ledger.likedRoomBytes(),
        )
    }
    override fun requiresCacheSpanTouches(): Boolean = true
    override fun onCacheInitialized() = Unit
    override fun onStartFile(cache: Cache, key: String, position: Long, length: Long) {
        synchronized(ledger) {
            evict(cache, key, if (length == C.LENGTH_UNSET.toLong()) 0L else length)
        }
    }
    override fun onSpanAdded(cache: Cache, span: CacheSpan) {
        synchronized(ledger) {
            ledger.add(span)
            evict(cache, pendingKey = null, pendingBytes = 0L)
        }
    }
    override fun onSpanRemoved(cache: Cache, span: CacheSpan) {
        synchronized(ledger) { ledger.remove(span) }
    }
    override fun onSpanTouched(cache: Cache, oldSpan: CacheSpan, newSpan: CacheSpan) {
        synchronized(ledger) {
            ledger.remove(oldSpan)
            ledger.add(newSpan)
            evict(cache, pendingKey = null, pendingBytes = 0L)
        }
    }
    private fun evict(cache: Cache, pendingKey: String?, pendingBytes: Long) {
        while (true) {
            val span = ledger.nextEviction(pendingKey, pendingBytes) ?: return
            cache.removeSpan(span)
            // removeSpan reports back through onSpanRemoved; removing here as
            // well guarantees the loop advances even if it did not.
            ledger.remove(span)
        }
    }
 }
@@ -3,6 +3,8 @@ package com.fabledsword.minstrel.cache.db
 import androidx.room.Database
 import androidx.room.RoomDatabase
 import androidx.room.TypeConverters
 import androidx.room.migration.Migration
 import androidx.sqlite.db.SupportSQLiteDatabase
 import com.fabledsword.minstrel.cache.db.dao.AudioCacheIndexDao
 import com.fabledsword.minstrel.cache.db.dao.AuthSessionDao
 import com.fabledsword.minstrel.cache.db.dao.CachedAlbumDao
@@ -11,6 +13,7 @@ import com.fabledsword.minstrel.cache.db.dao.CachedHistorySnapshotDao
 import com.fabledsword.minstrel.cache.db.dao.CachedHomeIndexDao
 import com.fabledsword.minstrel.cache.db.dao.CachedLikeDao
 import com.fabledsword.minstrel.cache.db.dao.CachedMutationDao
 import com.fabledsword.minstrel.cache.db.dao.CachedNotificationDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistDao
 import com.fabledsword.minstrel.cache.db.dao.CachedResumeStateDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistTrackDao
@@ -26,6 +29,8 @@ import com.fabledsword.minstrel.cache.db.entities.CachedHistorySnapshotEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedHomeIndexEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedLikeEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedMutationEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedNotificationEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedNotificationSettingsEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedPlaylistEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedResumeStateEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedPlaylistTrackEntity
@@ -35,17 +40,12 @@ import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
 import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity
 /**
- * Single Room database for the whole app. Mirrors the Flutter client's
+ * Single Room database for the whole app, one entity family per @Entity.
 * Drift `AppDb` — same logical schema, one entity-family per @Entity.
 *
- * Native v1 starts at schema version 1 (the Flutter Drift schemaVersion 11
+ * The server is the source of truth: the sync controller refills the
- * is an internal client detail; the server is the source of truth and the
+ * cache on first launch. Schema bumps land with explicit `Migration`
- * sync controller refills on first launch). Future schema bumps land per
+ * entries; `fallbackToDestructiveMigration` in `DatabaseModule` rebuilds
- * change with explicit `Migration` entries; `fallbackToDestructiveMigration`
+ * the database from a version that has no migration path.
 * in `DatabaseModule` is the safety net while we're pre-v1.
 *
 * Entity families land in Task 4.2 slices. The set will grow until the
 * whole Drift schema is mirrored.
 */
@Database(
    entities = [
@@ -64,14 +64,30 @@ import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity
        CachedHistorySnapshotEntity::class,
        AuthSessionEntity::class,
        DiagnosticEventEntity::class,
        CachedNotificationEntity::class,
        CachedNotificationSettingsEntity::class,
    ],
-    // v8: + cached_tracks.missing, the server's missing-file mark (#2704),
+    // v12: + auth_session.backgroundDelivery and notifiedUpTo, the device's
    // background-delivery choice and its shade high-water mark.
    // v11: + cached_notifications and cached_notification_settings, the
    // notifications inbox and its settings. MIGRATION_10_11 creates
    // both; nothing to backfill, the first refresh fills them.
    // v10: + cached_tracks.trackGain/trackPeak and cached_albums.albumGain/
    // albumPeak, the ReplayGain values the player levels by.
    // MIGRATION_9_10 also rewinds the sync cursor, so the next sync re-sends
    // every row and an existing cache gains its values.
    // v9: + auth_session.normalizationJson, the loudness-normalization
    // preference. The first schema step with an explicit Migration
    // (MIGRATION_8_9): a destructive rebuild would also wipe this row —
    // the server address and theme — and the queued offline writes,
    // which is too much to lose for one added column.
    // v8: + cached_tracks.missing, the server's missing-file mark,
    // so cache-first surfaces stop offering files that cannot stream.
-    // v7: + diagnostic_events table (M9) and the diagnosticsOptOut column
+    // v7: + diagnostic_events table and the diagnosticsOptOut column
-    // on auth_session. Pre-v1 destructive fallback rebuilds on mismatch —
+    // on auth_session. Versions before v8 rebuild destructively, which is
-    // which is exactly right here: the next sync refills every row with the
+    // right for them: the next sync refills every row with the new
-    // new column populated, so there is nothing to migrate by hand.
+    // columns populated, so there is nothing to migrate by hand.
-    version = 8,
+    version = 12,
    exportSchema = true,
 )
@TypeConverters(MinstrelTypeConverters::class)
@@ -91,4 +107,58 @@ abstract class AppDatabase : RoomDatabase() {
    abstract fun cachedHistorySnapshotDao(): CachedHistorySnapshotDao
    abstract fun authSessionDao(): AuthSessionDao
    abstract fun diagnosticEventDao(): DiagnosticEventDao
    abstract fun cachedNotificationDao(): CachedNotificationDao
 }
 /** v8 → v9: add the nullable normalization preference column. */
 val MIGRATION_8_9: Migration = object : Migration(8, 9) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE auth_session ADD COLUMN normalizationJson TEXT")
    }
 }
 /**
 * v9 → v10: the gain columns. Rows synced before this carry no gains,
 * and the sync is incremental, so it would never re-send them: the cursor goes
 * back to 0 and the next sync is a full one, upserting every row in place.
 */
 val MIGRATION_9_10: Migration = object : Migration(9, 10) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE cached_tracks ADD COLUMN trackGain REAL")
        db.execSQL("ALTER TABLE cached_tracks ADD COLUMN trackPeak REAL")
        db.execSQL("ALTER TABLE cached_albums ADD COLUMN albumGain REAL")
        db.execSQL("ALTER TABLE cached_albums ADD COLUMN albumPeak REAL")
        db.execSQL("UPDATE sync_metadata SET cursor = 0")
    }
 }
 /**
 * v10 → v11: the notifications inbox cache and its settings. The SQL
 * matches what Room generates for the two entities; Room checks it on open.
 */
 val MIGRATION_10_11: Migration = object : Migration(10, 11) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL(
            "CREATE TABLE IF NOT EXISTS `cached_notifications` (" +
                "`id` TEXT NOT NULL, `kind` TEXT NOT NULL, `title` TEXT NOT NULL, " +
                "`body` TEXT NOT NULL, `link` TEXT NOT NULL, `createdAt` INTEGER NOT NULL, " +
                "`readAt` INTEGER, PRIMARY KEY(`id`))",
        )
        db.execSQL(
            "CREATE TABLE IF NOT EXISTS `cached_notification_settings` (" +
                "`id` INTEGER NOT NULL, `json` TEXT NOT NULL, PRIMARY KEY(`id`))",
        )
    }
 }
 /**
 * v11 → v12: background delivery. The device choice defaults on,
 * as the entity's column default says; the high-water mark starts empty, so
 * the first catch-up sets it without announcing anything.
 */
 val MIGRATION_11_12: Migration = object : Migration(11, 12) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("ALTER TABLE auth_session ADD COLUMN backgroundDelivery INTEGER NOT NULL DEFAULT 1")
        db.execSQL("ALTER TABLE auth_session ADD COLUMN notifiedUpTo INTEGER")
    }
 }
@@ -10,6 +10,7 @@ import com.fabledsword.minstrel.cache.db.dao.CachedHistorySnapshotDao
 import com.fabledsword.minstrel.cache.db.dao.CachedHomeIndexDao
 import com.fabledsword.minstrel.cache.db.dao.CachedLikeDao
 import com.fabledsword.minstrel.cache.db.dao.CachedMutationDao
 import com.fabledsword.minstrel.cache.db.dao.CachedNotificationDao
 import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistTrackDao
@@ -32,11 +33,11 @@ object DatabaseModule {
    @Singleton
    fun provideDatabase(@ApplicationContext context: Context): AppDatabase =
        Room.databaseBuilder(context, AppDatabase::class.java, DATABASE_NAME)
-            // Pre-v1 safety net: rebuild on any schema mismatch. The sync
+            // Explicit migrations from v8 onward; an older schema has no path
-            // controller refills the cache from the server on first
+            // and rebuilds. The sync controller refills the cache from the
-            // launch, so users lose only the unsynced mutation queue
+            // server on first launch, so a rebuild loses only the unsynced
-            // (acceptable while we're iterating). Replace with explicit
+            // mutation queue.
-            // Migration entries before the first tagged release.
+            .addMigrations(MIGRATION_8_9, MIGRATION_9_10, MIGRATION_10_11, MIGRATION_11_12)
            .fallbackToDestructiveMigration(dropAllTables = true)
            .build()
@@ -111,5 +112,10 @@ object DatabaseModule {
    fun provideDiagnosticEventDao(db: AppDatabase): DiagnosticEventDao =
        db.diagnosticEventDao()
    @Provides
    @Singleton
    fun provideCachedNotificationDao(db: AppDatabase): CachedNotificationDao =
        db.cachedNotificationDao()
    private const val DATABASE_NAME = "minstrel.db"
 }
@@ -4,17 +4,10 @@ import androidx.room.TypeConverter
 import kotlinx.datetime.Instant
 /**
- * Source category for a cached audio file. Mirrors the Drift `CacheSource`
+ * How a row reached `audio_cache_index`. `CacheIndexer` writes
- * enum used by the Flutter client's `audio_cache_index` table 1:1.
+ * `INCIDENTAL` (the track was played); the other values are stored names
- *
+ * no writer uses. Eviction does not read this: the audio cache's two
- * - `MANUAL`: user explicitly pinned (e.g. "save for offline")
+ * budgets follow the liked set (see `TwoBucketCacheEvictor`).
 * - `AUTO_LIKED`: auto-cached because the track is liked
 * - `AUTO_PLAYLIST`: auto-cached because it's in a pinned playlist
 * - `AUTO_PREFETCH`: pre-warmed by background prefetch heuristics
 * - `INCIDENTAL`: cached as a side effect of playback streaming
 *
 * Eviction priority order (first to evict): INCIDENTAL → AUTO_PREFETCH
 * → AUTO_PLAYLIST → AUTO_LIKED → MANUAL.
 */
 enum class CacheSource { MANUAL, AUTO_LIKED, AUTO_PLAYLIST, AUTO_PREFETCH, INCIDENTAL }
@@ -22,10 +15,8 @@ enum class CacheSource { MANUAL, AUTO_LIKED, AUTO_PLAYLIST, AUTO_PREFETCH, INCID
 * Cross-cutting Room type converters. Registered on `@Database` via
 * `@TypeConverters(MinstrelTypeConverters::class)`.
 *
- * `kotlinx.datetime.Instant` ↔ `Long` epoch millis: the same convention the
+ * `kotlinx.datetime.Instant` ↔ `Long` epoch millis: leaner than ISO-8601
- * Flutter client uses (Drift `text()` column with ISO-8601 strings would
+ * text, and nothing needs human-readable rows in the SQLite file.
 * also work but Long is leaner; we don't need human-readable rows in the
 * SQLite file).
 */
 class MinstrelTypeConverters {
    @TypeConverter fun instantToLong(i: Instant?): Long? = i?.toEpochMilliseconds()
@@ -4,7 +4,6 @@ import androidx.room.Dao
 import androidx.room.Insert
 import androidx.room.OnConflictStrategy
 import androidx.room.Query
 import com.fabledsword.minstrel.cache.db.CacheSource
 import com.fabledsword.minstrel.cache.db.entities.AudioCacheIndexEntity
 import kotlinx.coroutines.flow.Flow
@@ -32,23 +31,6 @@ interface AudioCacheIndexDao {
    @Query("SELECT trackId FROM audio_cache_index ORDER BY lastPlayedAt DESC NULLS LAST")
    suspend fun trackIdsByRecency(): List<String>
    /** Eviction-candidate ordering — oldest lastPlayedAt first within a source. */
    @Query(
        "SELECT * FROM audio_cache_index " +
            "WHERE source = :source " +
            "ORDER BY lastPlayedAt ASC NULLS FIRST, cachedAt ASC",
    )
    suspend fun evictionCandidates(source: CacheSource): List<AudioCacheIndexEntity>
    /** Sum of bytes across rows; the rolling/liked bucket caps compare against this. */
    @Query("SELECT COALESCE(SUM(sizeBytes), 0) FROM audio_cache_index")
    suspend fun totalBytes(): Long
    @Query(
        "SELECT COALESCE(SUM(sizeBytes), 0) FROM audio_cache_index WHERE source = :source",
    )
    suspend fun bytesBySource(source: CacheSource): Long
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun upsert(row: AudioCacheIndexEntity)
@@ -6,6 +6,7 @@ import androidx.room.OnConflictStrategy
 import androidx.room.Query
 import com.fabledsword.minstrel.cache.db.entities.AuthSessionEntity
 import kotlinx.coroutines.flow.Flow
 import kotlinx.datetime.Instant
@Dao
 interface AuthSessionDao {
@@ -46,4 +47,16 @@ interface AuthSessionDao {
    /** Partial update: change only the per-device diagnostics opt-out. */
    @Query("UPDATE auth_session SET diagnosticsOptOut = :optOut WHERE id = 0")
    suspend fun setDiagnosticsOptOut(optOut: Boolean)
    /** Partial update: change only the serialized normalization preference. */
    @Query("UPDATE auth_session SET normalizationJson = :json WHERE id = 0")
    suspend fun setNormalizationJson(json: String?)
    /** Partial update: change only the background-delivery choice. */
    @Query("UPDATE auth_session SET backgroundDelivery = :enabled WHERE id = 0")
    suspend fun setBackgroundDelivery(enabled: Boolean)
    /** Partial update: change only the shade's high-water mark. */
    @Query("UPDATE auth_session SET notifiedUpTo = :upTo WHERE id = 0")
    suspend fun setNotifiedUpTo(upTo: Instant?)
 }
@@ -10,12 +10,16 @@ import kotlinx.coroutines.flow.Flow
@Dao
 interface CachedLikeDao {
-    /** All track IDs the user has liked. Audio-cache eviction uses this set. */
+    /**
     * The user's liked track IDs, most recently liked first. The audio
     * cache's Liked budget and the liked-audio downloads read this.
     */
    @Query(
        "SELECT entityId FROM cached_likes " +
-            "WHERE userId = :userId AND entityType = 'track'",
+            "WHERE userId = :userId AND entityType = 'track' " +
            "ORDER BY likedAt DESC",
    )
-    fun observeLikedTrackIds(userId: String): Flow<List<String>>
+    fun observeLikedTrackIdsNewestFirst(userId: String): Flow<List<String>>
    @Query(
        "SELECT entityId FROM cached_likes " +
@@ -44,10 +48,9 @@ interface CachedLikeDao {
    /**
     * Atomically replaces the user's entire cached_likes set with
     * [rows]. Used by [com.fabledsword.minstrel.likes.data.LikesRepository.refreshIds]
-     * so cross-device unlikes (a row that the server no longer
+     * so an unlike made on another device (a row the server no longer
-     * surfaces) get removed from the local cache — drift #570
+     * surfaces) leaves the local cache too; upserts alone would keep a
-     * caught the missing delete pass that left stale Liked tab
+     * stale Liked tab entry forever.
     * entries pointing at tracks the user had unliked elsewhere.
     */
    @Transaction
    suspend fun replaceAllForUser(userId: String, rows: List<CachedLikeEntity>) {
@@ -31,4 +31,8 @@ interface CachedMutationDao {
    @Query("DELETE FROM cached_mutations")
    suspend fun clear()
    /** Whether a write of [kind] is still waiting to be replayed. */
    @Query("SELECT EXISTS(SELECT 1 FROM cached_mutations WHERE kind = :kind)")
    suspend fun hasPending(kind: String): Boolean
 }
@@ -0,0 +1,51 @@
 package com.fabledsword.minstrel.cache.db.dao
 import androidx.room.Dao
 import androidx.room.Insert
 import androidx.room.OnConflictStrategy
 import androidx.room.Query
 import androidx.room.Transaction
 import com.fabledsword.minstrel.cache.db.entities.CachedNotificationEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedNotificationSettingsEntity
 import kotlinx.coroutines.flow.Flow
 import kotlinx.datetime.Instant
@Dao
 interface CachedNotificationDao {
    @Query("SELECT * FROM cached_notifications ORDER BY createdAt DESC, id DESC")
    fun observeAll(): Flow<List<CachedNotificationEntity>>
    @Query("SELECT COUNT(*) FROM cached_notifications WHERE readAt IS NULL")
    fun observeUnreadCount(): Flow<Int>
    @Query("SELECT * FROM cached_notifications")
    suspend fun getAll(): List<CachedNotificationEntity>
    @Query("DELETE FROM cached_notifications")
    suspend fun clear()
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertAll(rows: List<CachedNotificationEntity>)
    /** The newest page replaces the cache whole: a notice gone server-side goes here too. */
    @Transaction
    suspend fun replaceAll(rows: List<CachedNotificationEntity>) {
        clear()
        insertAll(rows)
    }
    @Query("UPDATE cached_notifications SET readAt = :at WHERE id = :id AND readAt IS NULL")
    suspend fun markRead(id: String, at: Instant)
    @Query("UPDATE cached_notifications SET readAt = :at WHERE readAt IS NULL")
    suspend fun markAllRead(at: Instant)
    @Query("SELECT * FROM cached_notification_settings WHERE id = 1")
    fun observeSettings(): Flow<CachedNotificationSettingsEntity?>
    @Query("SELECT * FROM cached_notification_settings WHERE id = 1")
    suspend fun getSettings(): CachedNotificationSettingsEntity?
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun upsertSettings(row: CachedNotificationSettingsEntity)
 }
@@ -46,13 +46,13 @@ interface CachedPlaylistTrackDao {
     * Atomic on purpose. Room's InvalidationTracker only notifies observers
     * after the transaction commits, so [observeByPlaylist] never sees the
     * empty gap between the delete and the re-insert. Un-transacted, that
-     * gap is a real observed state — it's what made every Home row visibly
+     * gap is a real observed state: the list visibly collapses to empty
-     * collapse to empty and refill before issue #2327 fixed the equivalent
+     * and refills, which is why `CachedHomeIndexDao` transacts its writes
-     * write in `CachedHomeIndexDao`.
+     * too.
     *
     * Nothing observes [observeByPlaylist] live today, so this is
-     * pre-emptive: it means making playlist detail cache-first later can't
+     * pre-emptive: making playlist detail cache-first later can't
-     * silently reintroduce that flicker.
+     * silently bring that flicker in.
     */
    @Transaction
    suspend fun replacePlaylistTracks(
@@ -41,8 +41,7 @@ interface CachedQuarantineDao {
    /**
     * Atomic full-replace from the server snapshot — one transaction so
     * the `observeAll()` watcher sees a single merged emission, not a
-     * delete-then-insert flicker. Mirrors Flutter's MyQuarantineController
+     * delete-then-insert flicker.
     * `_refreshFromServer` transaction.
     */
    @Transaction
    suspend fun replaceAll(rows: List<CachedQuarantineEntity>) {
@@ -38,6 +38,27 @@ interface CachedTrackDao {
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun upsertAll(rows: List<CachedTrackEntity>)
    /**
     * ReplayGain values for [ids]: the track's own from its row,
     * the album's from its album row. A track not in the cache has no row.
     */
    @Query(
        "SELECT t.id AS id, t.trackGain AS trackGain, t.trackPeak AS trackPeak, " +
            "a.albumGain AS albumGain, a.albumPeak AS albumPeak " +
            "FROM cached_tracks t LEFT JOIN cached_albums a ON a.id = t.albumId " +
            "WHERE t.id IN (:ids)",
    )
    suspend fun replayGains(ids: List<String>): List<CachedReplayGain>
    @Query("DELETE FROM cached_tracks WHERE id IN (:ids)")
    suspend fun deleteByIds(ids: List<String>)
 }
 /** One row of [CachedTrackDao.replayGains]. */
 data class CachedReplayGain(
    val id: String,
    val trackGain: Float?,
    val trackPeak: Float?,
    val albumGain: Float?,
    val albumPeak: Float?,
 )
@@ -7,18 +7,14 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 /**
- * One row per fully-downloaded audio file. Mirrors
+ * One row per track that has played through the audio cache (see
- * the Flutter client's `AudioCacheIndex` Drift table.
+ * `CacheIndexer`); SimpleCache, not this table, says what is on disk.
 *
- * Drives the 2-bucket LRU eviction (Phase 12 AudioCacheEvictionWorker):
+ * `source` says how the row arrived (see [CacheSource]); eviction does
- *   - `incidental` files (streamed-and-cached side effect) evict first
+ * not read it. `cachedAt` = when the row was written. `lastPlayedAt` =
- *   - `autoPrefetch` second
+ * when the user last played the track, which orders the offline
- *   - `manual` (user explicitly pinned) evict last
+ * "recently played" pool. Nullable on brand-new rows until the first
- *
+ * post-cache play touches them.
 * `cachedAt` = when we downloaded. `lastPlayedAt` = when the user last
 * played it; drives the offline "recently played" ordering and is the
 * tiebreaker for LRU eviction within a source bucket. Nullable on
 * brand-new rows until the first post-cache play touches them.
 */
@Entity(tableName = "audio_cache_index")
 data class AudioCacheIndexEntity(
@@ -1,7 +1,9 @@
 package com.fabledsword.minstrel.cache.db.entities
 import androidx.room.ColumnInfo
 import androidx.room.Entity
 import androidx.room.PrimaryKey
 import kotlinx.datetime.Instant
 /**
 * Single-row table holding the user's session cookie, configured
@@ -37,10 +39,29 @@ data class AuthSessionEntity(
     */
    val cacheSettingsJson: String? = null,
    /**
-     * Per-device opt-out of diagnostics reporting (M9). When the
+     * Per-device opt-out of diagnostics reporting. When the
     * account's debug mode is enabled by an admin, the user can still
     * turn reporting OFF on this device (battery/privacy) — that local
     * choice lives here. Default false = honor the account flag.
     */
    val diagnosticsOptOut: Boolean = false,
    /**
     * JSON-encoded NormalizationPrefs (settings/data), the last value seen
     * from the server or set here. Null = never fetched; the
     * defaults apply. Kept so offline playback still levels.
     */
    val normalizationJson: String? = null,
    /**
     * "Notifications when the app is closed": keep the
     * delivery foreground service running. A device choice, on by default.
     * The column default matches MIGRATION_11_12's, which Room checks.
     */
    @ColumnInfo(defaultValue = "1")
    val backgroundDelivery: Boolean = true,
    /**
     * The newest notice this device has announced in the shade. A catch-up
     * announces only what is newer, so a reboot or a reconnect never
     * re-announces a backlog. Cleared on sign-out.
     */
    val notifiedUpTo: Instant? = null,
 )
@@ -5,10 +5,7 @@ import androidx.room.PrimaryKey
 import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
-/**
+/** Cache row for one album. */
 * Cache row for one album. Mirrors the Flutter client's
 * `CachedAlbums` Drift table.
 */
@Entity(tableName = "cached_albums")
 data class CachedAlbumEntity(
    @PrimaryKey val id: String,
@@ -18,5 +15,8 @@ data class CachedAlbumEntity(
    val releaseDate: String? = null,
    val coverPath: String? = null,
    val mbid: String? = null,
    // ReplayGain 2.0 album values; null until every track is measured.
    val albumGain: Float? = null,
    val albumPeak: Float? = null,
    val fetchedAt: Instant = Clock.System.now(),
 )
@@ -6,13 +6,11 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 /**
- * Cache row for one artist. Mirrors the Flutter client's
+ * Cache row for one artist.
 * `CachedArtists` Drift table.
 *
- * Column names follow Kotlin idiom (camelCase) rather than Drift's
+ * Column names follow Kotlin idiom (camelCase) — the schema is purely
- * snake_case — the schema is purely internal to the native client; the
+ * internal to the app; the sync controller exchanges snake_case JSON
- * sync controller exchanges snake_case JSON with the server and our
+ * with the server and our mappers translate at the boundary.
 * mappers translate at the boundary.
 */
@Entity(tableName = "cached_artists")
 data class CachedArtistEntity(
@@ -8,8 +8,7 @@ import kotlinx.datetime.Instant
 /**
 * Single-row snapshot of the `/api/me/history` response, stored as the
 * raw wire JSON so the History tab paints instantly from disk on cold
- * open and survives connectivity loss. Mirrors the Flutter Drift
+ * open and survives connectivity loss. One row total; id defaults to 1.
 * `CachedHistorySnapshot` table (id defaults to 1; one row total).
 *
 * Cache-first + SWR: the tab observes this row and a background refresh
 * overwrites it, so the freshest plays land without a blocking spinner.
@@ -5,8 +5,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 /**
- * Per-item row driving the Home screen sections. Mirrors
+ * Per-item row driving the Home screen sections.
 * the Flutter client's `CachedHomeIndex` Drift table.
 *
 * `section` is one of (matching /api/home keys):
 *   - "recently_added_albums"
@@ -5,14 +5,13 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 /**
- * Like membership row. Mirrors the Flutter client's
+ * Like membership row. Composite primary key — one user may
 * `CachedLikes` Drift table. Composite primary key — one user may
 * independently like a track AND its album AND its artist; rows are
 * disambiguated by the (userId, entityType, entityId) triple.
 *
 * `entityType` is one of "track" | "album" | "artist". Stored as a
- * plain string for parity with the Drift schema and the server's wire
+ * plain string to match the server's wire format; an enum doesn't
- * format; an enum doesn't earn its keep here.
+ * earn its keep here.
 */
@Entity(
    tableName = "cached_likes",
@@ -6,12 +6,11 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 /**
- * One row per pending offline-write. Mirrors
+ * One row per pending offline write.
 * the Flutter client's `CachedMutations` Drift table.
 *
 * MutationQueue.enqueue() inserts a row when a server-write fails with
 * an IOException; MutationReplayer.drain() pops and re-attempts each
- * row when connectivity returns (Phase 12.2).
+ * row when connectivity returns.
 *
 * `kind` is a stable string registered in `MutationKind` — the replayer
 * looks up the handler in a kind→suspend-function map. Unknown kinds
@@ -0,0 +1,21 @@
 package com.fabledsword.minstrel.cache.db.entities
 import androidx.room.Entity
 import androidx.room.PrimaryKey
 import kotlinx.datetime.Instant
 /**
 * One notice from the user's inbox, kept so the Notifications screen
 * and the bell's badge work offline, and so a read made offline shows at once.
 * The newest page is cached; older notices are the server's to keep.
 */
@Entity(tableName = "cached_notifications")
 data class CachedNotificationEntity(
    @PrimaryKey val id: String,
    val kind: String,
    val title: String,
    val body: String,
    val link: String,
    val createdAt: Instant,
    val readAt: Instant?,
 )
@@ -0,0 +1,18 @@
 package com.fabledsword.minstrel.cache.db.entities
 import androidx.room.Entity
 import androidx.room.PrimaryKey
 /**
 * Single-row copy of the user's notification settings, stored as the
 * wire JSON, so the settings screen opens offline and a toggle shows at once.
 */
@Entity(tableName = "cached_notification_settings")
 data class CachedNotificationSettingsEntity(
    @PrimaryKey val id: Int = SINGLETON_ID,
    val json: String,
 ) {
    companion object {
        const val SINGLETON_ID = 1
    }
 }
@@ -6,8 +6,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 /**
- * Cache row for one playlist (user or system). Mirrors
+ * Cache row for one playlist (user or system).
 * the Flutter client's `CachedPlaylists` Drift table.
 *
 * `systemVariant` is null for user playlists and one of
 * "for_you" / "songs_like_artist" / "discover" / "todays_mix" / etc.
@@ -3,8 +3,7 @@ package com.fabledsword.minstrel.cache.db.entities
 import androidx.room.Entity
 /**
- * Ordered membership of tracks within a playlist. Mirrors
+ * Ordered membership of tracks within a playlist.
 * the Flutter client's `CachedPlaylistTracks` Drift table.
 * Composite PK so the same track can only appear once per playlist;
 * `position` carries the ordering.
 */
@@ -6,9 +6,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 /**
- * The current user's quarantine flag for one track. Mirrors
+ * The current user's quarantine flag for one track.
 * the Flutter client's `CachedQuarantineMine` Drift
 * table.
 *
 * The flat denormalized track/album/artist columns let the Quarantine
 * screen render off this single table without a join — the server
@@ -7,18 +7,15 @@ import kotlinx.datetime.Instant
 /**
 * Single-row snapshot of the last playback session — queue (as JSON),
- * current index, position, and source tag. Mirrors
+ * current index, position, and source tag.
 * the Flutter client's `CachedResumeState` Drift table.
 *
 * Lets a torn-down session (the player's idle/dismissed teardown)
 * resume on next launch; without it the headset / lock-screen play
- * button has nothing to act on. The Flutter codebase persists this on
+ * button has nothing to act on.
 * every queue change and reads on cold start.
 *
 * The `json` field carries the entire ResumeState shape (queue trackrefs,
- * currentIndex, positionMs, sourceTag). Kotlin-side deserialization
+ * currentIndex, positionMs, sourceTag). The ResumeController decodes it,
- * happens in the ResumeController (Phase 6.5) so the schema stays
+ * so the schema stays stable across resume-shape changes.
 * stable across resume-shape changes.
 */
@Entity(tableName = "cached_resume_state")
 data class CachedResumeStateEntity(
@@ -6,10 +6,9 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 /**
- * Cache row for one track. Mirrors the Flutter client's
+ * Cache row for one track.
 * `CachedTracks` Drift table.
 *
- * [missing] carries the server's missing-file mark (#2704). Every read that
+ * [missing] carries the server's missing-file mark. Every read that
 * can put a track in front of the user — or in a queue — must exclude it, and
 * the DAO queries do that rather than each call site remembering to.
 */
@@ -26,5 +25,9 @@ data class CachedTrackEntity(
    val fileFormat: String? = null,
    val genre: String? = null,
    val missing: Boolean = false,
    // ReplayGain 2.0 track values, kept so cached audio levels
    // offline. Null until the server has measured the track.
    val trackGain: Float? = null,
    val trackPeak: Float? = null,
    val fetchedAt: Instant = Clock.System.now(),
 )
@@ -4,14 +4,14 @@ import androidx.room.Entity
 import androidx.room.PrimaryKey
 /**
- * One buffered device-diagnostics event (M9). The DiagnosticsReporter
+ * One buffered device-diagnostics event. The DiagnosticsReporter
 * writes rows here when the account's debug mode is on; the
 * DiagnosticsUploader drains them to POST /api/diagnostics and deletes
 * on success.
 *
 * This is a deliberate ring buffer that is NOT routed through the offline
 * MutationQueue: diagnostics are high-volume, best-effort telemetry, and
- * the bug we're chasing (roaming / dead-zone recovery) happens WHILE
+ * the failures they record (roaming / dead-zone recovery) happen WHILE
 * offline — so events must persist locally through the dead zone and
 * upload on recovery, without clogging the user-data mutation replay.
 *
@@ -7,12 +7,8 @@ import kotlinx.datetime.Instant
 /**
 * Single-row table that tracks where the SyncController left off.
 *
- * Mirrors the Flutter Drift `sync_metadata` table. There is only ever
+ * There is only ever one row at `id = 0`; the SyncController upserts it
- * one row at `id = 0`; the SyncController upserts on every successful
+ * on every successful `/api/library/sync` call.
 * `/api/sync` call.
 *
 * Pulled into Task 4.1 to give Room a compileable @Database (it needs
 * at least one entity); the SyncController itself lands in Phase 12.4.
 */
@Entity(tableName = "sync_metadata")
 data class SyncMetadataEntity(
@@ -1,7 +1,9 @@
 package com.fabledsword.minstrel.cache.mutations
 import com.fabledsword.minstrel.api.endpoints.NotificationSettingChangeWire
 import com.fabledsword.minstrel.cache.db.dao.CachedMutationDao
 import com.fabledsword.minstrel.cache.db.entities.CachedMutationEntity
 import com.fabledsword.minstrel.settings.data.NormalizationPrefs
 import kotlinx.coroutines.channels.BufferOverflow
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.SharedFlow
@@ -31,16 +33,31 @@ object MutationKind {
    // Durable close-by-id for a play whose server row is already open
    // (play_started succeeded). Distinct from PLAY_OFFLINE, which records
-    // a *whole* play when no server row exists. Using close-by-id on
+    // a *whole* play when no server row exists. Recording a whole play on
-    // background avoids the duplicate + orphan row the old offline-on-stop
+    // background would duplicate the open row and leave it orphaned.
    // path produced (see 2026-06-11 contract audit).
    const val PLAY_ENDED: String = "play_ended"
-    // #2374 suggestion snooze. ONE toggle kind rather than separate
+    // Suggestion snooze. ONE toggle kind rather than separate
    // snooze/unsnooze kinds, mirroring LIKE_TOGGLE, so a snooze followed by
    // an undo collapses to the latest intent instead of replaying as two
    // opposed calls whose order decides the outcome.
    const val SUGGESTION_SNOOZE_TOGGLE: String = "suggestion_snooze_toggle"
    // Loudness-normalization preference. The payload is the whole
    // preference, a target state like the toggles above, so queued changes
    // collapse to the last one and an older one can never be replayed last.
    const val NORMALIZATION_SET: String = "normalization_set"
    // Notifications inbox. A read is a one-way action (read never goes
    // back to unread), so neither read kind needs collapsing. Read-all
    // carries the moment the user asked, so a late replay leaves newer
    // notices unread.
    const val NOTIFICATION_READ: String = "notification_read"
    const val NOTIFICATIONS_READ_ALL: String = "notifications_read_all"
    // Per-kind notification channel. One row per (kind, channel) target
    // state, collapsed on that pair, so the newest choice is the one sent.
    const val NOTIFICATION_SETTING_SET: String = "notification_setting_set"
 }
 /**
@@ -57,8 +74,8 @@ data class LikeTogglePayload(
 )
 /**
- * Persisted payload for `MutationKind.REQUEST_CREATE` (Discover →
+ * Persisted payload for `MutationKind.REQUEST_CREATE` (a Discover
- * Lidarr request that landed during a connectivity hiccup). Optional
+ * request that landed during a connectivity hiccup). Optional
 * fields stay null when not applicable; the replayer rebuilds the
 * `CreateRequestBody` from these.
 */
@@ -74,17 +91,15 @@ data class RequestCreatePayload(
 )
 /**
- * Minimal write-side of the offline mutation queue. Phase 8 v1 only
+ * Write side of the offline mutation queue; [MutationReplayer] drains it.
 * enqueues — the connectivity-aware replayer that drains the queue
 * lands with Phase 12.2's SyncController.
 *
 * Callers (LikesRepository et al.) follow the optimistic-write
 * pattern: mutate Room first so the UI reflects the change
 * immediately, fire the REST call as a best-effort attempt, and on
 * failure enqueue here so the replayer eventually pushes it through.
- * This matches `feedback_offline_first_for_server_writes` — writes
+ * Writes never go fire-and-forget.
 * never go fire-and-forget.
 */
@Suppress("TooManyFunctions") // one enqueue per mutation kind, like the replayer's dispatchers
@Singleton
 class MutationQueue @Inject constructor(
    private val dao: CachedMutationDao,
@@ -177,6 +192,31 @@ class MutationQueue @Inject constructor(
        ),
    )
    /** Queues the user's whole normalization preference for replay. */
    suspend fun enqueueNormalizationSet(prefs: NormalizationPrefs): Long = insertUserDriven(
        MutationKind.NORMALIZATION_SET,
        json.encodeToString(NormalizationPrefs.serializer(), prefs),
    )
    suspend fun enqueueNotificationRead(id: String): Long = insertUserDriven(
        MutationKind.NOTIFICATION_READ,
        json.encodeToString(NotificationReadPayload.serializer(), NotificationReadPayload(id)),
    )
    suspend fun enqueueNotificationsReadAll(upToIso: String?): Long = insertUserDriven(
        MutationKind.NOTIFICATIONS_READ_ALL,
        json.encodeToString(
            NotificationsReadAllPayload.serializer(),
            NotificationsReadAllPayload(upToIso),
        ),
    )
    suspend fun enqueueNotificationSettingSet(payload: NotificationSettingPayload): Long =
        insertUserDriven(
            MutationKind.NOTIFICATION_SETTING_SET,
            json.encodeToString(NotificationSettingPayload.serializer(), payload),
        )
    suspend fun enqueueRequestCancel(requestId: String): Long = insertUserDriven(
        MutationKind.REQUEST_CANCEL,
        json.encodeToString(
@@ -218,7 +258,7 @@ class MutationQueue @Inject constructor(
 }
 /**
- * Persisted payload for `MutationKind.SUGGESTION_SNOOZE_TOGGLE` (#2374).
+ * Persisted payload for `MutationKind.SUGGESTION_SNOOZE_TOGGLE`.
 * `desiredSnoozed` is the *target* state, matching [LikeTogglePayload], so
 * the replayer can collapse repeated toggles for one candidate down to the
 * last intent. Both directions are idempotent server-side: re-snoozing
@@ -241,10 +281,10 @@ data class SuggestionSnoozeTogglePayload(
 data class QuarantineUnflagPayload(val trackId: String)
 /**
- * Persisted payload for `MutationKind.PLAYLIST_APPEND`. Mirrors the
+ * Persisted payload for `MutationKind.PLAYLIST_APPEND`: the track IDs to
- * Flutter wire shape: list of track IDs to append to a specific
+ * append to one playlist. The server is idempotent at the
- * playlist. Server is idempotent at the (playlist_id, track_id) pair
+ * (playlist_id, track_id) pair level — re-firing the same payload yields
- * level — re-firing the same payload yields no duplicates.
+ * no duplicates.
 */
@Serializable
 data class PlaylistAppendPayload(
@@ -270,7 +310,7 @@ data class QuarantineFlagPayload(
 * re-fires `POST /api/events` with type=play_offline; the server
 * records start+end from `atIso` (the original play-start time)
 * + `durationPlayedMs`, applies the canonical skip rule, and
- * advances #415 rotation when source is a system playlist.
+ * advances rotation when source is a system playlist.
 */
@Serializable
 data class PlayOfflinePayload(
@@ -279,7 +319,7 @@ data class PlayOfflinePayload(
    val atIso: String,
    val durationPlayedMs: Long,
    val source: String? = null,
-    // #1551: device class for context conditioning; null on payloads queued
+    // Device class for context conditioning; null on payloads queued
    // before this field existed (decodes to null → server stores NULL).
    val deviceClass: String? = null,
 )
@@ -322,3 +362,36 @@ data class PlaybackErrorReportPayload(
    val detail: String? = null,
    val clientId: String,
 )
 /** Persisted payload for `MutationKind.NOTIFICATION_READ`. */
@Serializable
 data class NotificationReadPayload(val id: String)
 /**
 * Persisted payload for `MutationKind.NOTIFICATIONS_READ_ALL`.
 * `upToIso` is the newest notice the user could see when they asked; null
 * when the inbox was empty on the device, which marks everything.
 */
@Serializable
 data class NotificationsReadAllPayload(val upToIso: String?)
 /**
 * Persisted payload for `MutationKind.NOTIFICATION_SETTING_SET`: one
 * kind's one channel, as a target state. `channel` is "inbox" | "phone" |
 * "email". No defaults, so every field is always written.
 */
@Serializable
 data class NotificationSettingPayload(
    val kind: String,
    val channel: String,
    val value: Boolean,
 )
 /** The wire change for one queued channel setting, or null for an unknown channel. */
 internal fun notificationSettingChange(p: NotificationSettingPayload): NotificationSettingChangeWire? =
    when (p.channel) {
        "inbox" -> NotificationSettingChangeWire(kind = p.kind, inbox = p.value)
        "phone" -> NotificationSettingChangeWire(kind = p.kind, phone = p.value)
        "email" -> NotificationSettingChangeWire(kind = p.kind, email = p.value)
        else -> null
    }
@@ -7,6 +7,10 @@ import com.fabledsword.minstrel.api.endpoints.DiscoverApi
 import com.fabledsword.minstrel.api.endpoints.EventsApi
 import com.fabledsword.minstrel.api.endpoints.FlagRequest
 import com.fabledsword.minstrel.api.endpoints.LikesApi
 import com.fabledsword.minstrel.api.endpoints.MeApi
 import com.fabledsword.minstrel.api.endpoints.NotificationsApi
 import com.fabledsword.minstrel.api.endpoints.PutNotificationSettingsBody
 import com.fabledsword.minstrel.api.endpoints.ReadAllBody
 import com.fabledsword.minstrel.api.endpoints.PlaybackErrorReportRequest
 import com.fabledsword.minstrel.api.endpoints.PlaybackErrorsApi
 import com.fabledsword.minstrel.api.endpoints.PlaylistsApi
@@ -22,6 +26,7 @@ import com.fabledsword.minstrel.cache.db.dao.CachedMutationDao
 import com.fabledsword.minstrel.cache.db.entities.CachedMutationEntity
 import com.fabledsword.minstrel.di.ApplicationScope
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.settings.data.NormalizationPrefs
 import com.fabledsword.minstrel.models.wire.CreateRequestBody
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.flow.distinctUntilChanged
@@ -79,6 +84,8 @@ class MutationReplayer @Inject constructor(
    private val eventsApi: EventsApi = retrofit.create()
    private val requestsApi: RequestsApi = retrofit.create()
    private val playbackErrorsApi: PlaybackErrorsApi = retrofit.create()
    private val meApi: MeApi = retrofit.create()
    private val notificationsApi: NotificationsApi = retrofit.create()
    private val mutex = Mutex()
@@ -153,7 +160,7 @@ class MutationReplayer @Inject constructor(
    /**
     * Returns the outcome of replaying one row. SENT on a 2xx; DROP for an
     * unknown kind/variant. Network / HTTP failures THROW and are classified
-     * by [outcomeFor] — dispatchers no longer swallow.
+     * by [outcomeFor] — dispatchers never swallow them.
     */
    private suspend fun dispatch(row: CachedMutationEntity): Outcome = when (row.kind) {
        MutationKind.LIKE_TOGGLE -> dispatchLikeToggle(row.payload)
@@ -166,10 +173,23 @@ class MutationReplayer @Inject constructor(
        MutationKind.REQUEST_CANCEL -> dispatchRequestCancel(row.payload)
        MutationKind.PLAYBACK_ERROR_REPORT -> dispatchPlaybackErrorReport(row.payload)
        MutationKind.SUGGESTION_SNOOZE_TOGGLE -> dispatchSuggestionSnoozeToggle(row.payload)
        MutationKind.NORMALIZATION_SET -> dispatchNormalizationSet(row.payload)
        MutationKind.NOTIFICATION_READ,
        MutationKind.NOTIFICATIONS_READ_ALL,
        MutationKind.NOTIFICATION_SETTING_SET,
        -> dispatchNotification(row)
        // Unknown kind — drop so a stale schema entry can't wedge the queue.
        else -> Outcome.DROP
    }
    /** The notifications inbox's kinds, split out to keep [dispatch] simple. */
    private suspend fun dispatchNotification(row: CachedMutationEntity): Outcome = when (row.kind) {
        MutationKind.NOTIFICATION_READ -> dispatchNotificationRead(row.payload)
        MutationKind.NOTIFICATIONS_READ_ALL -> dispatchNotificationsReadAll(row.payload)
        MutationKind.NOTIFICATION_SETTING_SET -> dispatchNotificationSettingSet(row.payload)
        else -> Outcome.DROP
    }
    private suspend fun dispatchLikeToggle(payload: String): Outcome {
        val decoded = json.decodeFromString(LikeTogglePayload.serializer(), payload)
        val kindPath = when (decoded.entityType) {
@@ -279,6 +299,37 @@ class MutationReplayer @Inject constructor(
        return Outcome.SENT
    }
    /**
     * Sends the queued normalization preference. The device already shows
     * it, so the server's echo is not written back: a change made since the
     * row was queued would be a newer row, and the collapse keeps only that.
     */
    private suspend fun dispatchNormalizationSet(payload: String): Outcome {
        meApi.putNormalization(json.decodeFromString(NormalizationPrefs.serializer(), payload))
        return Outcome.SENT
    }
    /** A 404 (the notice was trimmed or already gone) is a 4xx, so DROP: nothing left to do. */
    private suspend fun dispatchNotificationRead(payload: String): Outcome {
        val decoded = json.decodeFromString(NotificationReadPayload.serializer(), payload)
        notificationsApi.markRead(decoded.id)
        return Outcome.SENT
    }
    private suspend fun dispatchNotificationsReadAll(payload: String): Outcome {
        val decoded = json.decodeFromString(NotificationsReadAllPayload.serializer(), payload)
        notificationsApi.readAll(ReadAllBody(upTo = decoded.upToIso))
        return Outcome.SENT
    }
    /** An unknown channel can only come from a corrupt row: DROP it. */
    private suspend fun dispatchNotificationSettingSet(payload: String): Outcome {
        val decoded = json.decodeFromString(NotificationSettingPayload.serializer(), payload)
        val change = notificationSettingChange(decoded) ?: return Outcome.DROP
        notificationsApi.putSettings(PutNotificationSettingsBody(listOf(change)))
        return Outcome.SENT
    }
    private suspend fun dispatchPlaybackErrorReport(payload: String): Outcome {
        val decoded = json.decodeFromString(PlaybackErrorReportPayload.serializer(), payload)
        playbackErrorsApi.report(
@@ -303,7 +354,8 @@ class MutationReplayer @Inject constructor(
 /**
 * Row ids of desired-state toggles superseded by a later toggle for the same
 * entity. Applies to every kind whose payload encodes a TARGET state rather
- * than an action — like-toggles and suggestion snoozes (#2374) — because
+ * than an action — like-toggles, suggestion snoozes and the
 * normalization preference — because
 * replaying a stale one last would invert the final state.
 *
 * Top-level and pure so it can be unit-tested without standing up a Retrofit
@@ -340,5 +392,14 @@ private fun toggleKeyOf(row: CachedMutationEntity, json: Json): String? = when (
        json.decodeFromString(SuggestionSnoozeTogglePayload.serializer(), row.payload)
    }.getOrNull()?.let { "${row.kind}:${it.mbid}" }
    MutationKind.NOTIFICATION_SETTING_SET -> runCatching {
        json.decodeFromString(NotificationSettingPayload.serializer(), row.payload)
    }.getOrNull()?.let { "${row.kind}:${it.kind}:${it.channel}" }
    // One preference per user, so every normalization row shares one key.
    MutationKind.NORMALIZATION_SET -> runCatching {
        json.decodeFromString(NormalizationPrefs.serializer(), row.payload)
    }.getOrNull()?.let { row.kind }
    else -> null
 }
@@ -34,9 +34,8 @@ import javax.inject.Inject
 import javax.inject.Singleton
 /**
- * Drives the delta sync against `/api/library/sync` (#357). Mirrors
+ * Drives the delta sync against `/api/library/sync`, scoped to the
- * the Flutter `SyncController`, scoped to the entity types the
+ * entity types the app caches (artist/album/track). Likes and
 * native client cares about (artist/album/track). Likes and
 * playlists get their own dedicated refresh paths so the sync
 * controller doesn't need to track them.
 *
@@ -46,10 +45,9 @@ import javax.inject.Singleton
 * with a persisted cookie). Re-running on every cookie change is
 * what makes the Library tabs populate within seconds of sign-in.
 *
- * Wipes-on-410: when the server's compaction window has passed the
+ * Restart-on-410: when the server's compaction window has passed the
- * stored cursor, the response is 410 Gone. The controller drops the
+ * stored cursor, the response is 410 Gone. The controller resets the
- * three local caches and recurses with cursor=0 — same wipe behavior
+ * cursor to 0 and pulls the full entity set again (see [resetCursor]).
 * as the Flutter port.
 */
@Singleton
 class SyncController @Inject constructor(
@@ -109,19 +107,36 @@ class SyncController @Inject constructor(
        }
    }
    /**
     * Pulls pages until the server has nothing newer. The server returns
     * at most 1000 changes a call, and a full library re-read adds tens
     * of thousands, so one page per trigger would leave the cache behind:
     * merge deletes would never arrive and the freshness sweep would keep
     * asking for tracks that are gone. The cursor is stored after each
     * page, so an interrupted pass resumes where it stopped.
     */
    private suspend fun sync() {
        repeat(MAX_PAGES_PER_PASS) {
            if (!syncPage()) return
        }
    }
    /** One page of the change log. True when the server may hold more. */
    private suspend fun syncPage(): Boolean {
        val meta = syncMetadataDao.get()
        val cursor = meta?.cursor ?: 0L
        val response = api.sync(cursor)
-        when (response.code()) {
+        return when (response.code()) {
            HTTP_NO_CONTENT -> {
                touchLastSyncAt(cursor)
                false
            }
            HTTP_GONE -> {
-                wipeAndRetry()
+                resetCursor()
                true
            }
            HTTP_OK -> {
-                val body = response.body() ?: return
+                val body = response.body() ?: return false
                applyDeltas(body.upserts.artist, body.upserts.album, body.upserts.track)
                applyDeletes(body.deletes.artist, body.deletes.album, body.deletes.track)
                syncMetadataDao.upsert(
@@ -131,10 +146,14 @@ class SyncController @Inject constructor(
                        lastSyncAt = Clock.System.now(),
                    ),
                )
                // A cursor that did not advance would ask for the same page
                // again; stop rather than spin.
                body.cursor > cursor
            }
            else -> {
-                // Unhandled status — treat as a no-op for v1; the next
+                // Unhandled status — treat as a no-op; the next
                // app start retries from the same cursor.
                false
            }
        }
    }
@@ -165,25 +184,27 @@ class SyncController @Inject constructor(
        )
    }
-    private suspend fun wipeAndRetry() {
+    private suspend fun resetCursor() {
        // The Library DAOs only expose deleteByIds; for the rare 410
-        // path we re-issue the same request with cursor=0 after
+        // path the next page is requested with cursor=0 after
-        // resetting our cursor. The next response carries the full
+        // resetting our cursor. The following pages carry the full
        // entity set, which upsertAll overwrites the existing rows
        // with — old rows for entities the server no longer knows
-        // about will linger until a later 410 or until the user clears
+        // about linger until MetadataProvider's refresh meets their
-        // app data. Acceptable for v1; a future "wipe all" DAO method
+        // 404 and drops them.
        // tightens this up.
        syncMetadataDao.upsert(
            SyncMetadataEntity(id = 0, cursor = 0, lastSyncAt = null),
        )
        sync()
    }
    private companion object {
        const val HTTP_OK = 200
        const val HTTP_NO_CONTENT = 204
        const val HTTP_GONE = 410
        // A guard, not a budget: 1000 pages is a million changes, far past
        // anything a library writes between two app starts.
        const val MAX_PAGES_PER_PASS = 1000
    }
 }
@@ -206,6 +227,8 @@ private fun SyncAlbumWire.toEntity(): CachedAlbumEntity = CachedAlbumEntity(
    releaseDate = releaseDate,
    coverPath = coverArtPath,
    mbid = mbid,
    albumGain = albumGain,
    albumPeak = albumPeak,
 )
 private fun SyncTrackWire.toEntity(): CachedTrackEntity = CachedTrackEntity(
@@ -220,4 +243,6 @@ private fun SyncTrackWire.toEntity(): CachedTrackEntity = CachedTrackEntity(
    fileFormat = fileFormat,
    genre = genre,
    missing = missing,
    trackGain = trackGain,
    trackPeak = trackPeak,
 )
@@ -74,6 +74,35 @@ class ConnectivityObserver @Inject constructor(
        awaitClose { cm.unregisterNetworkCallback(callback) }
    }.distinctUntilChanged()
    /**
     * Whether the network the device is using now is unmetered: Wi-Fi or
     * Ethernet, but not mobile data or a hotspot Android marks metered.
     * Downloads the user did not start (the liked-song downloads) wait for
     * this.
     */
    val unmetered: Flow<Boolean> = callbackFlow {
        val callback = object : ConnectivityManager.NetworkCallback() {
            override fun onCapabilitiesChanged(
                network: Network,
                capabilities: NetworkCapabilities,
            ) {
                trySend(capabilities.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED))
            }
            override fun onLost(network: Network) {
                trySend(false)
            }
        }
        cm.registerDefaultNetworkCallback(callback)
        trySend(isActiveNetworkUnmetered())
        awaitClose { cm.unregisterNetworkCallback(callback) }
    }.distinctUntilChanged()
    private fun isActiveNetworkUnmetered(): Boolean {
        val caps = cm.activeNetwork?.let { cm.getNetworkCapabilities(it) }
        return caps != null &&
            caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED)
    }
    private fun hasActiveNetwork(): Boolean {
        val caps = cm.activeNetwork?.let { cm.getNetworkCapabilities(it) }
        return caps != null &&
@@ -29,27 +29,25 @@ private const val POLL_DEGRADED_MS = 20_000L
 private const val ARBITRATE_MIN_GAP_MS = 2_000L
 /**
- * THE single authority on network/server reachability. Absorbs the former
+ * THE single authority on network/server reachability: the /healthz poll,
- * VersionCheckController (the /healthz poll + version parsing) and
+ * version parsing and the tri-state health derive live in one
- * ServerHealthController (the tri-state derive) into one signal-driven unit so
+ * signal-driven unit, so the app has one place that answers "can we reach
- * the app has one place that answers "can we reach Minstrel?" — not three
+ * Minstrel?".
 * half-systems reporting differently.
 *
 * Inputs (all funnel through a single-consumer intent channel for thread
 * safety — [reportSuccess]/[reportFailure] are called from the audio read path
 * and OkHttp threads):
 *  - device link transitions ([ConnectivityObserver]); link-return triggers an
- *    immediate probe so recovery is near-instant (fixes the sticky banner).
+ *    immediate probe so recovery is near-instant.
 *  - periodic /healthz probe, adaptive cadence (calm when Healthy, fast when down).
 *  - reportSuccess / reportFailure from the API interceptor, the audio data
 *    source, and the playback-error reporter.
 *  - recheck() from pull-to-refresh and the banner.
- *  - a forced probe when the app returns to the foreground (#1209). Without
+ *  - a forced probe when the app returns to the foreground. The poll
- *    it a stale ServerDown outlived the condition that caused it: the poll
+ *    loop's delay() is throttled while screen-off/doze, so without it a
- *    loop's delay() is throttled while screen-off/doze, so recovery waited on
+ *    stale ServerDown would outlive its cause until the OS next let the
- *    whenever the OS next let the loop run. Meanwhile ServerDown makes
+ *    loop run — and ServerDown makes OfflineGatedDataSource refuse every
- *    OfflineGatedDataSource refuse every uncached track, so the app declined
+ *    uncached track, declining music that would play fine.
 *    to play music that would have played fine.
 *
 * Version compatibility is a byproduct of the same /healthz response.
 *
@@ -112,7 +110,7 @@ class NetworkStatusController @Inject constructor(
    /**
     * App returned to the foreground — probe now rather than waiting for the
-     * poll loop (#1209).
+     * poll loop.
     *
     * The link-return probe in `init` does NOT cover this: it fires on a
     * connectivity *change*, and an app backgrounded on stable Wi-Fi sees none.
@@ -172,7 +170,7 @@ class NetworkStatusController @Inject constructor(
    private suspend fun probeOnce(force: Boolean = false) {
        // Startup guard: don't poll the localhost placeholder before AuthStore
-        // hydrates the real base URL — that false failure used to flash the banner.
+        // hydrates the real base URL — that false failure would flash the banner.
        if (authStore.baseUrl.value == AuthStore.DEFAULT_BASE_URL) return
        val now = System.currentTimeMillis()
        if (!force && now - lastProbeAtMs.get() < ARBITRATE_MIN_GAP_MS) return
@@ -5,15 +5,14 @@ internal const val CORROBORATION_WINDOW_MS = 30_000L
 internal const val CORROBORATION_OP_THRESHOLD = 2
 /**
- * Minimum gap between op failures for them to count as SEPARATE evidence
+ * Minimum gap between op failures for them to count as SEPARATE evidence.
 * (#1209).
 *
 * A link handoff fails every in-flight request at once, so a burst is one
 * event producing N failures — not N independent observations that the server
- * is gone. Without this, two simultaneous failures corroborated each other
+ * is gone. Counted separately, two simultaneous failures would corroborate
- * straight to Unreachable, and ServerDown makes OfflineGatedDataSource refuse
+ * each other straight to Unreachable, and ServerDown makes
- * every uncached track. The app declined to play music that would have played
+ * OfflineGatedDataSource refuse every uncached track: the app would decline
- * fine, for a blip that had already resolved.
+ * music that plays fine, for a blip that had already resolved.
 *
 * 3s is comfortably above the sub-second window an OS handoff occupies while
 * still letting a genuine outage corroborate within seconds once a client
@@ -38,7 +38,7 @@ import javax.inject.Inject
 import javax.inject.Singleton
 /**
- * On-device diagnostics collector (M9). Active only while the account's
+ * On-device diagnostics collector. Active only while the account's
 * debug mode is enabled (server flag, read via AuthController.currentUser)
 * AND the user hasn't opted out locally. When active it taps existing
 * connectivity / player / UPnP / power seams READ-ONLY and writes a
@@ -196,13 +196,11 @@ class DiagnosticsReporter @Inject constructor(
    /**
     * Catch the renderer rapidly leaving and re-entering PLAYING.
     *
-     * The operator reports the Sonos "play pause play pause, like someone
+     * The symptom: a Sonos rapidly play-pause-play-pausing, about every half
-     * pressing it every half second", usually as a track starts, cleared by a
+     * second, usually as a track starts, cleared by a manual pause or skip.
-     * manual pause or skip. Nothing here could see that: `player_state`
+     * No other collector sees it: `player_state` carries
-     * carries source/loading/error but not playing, `track_change` needs the
+     * source/loading/error but not playing, `track_change` needs the index
-     * index to move, and the heartbeat samples once per 45s. The symptom fell
+     * to move, and the heartbeat samples once per 45s.
     * through every existing collector, which is why it has only ever been
     * described and never measured.
     *
     * Records every raw transport change (cheap — steady playback produces
     * a couple per track) and, when they come in a burst, one summary event
@@ -27,7 +27,7 @@ import javax.inject.Singleton
 /**
 * Drains the [DiagnosticEventDao] ring buffer to POST /api/diagnostics
- * (M9). Triggers mirror [com.fabledsword.minstrel.cache.mutations.MutationReplayer]:
+ *. Triggers mirror [com.fabledsword.minstrel.cache.mutations.MutationReplayer]:
 * a periodic tick, a sign-in (sessionCookie non-null), and a server-health
 * recovery to [ServerHealth.Healthy] — so a dead-zone's buffered events
 * upload the moment the link comes back.
@@ -6,10 +6,9 @@ import com.fabledsword.minstrel.player.TransportObservation
 * Decides when a run of renderer transport changes is a *flap* — the renderer
 * repeatedly failing to settle — rather than an ordinary track transition.
 *
- * The operator reports the Sonos "play pause play pause, like someone pressing
+ * The symptom: a Sonos rapidly play-pause-play-pausing, about every half
- * it every half second", usually as a track starts. No diagnostic event could
+ * second, usually as a track starts. No other diagnostic event records it;
- * see it, so it has been described several times and measured never. This is
+ * this is the rule that decides when an episode is worth writing down.
 * the rule that decides when an episode is worth writing down.
 *
 * Pure decision state, like [com.fabledsword.minstrel.player.RemoteStallWatchdog]:
 * the caller owns the flow and the recording, this only answers "is this an
@@ -4,13 +4,13 @@ import com.fabledsword.minstrel.api.endpoints.DiscoverApi
 import com.fabledsword.minstrel.cache.mutations.MutationQueue
 import com.fabledsword.minstrel.cache.mutations.RequestCreatePayload
 import com.fabledsword.minstrel.models.ArtistSuggestionRef
-import com.fabledsword.minstrel.models.LidarrRequestKind
+import com.fabledsword.minstrel.models.RequestKind
-import com.fabledsword.minstrel.models.LidarrSearchResultRef
+import com.fabledsword.minstrel.models.CatalogueResultRef
 import com.fabledsword.minstrel.models.SeedContributionRef
 import com.fabledsword.minstrel.models.SuggestionSnoozeRef
 import com.fabledsword.minstrel.models.wire.ArtistSuggestionWire
 import com.fabledsword.minstrel.models.wire.CreateRequestBody
-import com.fabledsword.minstrel.models.wire.LidarrSearchResultWire
+import com.fabledsword.minstrel.models.wire.CatalogueSearchResultWire
 import com.fabledsword.minstrel.models.wire.SeedContributionWire
 import com.fabledsword.minstrel.models.wire.SnoozeSuggestionBody
 import com.fabledsword.minstrel.models.wire.SuggestionSnoozeWire
@@ -28,17 +28,12 @@ import javax.inject.Singleton
 enum class RequestOutcome { ACCEPTED, QUEUED }
 /**
- * Read-through Discover surface: Lidarr search, suggestion feed, and
+ * Read-through Discover surface: catalogue search, suggestion feed, and
- * the request-creation write path. Mirrors the Flutter
+ * the request-creation write path. Writes never go fire-and-forget, so
- * `DiscoverApi` + `mutationQueueProvider` integration —
+ * `createRequest` falls back to the MutationQueue on transport failure.
 * `feedback_offline_first_for_server_writes` says writes never go
 * fire-and-forget, so `createRequest` falls back to the
 * MutationQueue on transport failure.
 *
- * Reads are not cached locally yet — discovery results are inherently
+ * Reads are not cached locally — discovery results are inherently
- * transient (60s server-side LRU); the cache wins are minor and
+ * transient (60s server-side LRU), so a local cache would win little.
 * unblock no UX. Phase 13's offline pass adds an offline scrollback
 * for the suggestion feed only.
 */
@Singleton
 class DiscoverRepository @Inject constructor(
@@ -54,7 +49,7 @@ class DiscoverRepository @Inject constructor(
        api.listSnoozes().map { it.toDomain() }
    /**
-     * Parks a suggestion ("not right now"). Offline-first per rule #100: on
+     * Parks a suggestion ("not right now"). Offline-first: on
     * transport failure the target state is queued for the replayer rather
     * than dropped.
     *
@@ -113,7 +108,7 @@ class DiscoverRepository @Inject constructor(
        code in HTTP_CLIENT_ERR_MIN..HTTP_CLIENT_ERR_MAX &&
            code != HTTP_TIMEOUT && code != HTTP_TOO_MANY
-    suspend fun search(query: String, kind: LidarrRequestKind): List<LidarrSearchResultRef> =
+    suspend fun search(query: String, kind: RequestKind): List<CatalogueResultRef> =
        api.search(query = query, kind = kind.wire).map { it.toDomain() }
    /**
@@ -123,7 +118,7 @@ class DiscoverRepository @Inject constructor(
     * 2xx, [RequestOutcome.QUEUED] when the call was buffered.
     */
    suspend fun createRequest(
-        kind: LidarrRequestKind,
+        kind: RequestKind,
        artistMbid: String,
        artistName: String,
        albumMbid: String? = null,
@@ -163,7 +158,7 @@ class DiscoverRepository @Inject constructor(
 // ── Mappers (internal — wire types stay out of UI) ──
-private fun LidarrSearchResultWire.toDomain(): LidarrSearchResultRef = LidarrSearchResultRef(
+private fun CatalogueSearchResultWire.toDomain(): CatalogueResultRef = CatalogueResultRef(
    mbid = mbid,
    name = name,
    secondaryText = secondaryText,
@@ -38,8 +38,8 @@ import com.composables.icons.lucide.Lucide
 import com.composables.icons.lucide.Search as LucideSearch
 import com.fabledsword.minstrel.discover.data.RequestOutcome
 import com.fabledsword.minstrel.models.ArtistSuggestionRef
-import com.fabledsword.minstrel.models.LidarrRequestKind
+import com.fabledsword.minstrel.models.RequestKind
-import com.fabledsword.minstrel.models.LidarrSearchResultRef
+import com.fabledsword.minstrel.models.CatalogueResultRef
 import com.fabledsword.minstrel.models.SuggestionSnoozeRef
 import com.fabledsword.minstrel.nav.Discover
 import com.fabledsword.minstrel.shared.widgets.ShellContentWindowInsets
@@ -161,7 +161,7 @@ private fun SearchBar(
            .fillMaxWidth()
            .padding(horizontal = 16.dp, vertical = 8.dp),
        singleLine = true,
-        placeholder = { Text("Search Lidarr for new music") },
+        placeholder = { Text("Search MusicBrainz for new music") },
        keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
        keyboardActions = KeyboardActions(onSearch = { onSubmit() }),
        trailingIcon = {
@@ -173,7 +173,7 @@ private fun SearchBar(
 }
@Composable
-private fun KindChips(kind: LidarrRequestKind, onChange: (LidarrRequestKind) -> Unit) {
+private fun KindChips(kind: RequestKind, onChange: (RequestKind) -> Unit) {
    Row(
        modifier = Modifier
            .fillMaxWidth()
@@ -181,13 +181,13 @@ private fun KindChips(kind: LidarrRequestKind, onChange: (LidarrRequestKind) ->
        horizontalArrangement = Arrangement.spacedBy(8.dp),
    ) {
        FilterChip(
-            selected = kind == LidarrRequestKind.ARTIST,
+            selected = kind == RequestKind.ARTIST,
-            onClick = { onChange(LidarrRequestKind.ARTIST) },
+            onClick = { onChange(RequestKind.ARTIST) },
            label = { Text("Artists") },
        )
        FilterChip(
-            selected = kind == LidarrRequestKind.ALBUM,
+            selected = kind == RequestKind.ALBUM,
-            onClick = { onChange(LidarrRequestKind.ALBUM) },
+            onClick = { onChange(RequestKind.ALBUM) },
            label = { Text("Albums") },
        )
    }
@@ -195,8 +195,8 @@ private fun KindChips(kind: LidarrRequestKind, onChange: (LidarrRequestKind) ->
 /**
 * The snooze surface's data and callbacks, bundled rather than threaded
- * through as four more parameters — the pane grew from one action to three
+ * through as separate parameters: the pane carries three actions, and the
- * with slice 4 and the signatures stopped being readable.
+ * signatures stop being readable otherwise.
 */
 private data class SnoozeUi(
    val locallySnoozedMbids: Set<String>,
@@ -240,9 +240,9 @@ private fun SuggestionsList(
    ) {
        item { SuggestionsHeader() }
        if (items.isEmpty()) {
-            // An empty deck used to mean one thing — no listening signal yet.
+            // An empty deck means one of two things — no listening signal yet,
-            // With snoozing it can also mean "you parked them all", and telling
+            // or "you parked them all" — and telling the second user to go
-            // that user to go listen to something would be wrong advice.
+            // listen to something would be wrong advice.
            item {
                CenteredMessage(
                    if (snoozeUi.snoozes.isEmpty()) {
@@ -316,9 +316,9 @@ private fun SuggestionsHeader() {
@Composable
 private fun ResultsList(
-    rows: List<LidarrSearchResultRef>,
+    rows: List<CatalogueResultRef>,
    locallyRequestedMbids: Set<String>,
-    onRequest: (LidarrSearchResultRef) -> Unit,
+    onRequest: (CatalogueResultRef) -> Unit,
 ) {
    if (rows.isEmpty()) {
        CenteredMessage("Nothing to add for that search yet.")
@@ -25,14 +25,14 @@ import androidx.compose.ui.draw.clip
 import androidx.compose.ui.graphics.vector.ImageVector
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
 import coil3.compose.AsyncImage
 import com.composables.icons.lucide.Clock
 import com.composables.icons.lucide.Disc3
 import com.composables.icons.lucide.Lucide
 import com.composables.icons.lucide.User
 import com.fabledsword.minstrel.models.ArtistSuggestionRef
-import com.fabledsword.minstrel.models.LidarrSearchResultRef
+import com.fabledsword.minstrel.models.CatalogueResultRef
 import com.fabledsword.minstrel.models.SuggestionSnoozeRef
 import com.fabledsword.minstrel.shared.widgets.ServerImage
@Composable
 internal fun SuggestionTile(
@@ -79,8 +79,8 @@ internal fun SuggestionTile(
            IconButton(onClick = onSnooze) {
                Icon(
                    imageVector = Lucide.Clock,
-                    // Rule #101: the label states what happens, and passes no
+                    // The label states what happens and passes no judgement on the
-                    // judgement on the music. Never "not for me".
+                    // music: never "not for me".
                    contentDescription = "Not right now — hide ${s.name} for a while",
                    tint = MaterialTheme.colorScheme.onSurfaceVariant,
                )
@@ -123,7 +123,7 @@ internal fun SnoozedTile(row: SuggestionSnoozeRef, onUnsnooze: () -> Unit) {
@Composable
 internal fun ResultTile(
-    row: LidarrSearchResultRef,
+    row: CatalogueResultRef,
    locallyRequested: Boolean,
    onRequest: () -> Unit,
 ) {
@@ -173,18 +173,19 @@ private fun Avatar(imageUrl: String, fallback: ImageVector, circular: Boolean) {
            .background(MaterialTheme.colorScheme.surfaceVariant),
        contentAlignment = Alignment.Center,
    ) {
-        if (imageUrl.isEmpty()) {
+        // The server hands back its own art endpoint (relative),
        // which answers 404 when no source has an image: ServerImage resolves
        // the path and shows the icon while loading and on a miss.
        ServerImage(
            url = imageUrl,
            contentDescription = null,
            modifier = Modifier.fillMaxSize(),
        ) {
            Icon(
                imageVector = fallback,
                contentDescription = null,
                tint = MaterialTheme.colorScheme.onSurfaceVariant,
            )
        } else {
            AsyncImage(
                model = imageUrl,
                contentDescription = null,
                modifier = Modifier.fillMaxSize(),
            )
        }
    }
 }
@@ -8,8 +8,8 @@ import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.discover.data.DiscoverRepository
 import com.fabledsword.minstrel.discover.data.RequestOutcome
 import com.fabledsword.minstrel.models.ArtistSuggestionRef
-import com.fabledsword.minstrel.models.LidarrRequestKind
+import com.fabledsword.minstrel.models.RequestKind
-import com.fabledsword.minstrel.models.LidarrSearchResultRef
+import com.fabledsword.minstrel.models.CatalogueResultRef
 import com.fabledsword.minstrel.models.SuggestionSnoozeRef
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
@@ -24,7 +24,7 @@ import javax.inject.Inject
 data class DiscoverState(
    val query: String = "",
-    val kind: LidarrRequestKind = LidarrRequestKind.ARTIST,
+    val kind: RequestKind = RequestKind.ARTIST,
    val suggestions: SuggestionState = SuggestionState.Loading,
    val results: ResultsState = ResultsState.Idle,
    val locallyRequestedMbids: Set<String> = emptySet(),
@@ -51,7 +51,7 @@ sealed interface ResultsState {
    /** No active search — the screen shows the suggestion feed. */
    data object Idle : ResultsState
    data object Loading : ResultsState
-    data class Loaded(val items: List<LidarrSearchResultRef>) : ResultsState
+    data class Loaded(val items: List<CatalogueResultRef>) : ResultsState
    data class Error(val message: String) : ResultsState
 }
@@ -68,7 +68,7 @@ class DiscoverViewModel @Inject constructor(
    init {
        loadSuggestions()
-        // Screen-level auto-recovery (issue #1245): re-run whichever pane
+        // Screen-level auto-recovery: re-run whichever pane
        // failed while the server was unreachable once health returns.
        viewModelScope.launch {
            networkStatus.recoveries().collect {
@@ -87,7 +87,7 @@ class DiscoverViewModel @Inject constructor(
        }
    }
-    fun setKind(kind: LidarrRequestKind) {
+    fun setKind(kind: RequestKind) {
        internal.update { it.copy(kind = kind) }
        if (internal.value.query.isNotBlank()) runSearch()
    }
@@ -177,14 +177,14 @@ class DiscoverViewModel @Inject constructor(
     * QUEUED) so the screen can pick the snackbar wording and update
     * the local "requested" overlay.
     */
-    suspend fun requestRow(row: LidarrSearchResultRef): RequestOutcome {
+    suspend fun requestRow(row: CatalogueResultRef): RequestOutcome {
        val kind = internal.value.kind
        val outcome = repository.createRequest(
            kind = kind,
-            artistMbid = if (kind == LidarrRequestKind.ARTIST) row.mbid else row.artistMbid,
+            artistMbid = if (kind == RequestKind.ARTIST) row.mbid else row.artistMbid,
-            artistName = if (kind == LidarrRequestKind.ARTIST) row.name else row.secondaryText,
+            artistName = if (kind == RequestKind.ARTIST) row.name else row.secondaryText,
-            albumMbid = if (kind == LidarrRequestKind.ALBUM) row.mbid else null,
+            albumMbid = if (kind == RequestKind.ALBUM) row.mbid else null,
-            albumTitle = if (kind == LidarrRequestKind.ALBUM) row.name else null,
+            albumTitle = if (kind == RequestKind.ALBUM) row.name else null,
        )
        markRequested(row.mbid)
        return outcome
@@ -192,7 +192,7 @@ class DiscoverViewModel @Inject constructor(
    suspend fun requestSuggestion(s: ArtistSuggestionRef): RequestOutcome {
        val outcome = repository.createRequest(
-            kind = LidarrRequestKind.ARTIST,
+            kind = RequestKind.ARTIST,
            artistMbid = s.mbid,
            artistName = s.name,
        )
@@ -1,14 +1,18 @@
 package com.fabledsword.minstrel.events
 import com.fabledsword.minstrel.auth.AuthStore
 import com.fabledsword.minstrel.connectivity.ConnectivityObserver
 import com.fabledsword.minstrel.di.ApplicationScope
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.channels.BufferOverflow
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharedFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.launch
@@ -28,9 +32,6 @@ import javax.inject.Singleton
 private const val SSE_PATH = "/api/events/stream"
 private const val EVENTS_BUFFER_CAPACITY = 64
 private const val BASE_BACKOFF_MS = 1_000L
 private const val MAX_BACKOFF_MS = 30_000L
 private const val BACKOFF_FACTOR = 2
 /**
 * Long-lived SSE subscription to `GET /api/events/stream`. Exposes
@@ -45,11 +46,16 @@ private const val BACKOFF_FACTOR = 2
 * - No client-side timeout — the server emits 15s heartbeats which
 *   okhttp-sse handles transparently.
 * - Reconnect-with-backoff: if the stream drops mid-session (server
- *   restart, network blip) it reconnects with exponential backoff
+ *   restart, network blip) it reconnects after [ReconnectBackoff]'s
- *   (1s → 2s → … → 30s cap), reset to 1s on a successful open. Only
+ *   jittered wait (2s doubling to 5 min), reset on a successful open.
 *   A network coming up reconnects at once: the callback is a hint, and
 *   the only test of whether the server is reachable is trying it. Only
 *   reconnects while still signed in; a sign-out cancels the pending
 *   retry. Without this a single blip silently kills cross-device
 *   reactivity until the next app launch.
 * - [connected] says whether a stream is open. Background delivery
 *   catches up on every rising edge: nothing replays a
 *   frame sent while the stream was down.
 *
 * The URL passes through the placeholder host that
 * `BaseUrlInterceptor` rewrites — same mechanism the rest of the
@@ -62,6 +68,7 @@ class EventsStream @Inject constructor(
    @ApplicationScope private val scope: CoroutineScope,
    private val okHttpClient: OkHttpClient,
    private val json: Json,
    private val connectivity: ConnectivityObserver,
 ) {
    private val factory = EventSources.createFactory(okHttpClient)
@@ -72,10 +79,13 @@ class EventsStream @Inject constructor(
    )
    val events: SharedFlow<LiveEvent> = emitter.asSharedFlow()
    private val connectedState = MutableStateFlow(false)
    val connected: StateFlow<Boolean> = connectedState.asStateFlow()
    private var currentSource: EventSource? = null
    @Volatile private var signedIn = false
    private var reconnectJob: Job? = null
-    private var backoffMs = BASE_BACKOFF_MS
+    private var backoffMs = ReconnectBackoff.BASE_MS
    init {
        scope.launch {
@@ -85,13 +95,30 @@ class EventsStream @Inject constructor(
                .collect { isSignedIn ->
                    signedIn = isSignedIn
                    if (isSignedIn) {
-                        backoffMs = BASE_BACKOFF_MS
+                        backoffMs = ReconnectBackoff.BASE_MS
                        connect()
                    } else {
                        disconnect()
                    }
                }
        }
        scope.launch {
            connectivity.online.collect { up -> if (up) reconnectNow() }
        }
    }
    /**
     * Cuts a pending backoff short: reconnects at once and starts the ladder
     * over. For a network that has just come up, or the app coming to the
     * foreground, where waiting out a five-minute backoff would leave the
     * server unheard from for nothing. Does nothing while a stream is open or
     * opening.
     */
    @Synchronized
    fun reconnectNow() {
        if (!signedIn || reconnectJob?.isActive != true) return
        backoffMs = ReconnectBackoff.BASE_MS
        connect()
    }
    @Synchronized
@@ -106,20 +133,22 @@ class EventsStream @Inject constructor(
        reconnectJob?.cancel()
        currentSource?.cancel()
        currentSource = null
        connectedState.value = false
    }
    /**
-     * Schedule a reconnect after the current backoff, then double it
+     * Schedule a reconnect after the current backoff, jittered, then
-     * (capped). No-op when signed out — sign-out's [disconnect]
+     * double it (capped). No-op when signed out — sign-out's [disconnect]
     * cancels the pending job. A successful [Listener.onOpen] resets
     * the backoff to the floor.
     */
    @Synchronized
    private fun scheduleReconnect() {
        connectedState.value = false
        if (!signedIn) return
        reconnectJob?.cancel()
-        val waitMs = backoffMs
+        val waitMs = ReconnectBackoff.jittered(backoffMs)
-        backoffMs = (backoffMs * BACKOFF_FACTOR).coerceAtMost(MAX_BACKOFF_MS)
+        backoffMs = ReconnectBackoff.next(backoffMs)
        reconnectJob = scope.launch {
            delay(waitMs)
            if (signedIn) connect()
@@ -136,7 +165,8 @@ class EventsStream @Inject constructor(
    private inner class Listener : EventSourceListener() {
        override fun onOpen(eventSource: EventSource, response: Response) {
-            backoffMs = BASE_BACKOFF_MS
+            backoffMs = ReconnectBackoff.BASE_MS
            connectedState.value = true
        }
        override fun onEvent(
@@ -4,8 +4,7 @@ import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.JsonObject
 /**
- * Parsed event from the server's SSE stream. Mirrors
+ * Parsed event from the server's SSE stream.
 * the Flutter client's `LiveEvent`.
 *
 * - [kind] is the SSE `event:` field (e.g. "track.liked", "playlist.deleted").
 * - [userId] is the actor whose user-scoped state changed (empty for
@@ -5,6 +5,7 @@ import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.ProcessLifecycleOwner
 import com.fabledsword.minstrel.di.ApplicationScope
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.notifications.data.NotificationsRepository
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.launch
 import javax.inject.Inject
@@ -30,6 +31,7 @@ import javax.inject.Singleton
 class LiveEventsDispatcher @Inject constructor(
    private val eventsStream: EventsStream,
    private val likes: LikesRepository,
    private val notifications: NotificationsRepository,
    @ApplicationScope private val scope: CoroutineScope,
 ) : DefaultLifecycleObserver {
@@ -49,6 +51,8 @@ class LiveEventsDispatcher @Inject constructor(
            "artist.liked",
            "artist.unliked",
            -> refreshLikes()
            // a contentless nudge; the inbox refetches its newest page.
            "notification.created" -> refreshNotifications()
        }
        // Other kinds (playlist.*, quarantine.*, request.status_changed,
        // scan.*) reach screen-scoped subscribers via EventsStream
@@ -58,9 +62,18 @@ class LiveEventsDispatcher @Inject constructor(
    override fun onStart(owner: LifecycleOwner) {
        // App returned to the foreground. SSE will catch up but might
-        // not have reconnected yet; flush the cross-screen refreshes
+        // not have reconnected yet (it may be deep in its backoff, so it
        // is told to try now); flush the cross-screen refreshes
        // defensively.
        eventsStream.reconnectNow()
        refreshLikes()
        refreshNotifications()
    }
    private fun refreshNotifications() {
        scope.launch {
            runCatching { notifications.refresh() }
        }
    }
    private fun refreshLikes() {
--- a/Show More
+++ b/Show More