chore(deps): update dependency tailwindcss to v4

Merges Renovate's three branches (PRs #145, #146, #147), which fail
alone: vite-plugin-svelte 7 requires vite 8, and vitest 5 is the vitest
for vite 8. Renovate changed only package.json, so npm ci failed on each.

The lockfile is regenerated for just these packages: the stale entries
for vite, vitest, @vitest/* and vite-plugin-svelte (with its old
inspector) were dropped and re-resolved, leaving everything else locked.
SvelteKit stays on 2.70.3, which accepts vite 8 and plugin 7. Vite 8
builds with Rolldown, so esbuild moves to 0.28 and rollup leaves the tree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.dockerignore

@@ -6,10 +6,20 @@
 **/build
 web/build
 
-# Flutter mobile client — built separately on developer machines / Flutter CI.
-# Including it in the Go build context wastes ~70 files and invalidates the
-# `COPY . .` layer cache on every Flutter-only change.
-flutter_client/
+# The Android client — built by its own job, never from this context. The APK
+# reaches the image through client/, downloaded as a CI artifact, so nothing
+# here reads android/ sources.
+#
+# This block named `flutter_client/` until 2026-09-10 and lost its PATTERN when
+# that tree was deleted, leaving a comment describing an exclusion that was no
+# longer happening. android/ never took its place, so 4.1 MB of Gradle project
+# has been entering the context and busting 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/
@@ -27,5 +37,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/

.gitea/workflows/android.yml

@@ -1,89 +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'
-        # Gitea Actions runs in GHES-emulation mode; @actions/artifact v2+
-        # (i.e. upload-artifact@v4+) errors with "GHESNotSupportedError".
-        # Pin to @v3 until act_runner or the artifact backend catches up.
-        uses: actions/upload-artifact@v3
-        with:
-          name: minstrel-android-debug-${{ github.sha }}
-          path: android/app/build/outputs/apk/debug/app-debug.apk

.gitea/workflows/release.yml

@@ -2,47 +2,407 @@ name: release
 
 # Builds and pushes the minstrel container image to the Gitea registry.
 #
-#   push to main             → :main and :latest (no APK bundled)
-#   push tag vYYYY.MM.DD     → :vYYYY.MM.DD and :latest (APK bundled)
-#   workflow_dispatch        → manual trigger (same rules based on the ref)
+#   push to dev                  → :dev            (freshly-built dev APK bundled)
+#   push to main                 → :latest + :<sha> (latest-release APK bundled)
+#   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
-# 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
-# the same name gets overwritten. :latest is updated by every main push
-# AND every tag push, so it always reflects the newest blessed image.
+# That is the whole tag map, and it is family rule 145 + 147 as written.
+#
+# :<sha> on main is the ROLLBACK UNIT — every production commit addressable
+# without a release ceremony. It is minted only on main, where rollback is
+# actually worth having: merges are gated (rule 2) 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. This repo published :vYYYY.MM.DD.HHMM
+# until 2026-09-10 and it was the inverse of the rule on both counts — minting
+# a version tag nobody pinned while the rollback unit the rule names did not
+# exist here at all. 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. Operator, 2026-09-10: "only things like the APK need that kind
+# of versioning for their update process."
+#
+# There is no :main either. :latest tracks main's tip with no gate between them
+# (rule 147), 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.
+# Before it, the only way to get an APK onto a phone was to cut a release,
+# which made `main` the staging area by default. `: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.
+#
+# Note what this repo does NOT need: a cross-repo dispatch to refresh the
+# channel when its bundled APK is rebuilt. That mechanism exists elsewhere in
+# the family because the app and the server live in separate repos. Minstrel
+# is a monorepo — one push builds the APK and the image in the same run from
+# the same commit, so the channel cannot go stale against its own artifact.
+# The requirement is satisfied structurally; copying the mechanism would add
+# a moving part to fix a problem that does not exist here.
+#
+# 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.
+#
+# This block used to say the opposite: that the per-day tag was
+# "intentionally mutable" and that a same-day re-cut should
+# `git push -f origin vYYYY.MM.DD`. That instruction is what the family
+# rulebook now forbids outright, and it has incidents behind it — moving a
+# same-day tag forward once took a published release down with it. Anyone
+# installing from a tag is holding 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
-# happens in the same android-release job, so the Release-page download
-# link and the in-image bundled APK are both populated atomically.
+# race, no silent-failure mode. Attaching the APK to the gitea Release is
+# its own job (release-assets), behind the test gate below.
 #
-# Android testing (lint + detekt + unit tests, debug APK upload on main)
-# lives in android.yml and runs independently on every push.
+# :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 the version sidecar published beside it — the recorded values, not
+# recomputed ones — so no rebuild is needed, just a rebundle. Tag builds
+# keep bundling their own freshly-built APK.
+#
+# THE GATE (rule 177, M462 #4984). Every verifying lane lives in this file —
+# 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.
+#
+# They used to be three separate workflows (test-go, test-web, android) on the
+# same push trigger as this one. Separate workflows cannot see each other's
+# verdict, so :dev meant "it built", never "it passed": 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
-# supersede the in-flight build — the operator explicitly wants the
-# later commit to win.
+# A rapid re-push to main should supersede the in-flight build — the
+# operator explicitly wants the later commit to win. Tags no longer enter
+# into this: they are immutable and unique, so no tag build can ever be
+# superseded by 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 the operator's 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 disaster Fable #339 exists to prevent).
+  #
+  # The key stays `integration` with no `name:` (rule 80): 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 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 connections. Asked of the service
+          # container itself: the run: shell is dash (rule 81), where the
+          # old `/dev/tcp` probe never connects and the loop silently
+          # burned its full two minutes on every run.
+          ready=""
+          for i in $(seq 1 60); do
+            if docker exec "$PG_ID" pg_isready -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 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).
+          # -timeout 20m: internal/api alone takes ~6.5 min under -race on
+          # an idle runner, and a dev and a main run sharing the runner
+          # pushed it past go test's default 10m (run 8368, 600.016s, the
+          # running test 2s old — 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
+
+      # What ships to browsers: `dependencies` and the runtime they pull in
+      # (svelte, devalue). Build and test tooling (vite, vitest, tailwind,
+      # kit's dev server) is left out because none of it reaches a user, and
+      # its open advisories need major-version upgrades tracked separately.
+      - name: npm audit (shipped dependencies)
+        run: npm audit --omit=dev --audit-level=moderate
+
+      - name: Type-check + svelte-check
+        run: npm run check
+
+      - name: Vitest
+        run: npm test
+
+  android:
+    # Using flutter-ci runner label because it's 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. Main used to upload a
+      # debug-signed app-debug.apk: a build signed by a key regenerated in
+      # every container, which no install can update (family idea #5103,
+      # practice 2). 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 (rule 154): 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 (rule 81).
+      - 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)
-    if: startsWith(github.ref, 'refs/tags/v')
+    name: Build signed APK (releases and dev)
+    # 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 was 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
@@ -67,14 +427,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
-          # would return 1 for `git rev-list --count HEAD`, breaking the
-          # iteration suffix.
+          # Full history. The version name now reads only the tip commit's
+          # timestamp, so a shallow clone would technically serve — but this
+          # 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
@@ -83,12 +447,49 @@ jobs:
         working-directory: ${{ github.workspace }}
         run: |
           set -euo pipefail
-          TAG="${GITHUB_REF#refs/tags/v}"
-          COMMIT_COUNT=$(git rev-list --count HEAD)
-          VERSION_NAME="${TAG}.${COMMIT_COUNT}"
-          echo "name=${VERSION_NAME}" >> "$GITHUB_OUTPUT"
-          echo "code=${COMMIT_COUNT}" >> "$GITHUB_OUTPUT"
-          echo "::notice::APK version: ${VERSION_NAME} (code=${COMMIT_COUNT})"
+          # The derivation lives in ci/version.sh, not here, so it can be
+          # executed by a test on every push. Anything inline in this file is
+          # unverifiable until a release is already running.
+          out="$(ci/version.sh HEAD)"
+          printf '%s\n' "${out}" >> "$GITHUB_OUTPUT"
+
+          # 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
+      # APK for several minutes first and only then discovered it had 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:
+          CI_TOKEN: ${{ secrets.CI_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF#refs/tags/}"
+          if ! curl -fsSL -o /dev/null \
+            -H "Authorization: token ${CI_TOKEN}" \
+            "https://git.fabledsword.com/api/v1/repos/${GITHUB_REPOSITORY}/releases/tags/${TAG}"; then
+            echo "::error::no release exists for ${TAG}. Create the release (which creates the tag) rather than pushing a bare tag — otherwise there is nothing to attach the APK to."
+            exit 1
+          fi
+          echo "::notice::release found for ${TAG}"
 
       - name: Cache Gradle dirs
         uses: actions/cache@v4
@@ -122,25 +523,113 @@ 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 (family idea
+      # #5103, practice 3). 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. Read from run 8446 (#5116).
+          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
-        # @v3 because Gitea Actions emulates GHES and the v2 artifact
-        # backend used by upload-artifact@v4 errors with GHESNotSupportedError.
-        uses: actions/upload-artifact@v3
+        # Stock action (snippet #2271) — never @v3, which uploads something Gitea
+        # will never serve back. This is the producing half of a pair:
+        # image-release downloads `minstrel-apk` below. Any upload v4+ pairs with
+        # any download v4+ on this forge (every combination tested 2026-09-10,
+        # Scribe spike #3843), so the two pins need not move together.
+        uses: actions/upload-artifact@v7
         with:
           name: minstrel-apk
           path: android/app/build/outputs/apk/release/app-release.apk
+          # error, not the default warn: image-release hard-depends on this
+          # 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}")"
@@ -162,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
-    # runs and must succeed before this job starts — guaranteeing the
-    # APK artifact is present. For main pushes android-release is
-    # skipped; the `if: ...` below lets this job run anyway and the
-    # download/copy steps gate themselves on the tag context.
-    needs: [android-release]
-    if: ${{ !failure() && !cancelled() }}
+    # Every lane must have SUCCEEDED, each named here (rule 177). Then the
+    # APK: tag and dev pushes build one and it must have succeeded; main
+    # pushes skip android-release and bundle the latest release's APK
+    # instead, so for main alone a skipped android-release is expected.
+    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'
+      || (needs.android-release.result == 'skipped' && github.ref == 'refs/heads/main')) }}
     runs-on: go-ci
     container:
       image: git.fabledsword.com/bvandeusen/ci-go:1.26
@@ -181,6 +692,17 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          # Full history, and rule 149 names this specifically: any job that
+          # DERIVES the version name needs it, because a shallow clone changes
+          # what git-derived values resolve to WITHOUT failing — a too-low
+          # value, silently, with every lane green.
+          #
+          # This job was depth-1 while it took the version from GITHUB_REF. It
+          # now runs ci/version.sh itself, because with :<version> image tags
+          # gone the server's self-reported version is the only thing that says
+          # which build an image is.
+          fetch-depth: 0
 
       - name: Detect buildable project
         id: guard
@@ -198,21 +720,68 @@ jobs:
         if: steps.guard.outputs.ready == 'true'
         shell: bash
         run: |
-          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
-            VERSION="${GITHUB_REF#refs/tags/}"
-            echo "args=-t ${IMAGE}:${VERSION} -t ${IMAGE}:latest" >> "$GITHUB_OUTPUT"
-            echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
-            echo "::notice::Release build: ${VERSION} + latest"
-          else
-            # Main is the protected, post-PR-merge branch. Treat it as the
-            # rolling stable channel — every main push moves :latest.
-            # Pinned consumers can target :vYYYY.MM.DD; everyone else
-            # gets the newest main.
-            echo "args=-t ${IMAGE}:main -t ${IMAGE}:latest" >> "$GITHUB_OUTPUT"
-            echo "version=main" >> "$GITHUB_OUTPUT"
-            echo "::notice::Main-branch build: :main + :latest"
+          set -euo pipefail
+
+          # THE VERSION, and it is derived the same way on every ref — the
+          # branch decides the CHANNEL, never the version (family rule 149).
+          #
+          # This used to be three different things: the literal string "main"
+          # on main, "dev" on dev, and the tag name on a tag. None of them
+          # ordered, and the first two were the same string forever — two dev
+          # images eight weeks apart were indistinguishable in the UI. That
+          # mattered little while :vYYYY.MM.DD.HHMM existed to identify a
+          # build; with version image tags gone, this IS how an operator tells
+          # which build a container is running.
+          #
+          # `sed -n s///p` rather than `grep`: it exits 0 when nothing matches,
+          # so the empty check below is actually reachable. A grep here would
+          # kill the step at the assignment under the runner's pipefail — the
+          # exact bug that took down the first main build after the version
+          # rework.
+          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.
+            # Rule 145 is explicit about that case: 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 (rule 146).
+            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 (rule 147) and
+            # :<sha> is the rollback unit (rule 145). Full 40-char SHA, matching
+            # the family's other repos, 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
@@ -221,35 +790,201 @@ jobs:
             | docker login git.fabledsword.com -u "${{ github.actor }}" --password-stdin
 
       - name: Download signed APK artifact
-        # Tag pushes only — android-release just produced this. Main
-        # pushes skip and the image ships with empty client/ (the
-        # /api/client/version endpoint then returns 404 by design).
-        if: steps.guard.outputs.ready == 'true' && startsWith(github.ref, 'refs/tags/v')
-        uses: actions/download-artifact@v3
+        # Tag and dev pushes — android-release just produced this. Only `main`
+        # takes the "Bundle latest release APK" path below, because it is the
+        # one ref that moves a channel without building an APK of its own.
+        if: >-
+          steps.guard.outputs.ready == 'true' &&
+          (startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/dev')
+        # 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
+        # out of the bundle; snippet #2271). v8 runs on node24, which every
+        # CI-runner image carries — the runner uses the image's own node.
+        uses: actions/download-artifact@v8
         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
-          # sidecar string the server hands clients matches the
-          # versionName baked into the APK they're comparing against.
+          # All three pulled from android-release's outputs so the sidecar the
+          # server hands clients matches exactly what is baked into the APK
+          # 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
+        # the sidecar published beside it, so what the server reports is what
+        # that build actually recorded rather than something re-derived here.
+        # Degrades to an empty client/ (404 update channel) — never a wrong
+        # version — if no release or APK asset can be resolved. That
+        # 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 }}
+        run: |
+          set -eu
+          REPO="${GITHUB_REPOSITORY}"
+          REL_JSON="$(curl -fsSL -H "Authorization: token ${CI_TOKEN}" \
+            "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/latest" || true)"
+          if [ -z "${REL_JSON}" ]; then
+            echo "::notice::no published release — image ships without bundled APK"; exit 0
+          fi
+          # `|| true` on every one of these, and it is load-bearing rather
+          # 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
+          curl -fsSL -H "Authorization: token ${CI_TOKEN}" -o client/minstrel.apk "${APK_URL}"
+
+          # Take the version the release RECORDED rather than recomputing it.
+          # This used to re-derive the name from the tagged commit, which meant
+          # the formula lived in two files that had to be kept in step, and it
+          # could only ever recover the name — the ordering key is build-time
+          # minutes and does not exist anywhere 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
+  # started — no log was written at all — so all eight of its steps reported
+  # `failure` with none executed and image-release showed `skipped`. The run was
+  # red, but the *release page rendered fine*, and `main`'s own push build had
+  # already moved `:latest`, so the code was deployable and nothing looked
+  # obviously wrong. The release was simply missing its APK and its image,
+  # which is easy to skim past.
+  #
+  # This job cannot prevent that (the cause was a runner failing to launch, not
+  # anything in this file). What it does is turn an incomplete release into an
+  # 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, release-assets, image-release]
+    if: ${{ always() && startsWith(github.ref, 'refs/tags/v') }}
+    runs-on: go-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-go:1.26
+
+    steps:
+      - name: Release must have an APK attached
+        shell: bash
+        env:
+          CI_TOKEN: ${{ secrets.CI_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF#refs/tags/}"
+          REPO="${GITHUB_REPOSITORY}"
+
+          REL_JSON="$(curl -fsSL \
+            -H "Authorization: token ${CI_TOKEN}" \
+            "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/tags/${TAG}" || true)"
+          if [ -z "${REL_JSON}" ]; then
+            echo "::error::no release found for ${TAG} — the tag exists but nothing was published"
+            exit 1
+          fi
+
+          APK="$(printf '%s' "${REL_JSON}" \
+            | grep -oP '"browser_download_url":\s*"\K[^"]+' \
+            | grep -E '\.apk$' | head -1 || true)"
+          if [ -z "${APK}" ]; then
+            echo "::error::release ${TAG} has NO APK attached — in-app update will offer nothing, and the bundled-APK path on future :latest builds has no source."
+            echo "::error::Fix by RE-RUNNING this workflow run. Do NOT delete and re-create the tag; if it fails again the runner never started the container, and the evidence is in act_runner on the host (Gitea will hold no job log)."
+            exit 1
+          fi
+
+          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
+      # missing when v2026.08.07 had to be re-cut. `always()` on this job means
+      # it runs even when image-release failed, so without this the guard would
+      # cheerfully verify an incomplete release.
+      #
+      # This asserted `:${TAG}` — the :vYYYY.MM.DD.HHMM image — until
+      # 2026-09-10. Version image tags are no longer published (rule 145), so
+      # that assertion would now fail every release for a tag nothing mints.
+      # The rollback target it was really protecting is the :<sha> image, which
+      # main's own build published for this same commit before the tag was cut.
+      #
+      # Checking it here earns its keep twice over: it still catches an image
+      # push that silently did not happen, and it additionally 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
+          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}:${GITHUB_SHA}" > /dev/null 2>&1; then
+            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::rollback target verified: ${IMAGE}:${GITHUB_SHA}"

.gitea/workflows/test-go.yml

@@ -1,125 +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'
-      - '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: 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
-
-          # 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 ./...

.gitea/workflows/test-web.yml

@@ -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

.gitignore

@@ -12,6 +12,11 @@
 # Test binary, built with `go test -c`
 *.test
 
+# `make build` output. bin/minstrel was tracked until 2026-09-10 — an 18 MB
+# binary committed by accident, last refreshed by a commit about web test
+# mocks, and re-dirtied by every local build since.
+bin/
+
 # Bundled Android APK + version sidecar (#397). Populated by CI for
 # tag releases; never committed. README in client/ explains the flow.
 client/minstrel.apk
@@ -52,20 +57,6 @@ GEMINI.md
 .windsurfrules
 .aider.conf.yml
 
-# Flutter
-flutter_client/.dart_tool/
-flutter_client/.flutter-plugins
-flutter_client/.flutter-plugins-dependencies
-flutter_client/build/
-flutter_client/.idea/
-flutter_client/ios/Podfile.lock
-flutter_client/ios/Pods/
-flutter_client/android/.gradle/
-flutter_client/android/app/build/
-flutter_client/android/local.properties
-flutter_client/android/key.properties
-flutter_client/*.iml
-
 # Native Android (Kotlin/Compose) — M8 rewrite
 android/.gradle/
 android/.kotlin/

Dockerfile

@@ -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,32 @@ 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
-# build-arg; local `docker build` falls back to "dev". Surfaced at
-# /healthz for operator-side image-version verification.
+# Version stamping. release.yml passes the DERIVED version name
+# (YYYY.MM.DD.HHMM) and the lane's channel; a local `docker build` falls back
+# to "dev"/"local". Both are surfaced at /healthz.
+#
+# These are two values on purpose (family rule 149): 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 is what the rule forbids — the version
+# used to BE the channel word here ("main"/"dev"), which meant two dev images
+# eight weeks apart were 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/server.ServerVersion=${MINSTREL_VERSION}' \
+      -X 'git.fabledsword.com/bvandeusen/minstrel/internal/server.ServerChannel=${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 (M400). Both are baked in at build time so a
+# deployed instance never fetches either (rule 164); 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 \

Makefile

@@ -1,10 +1,34 @@
-.PHONY: generate test test-short test-integration lint build
+.PHONY: generate generate-go verify-generate test test-short test-integration lint build
 
+# renovate: datasource=docker depName=sqlc/sqlc
 SQLC_VERSION := 1.31.1
 
+# Local codegen. Containerised so a dev needs no sqlc install.
 generate:
 	docker run --rm -v "$(CURDIR):/src" -w /src sqlc/sqlc:$(SQLC_VERSION) generate
 
+# Same codegen, run as a Go tool instead of a container. This is the CI path:
+# the ci-go image already has Go, so it avoids docker-in-docker. Pinned to the
+# SAME version as `generate` above so both routes emit identical output.
+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.
+#
+# 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.
+verify-generate: generate-go
+	# -N (intent-to-add) so a BRAND-NEW generated file is visible to `git
+	# diff`, which otherwise ignores untracked paths entirely — a whole
+	# missing *.sql.go would sail through the check below.
+	git add -N -- internal/db/dbq
+	git --no-pager diff -- internal/db/dbq
+	git diff --quiet -- internal/db/dbq
+
 test:
 	go test -race ./...
 

README.md

@@ -4,16 +4,28 @@ A self-hosted music server that thinks for you. Smart shuffle, contextual likes,
 
 > State and intelligence belong on the server, not the client.
 
-<!-- TODO: screenshot of the home page -->
+<a href="docs/screenshots/home.png"><img src="docs/screenshots/home.png" width="820" alt="Minstrel home — your library at a glance"></a>
 
 ## Highlights
 
 - **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.
+- **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.
-- **Flutter mobile client in flight.** Tracking issue [#356](https://git.fabledsword.com/bvandeusen/minstrel/issues/356).
+- **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
 
@@ -22,12 +34,27 @@ A self-hosted music server that thinks for you. Smart shuffle, contextual likes,
 services:
   minstrel:
     image: git.fabledsword.com/bvandeusen/minstrel:latest
+    # Reachable from your LAN at http://<host>:4533. If this host faces the
+    # internet, bind it to 127.0.0.1 and put an HTTPS proxy in front instead:
+    # see docs/hosting.md.
     ports: ['4533:4533']
     volumes:
-      - ./music:/music:ro
-      - minstrel-data:/data
+      # Your music library. Point ./music at wherever your audio files
+      # live. Writable, because Minstrel deletes a file when an admin asks
+      # it to (for example, quarantine's "Delete file"). It never moves,
+      # renames or retags anything. The container runs as uid 1000, so that
+      # user needs write access to the folders. Mount it :ro to forbid even
+      # deletes: those actions then refuse, say why, and delete nothing.
+      - ./music:/music
+      # 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 music mount above (/music here).
       MINSTREL_LIBRARY_SCAN_PATHS: /music
     depends_on: [db]
 
@@ -37,6 +64,8 @@ services:
       POSTGRES_USER: minstrel
       POSTGRES_PASSWORD: minstrel
       POSTGRES_DB: minstrel
+    # Postgres data dir — users, likes, play history, sessions, settings.
+    # The one volume you must never lose; back it up with pg_dump.
     volumes: [pgdata:/var/lib/postgresql/data]
 
 volumes:
@@ -48,16 +77,40 @@ volumes:
 docker compose up -d
 ```
 
-After the stack is up, visit `http://localhost:4533/register` and create your admin account. The first user to register on a fresh instance is automatically marked as the administrator; subsequent users can register through the same form (or via invite tokens generated from the admin Users panel, depending on how you configure registration).
+## First run
+
+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 on a network you trust; a server reachable from the internet belongs behind HTTPS, which [docs/hosting.md](docs/hosting.md) walks through.
+
+**1. Create your admin account.** Visit `http://localhost:4533/register`. The first account on a fresh instance becomes the administrator, and creating it asks for the **setup token** the server prints in its log (`docker compose logs minstrel | grep setup_token`), so nobody else can claim a newly exposed server first. Later users join through the same form or an invite token (step 5).
+
+<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>
+
+**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).
 
+Hosting Minstrel on the internet: see [docs/hosting.md](docs/hosting.md). What Minstrel does to protect accounts, and why: [docs/security.md](docs/security.md).
+
 ## Configuration
 
 Most operators only need the env vars in the quickstart above. A few extras worth knowing:
 
 - `MINSTREL_BRANDING_APP_NAME` — rename the instance ("Family Jukebox", "Office Music"). Surfaces in the header, browser tab, and OG share previews.
-- `MINSTREL_STORAGE_DATA_DIR` — defaults to `./data`. Holds playlist cover collages and other generated artefacts.
+- `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`).
 
 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.
@@ -66,8 +119,23 @@ Most operational keys have a `MINSTREL_<SECTION>_<FIELD>` env override. Recommen
 
 ## Updating
 
-- `:main` — rolling, follows the dev branch's tested tip. Recommended only for the operator who's running an upstream-watching deployment.
-- `:v1.0.x` — pinned releases. Recommended default. Database migrations run automatically at startup; rollbacks require restoring a Postgres dump.
+Image tags (`git.fabledsword.com/bvandeusen/minstrel:<tag>`):
+
+- `:latest` — production. Tracks `main`'s tip and moves on every `main` push and every release. What most operators should run.
+- `:<commit-sha>` — the rollback unit. Every `main` push publishes one, so any production commit is addressable without a release ceremony. Immutable: a given SHA tag is never re-pushed. Pin one if you need a deployment that cannot change under you, and use it to roll back.
+- `:dev` — the rolling test channel, rebuilt on every push to `dev` and carrying its own freshly-built Android APK. Run this to try something before it ships. It moves constantly, has no per-commit tag, and its only recovery path is forward — if a `:dev` image is broken, the fix is the next push, not a rollback.
+
+That is the whole tag map. **There are no version-numbered image tags**, and no `:main`. Git and the build's own self-reported version answer "which build is this" — the Settings page shows it, and so does `/healthz`. Release *tags* in git are still `vYYYY.MM.DD.HHMM`; they name a changelog entry and the APK attached to it, not an image.
+
+Rolling back to `:<commit-sha>` pins the **server code** at that commit — not the server-and-app pair. The Android APK is baked in at image build time, so a SHA image carries whichever app was current when that commit was built, which may be older than what `:latest` bundles now. If both halves matter, check what the image bundles rather than trusting the tag's name.
+
+Every `:latest`, `:<commit-sha>` and `:dev` bundles a signed Android APK, so the in-app update channel is always live. All are signed with the same key, so a phone can move between the stable and dev channels without uninstalling — point it at a `:dev` server and the in-app updater offers that channel's build.
+
+The app reports which channel it is on alongside its version, and decides whether an update is available using the build's ordering key rather than its displayed name — the same value Android installs by, so an offer it makes is one the platform will accept.
+
+Database migrations run automatically at startup; rollbacks require restoring a Postgres dump.
+
+Releases up to 2026-09-10 also published a `:vYYYY.MM.DD[.HHMM]` image tag. Those images still exist and still work — they are simply not extended.
 
 ## Specs
 
@@ -91,7 +159,8 @@ Two concurrent dev processes:
   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`).
+  job with its own ephemeral Postgres (the `integration` lane in
+  `.gitea/workflows/release.yml`, which also gates every image publish).
 
 ### Production build
 
@@ -101,7 +170,7 @@ Two concurrent dev processes:
 
 - 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.
+- Releases are cut by tagging `v*` off `main`; the release workflow builds the signed APK, attaches it to the release, and refreshes `:latest` around it.
 
 Task and milestone tracking: Fable (`Minstrel` project, id 12).
 

android/.idea/caches/deviceStreaming.xml

@@ -1754,6 +1754,19 @@
           <option name="screenX" value="1600" />
           <option name="screenY" value="2560" />
         </PersistentDeviceSelectionData>
+        <PersistentDeviceSelectionData>
+          <option name="api" value="36" />
+          <option name="brand" value="google" />
+          <option name="codename" value="tangorpro" />
+          <option name="formFactor" value="Tablet" />
+          <option name="id" value="tangorpro" />
+          <option name="labId" value="google" />
+          <option name="manufacturer" value="Google" />
+          <option name="name" value="Pixel Tablet" />
+          <option name="screenDensity" value="320" />
+          <option name="screenX" value="1600" />
+          <option name="screenY" value="2560" />
+        </PersistentDeviceSelectionData>
         <PersistentDeviceSelectionData>
           <option name="api" value="35" />
           <option name="brand" value="google" />

android/.idea/misc.xml

@@ -1,4 +1,3 @@
-<?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="ExternalStorageConfigurationManager" enabled="true" />
   <component name="ProjectRootManager" version="2" languageLevel="JDK_21" default="true" project-jdk-name="jbr-21" project-jdk-type="JavaSDK">

android/app/build.gradle.kts

@@ -21,13 +21,24 @@ android {
         applicationId = "com.fabledsword.minstrel"
         minSdk = 26
         targetSdk = 36
-        // versionName / versionCode are released-build values injected by
-        // CI from the git tag + commit count. Local / debug builds fall
-        // back to "dev" so the About card reads honestly. Releases ship
-        // versionName="YYYY.MM.DD.<commits>" (e.g. "2026.06.02.142") and
-        // versionCode=<commits>, which is monotonic forever and lets the
-        // shared isVersionNewer comparator distinguish two same-day
-        // re-cuts (the iteration suffix differs).
+        // versionName / versionCode are released-build values injected by CI.
+        // Local / debug builds fall back to "dev" so the About card reads
+        // honestly.
+        //
+        // versionName is "YYYY.MM.DD.HHMM" from the COMMIT's timestamp, so
+        // every lane building this source reports the same string and the
+        // 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.
+        //
+        // This comment used to say versionCode was a commit count and that it
+        // was "monotonic forever". It was neither — a commit count runs ahead
+        // on `dev`, so a dev build outranked the `main` release meant to
+        // replace it and Android refused the install as a downgrade. Worth
+        // knowing the claim was here, stated as a reassurance, while the bug
+        // it denied was live.
         val versionNameOverride =
             (project.findProperty("MINSTREL_VERSION_NAME") as String?)?.takeIf { it.isNotBlank() }
         val versionCodeOverride =
@@ -61,9 +72,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 made a missing secret into a published APK that no
+            // install could ever update (family idea #5103, practice 2). 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 +165,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)
 
@@ -210,4 +224,17 @@ dependencies {
     debugImplementation(libs.compose.ui.test.manifest)
 }
 
-tasks.withType<Test> { useJUnitPlatform() }
+tasks.withType<Test> {
+    useJUnitPlatform()
+    // Print the assertion message + full stack trace for failures. The
+    // default console output gives only "AssertionError at Foo.kt:12", and
+    // for a failure inside a `runTest { }` lambda even that line collapses
+    // to the test function's own line (the assertion frames live in the
+    // suspend-lambda class, which Gradle filters out) — leaving nothing to
+    // debug from when the HTML report isn't reachable, as in CI.
+    testLogging {
+        events("failed")
+        exceptionFormat = org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
+        showStackTraces = true
+    }
+}

android/app/schemas/com.fabledsword.minstrel.cache.db.AppDatabase/6.json

@@ -0,0 +1,690 @@
+{
+  "formatVersion": 1,
+  "database": {
+    "version": 6,
+    "identityHash": "fb73ed8674efb1d82a586551baba5ef0",
+    "entities": [
+      {
+        "tableName": "sync_metadata",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER NOT NULL, `cursor` INTEGER NOT NULL, `lastSyncAt` INTEGER, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "cursor",
+            "columnName": "cursor",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "lastSyncAt",
+            "columnName": "lastSyncAt",
+            "affinity": "INTEGER"
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_artists",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` TEXT NOT NULL, `name` TEXT NOT NULL, `sortName` TEXT NOT NULL, `mbid` TEXT, `artistThumbPath` TEXT, `artistFanartPath` TEXT, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "name",
+            "columnName": "name",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "sortName",
+            "columnName": "sortName",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "mbid",
+            "columnName": "mbid",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "artistThumbPath",
+            "columnName": "artistThumbPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "artistFanartPath",
+            "columnName": "artistFanartPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_albums",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` TEXT NOT NULL, `artistId` TEXT NOT NULL, `title` TEXT NOT NULL, `sortTitle` TEXT NOT NULL, `releaseDate` TEXT, `coverPath` TEXT, `mbid` TEXT, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "artistId",
+            "columnName": "artistId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "title",
+            "columnName": "title",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "sortTitle",
+            "columnName": "sortTitle",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "releaseDate",
+            "columnName": "releaseDate",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "coverPath",
+            "columnName": "coverPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "mbid",
+            "columnName": "mbid",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_tracks",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` TEXT NOT NULL, `albumId` TEXT NOT NULL, `artistId` TEXT NOT NULL, `title` TEXT NOT NULL, `durationMs` INTEGER NOT NULL, `trackNumber` INTEGER, `discNumber` INTEGER, `filePath` TEXT, `fileFormat` TEXT, `genre` TEXT, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "albumId",
+            "columnName": "albumId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "artistId",
+            "columnName": "artistId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "title",
+            "columnName": "title",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "durationMs",
+            "columnName": "durationMs",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "trackNumber",
+            "columnName": "trackNumber",
+            "affinity": "INTEGER"
+          },
+          {
+            "fieldPath": "discNumber",
+            "columnName": "discNumber",
+            "affinity": "INTEGER"
+          },
+          {
+            "fieldPath": "filePath",
+            "columnName": "filePath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fileFormat",
+            "columnName": "fileFormat",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "genre",
+            "columnName": "genre",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_likes",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`userId` TEXT NOT NULL, `entityType` TEXT NOT NULL, `entityId` TEXT NOT NULL, `likedAt` INTEGER NOT NULL, PRIMARY KEY(`userId`, `entityType`, `entityId`))",
+        "fields": [
+          {
+            "fieldPath": "userId",
+            "columnName": "userId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "entityType",
+            "columnName": "entityType",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "entityId",
+            "columnName": "entityId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "likedAt",
+            "columnName": "likedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "userId",
+            "entityType",
+            "entityId"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_playlists",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` TEXT NOT NULL, `userId` TEXT NOT NULL, `name` TEXT NOT NULL, `description` TEXT NOT NULL, `isPublic` INTEGER NOT NULL, `coverPath` TEXT, `trackCount` INTEGER NOT NULL, `durationSec` INTEGER NOT NULL, `systemVariant` TEXT, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "userId",
+            "columnName": "userId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "name",
+            "columnName": "name",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "description",
+            "columnName": "description",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "isPublic",
+            "columnName": "isPublic",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "coverPath",
+            "columnName": "coverPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "trackCount",
+            "columnName": "trackCount",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "durationSec",
+            "columnName": "durationSec",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "systemVariant",
+            "columnName": "systemVariant",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_playlist_tracks",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`playlistId` TEXT NOT NULL, `trackId` TEXT NOT NULL, `position` INTEGER NOT NULL, PRIMARY KEY(`playlistId`, `trackId`))",
+        "fields": [
+          {
+            "fieldPath": "playlistId",
+            "columnName": "playlistId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "trackId",
+            "columnName": "trackId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "position",
+            "columnName": "position",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "playlistId",
+            "trackId"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_quarantine_mine",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`trackId` TEXT NOT NULL, `reason` TEXT NOT NULL, `notes` TEXT, `createdAt` TEXT NOT NULL, `trackTitle` TEXT NOT NULL, `trackDurationMs` INTEGER NOT NULL, `albumId` TEXT NOT NULL, `albumTitle` TEXT NOT NULL, `albumCoverArtPath` TEXT, `artistId` TEXT NOT NULL, `artistName` TEXT NOT NULL, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`trackId`))",
+        "fields": [
+          {
+            "fieldPath": "trackId",
+            "columnName": "trackId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "reason",
+            "columnName": "reason",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "notes",
+            "columnName": "notes",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "createdAt",
+            "columnName": "createdAt",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "trackTitle",
+            "columnName": "trackTitle",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "trackDurationMs",
+            "columnName": "trackDurationMs",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "albumId",
+            "columnName": "albumId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "albumTitle",
+            "columnName": "albumTitle",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "albumCoverArtPath",
+            "columnName": "albumCoverArtPath",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "artistId",
+            "columnName": "artistId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "artistName",
+            "columnName": "artistName",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "trackId"
+          ]
+        }
+      },
+      {
+        "tableName": "audio_cache_index",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`trackId` TEXT NOT NULL, `path` TEXT NOT NULL, `sizeBytes` INTEGER NOT NULL, `cachedAt` INTEGER NOT NULL, `lastPlayedAt` INTEGER, `source` TEXT NOT NULL, PRIMARY KEY(`trackId`))",
+        "fields": [
+          {
+            "fieldPath": "trackId",
+            "columnName": "trackId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "path",
+            "columnName": "path",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "sizeBytes",
+            "columnName": "sizeBytes",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "cachedAt",
+            "columnName": "cachedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "lastPlayedAt",
+            "columnName": "lastPlayedAt",
+            "affinity": "INTEGER"
+          },
+          {
+            "fieldPath": "source",
+            "columnName": "source",
+            "affinity": "TEXT",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "trackId"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_mutations",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, `kind` TEXT NOT NULL, `payload` TEXT NOT NULL, `createdAt` INTEGER NOT NULL, `lastAttemptAt` INTEGER, `attempts` INTEGER NOT NULL)",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "kind",
+            "columnName": "kind",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "payload",
+            "columnName": "payload",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "createdAt",
+            "columnName": "createdAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "lastAttemptAt",
+            "columnName": "lastAttemptAt",
+            "affinity": "INTEGER"
+          },
+          {
+            "fieldPath": "attempts",
+            "columnName": "attempts",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": true,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_resume_state",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER NOT NULL, `json` TEXT NOT NULL, `updatedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "json",
+            "columnName": "json",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "updatedAt",
+            "columnName": "updatedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_home_index",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`section` TEXT NOT NULL, `position` INTEGER NOT NULL, `entityType` TEXT NOT NULL, `entityId` TEXT NOT NULL, `fetchedAt` INTEGER NOT NULL, PRIMARY KEY(`section`, `position`))",
+        "fields": [
+          {
+            "fieldPath": "section",
+            "columnName": "section",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "position",
+            "columnName": "position",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "entityType",
+            "columnName": "entityType",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "entityId",
+            "columnName": "entityId",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "fetchedAt",
+            "columnName": "fetchedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "section",
+            "position"
+          ]
+        }
+      },
+      {
+        "tableName": "cached_history_snapshot",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER NOT NULL, `json` TEXT NOT NULL, `updatedAt` INTEGER NOT NULL, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "json",
+            "columnName": "json",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "updatedAt",
+            "columnName": "updatedAt",
+            "affinity": "INTEGER",
+            "notNull": true
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      },
+      {
+        "tableName": "auth_session",
+        "createSql": "CREATE TABLE IF NOT EXISTS `${TABLE_NAME}` (`id` INTEGER NOT NULL, `sessionCookie` TEXT, `baseUrl` TEXT NOT NULL, `userJson` TEXT, `themeMode` TEXT, `clientId` TEXT, `cacheSettingsJson` TEXT, PRIMARY KEY(`id`))",
+        "fields": [
+          {
+            "fieldPath": "id",
+            "columnName": "id",
+            "affinity": "INTEGER",
+            "notNull": true
+          },
+          {
+            "fieldPath": "sessionCookie",
+            "columnName": "sessionCookie",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "baseUrl",
+            "columnName": "baseUrl",
+            "affinity": "TEXT",
+            "notNull": true
+          },
+          {
+            "fieldPath": "userJson",
+            "columnName": "userJson",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "themeMode",
+            "columnName": "themeMode",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "clientId",
+            "columnName": "clientId",
+            "affinity": "TEXT"
+          },
+          {
+            "fieldPath": "cacheSettingsJson",
+            "columnName": "cacheSettingsJson",
+            "affinity": "TEXT"
+          }
+        ],
+        "primaryKey": {
+          "autoGenerate": false,
+          "columnNames": [
+            "id"
+          ]
+        }
+      }
+    ],
+    "setupQueries": [
+      "CREATE TABLE IF NOT EXISTS room_master_table (id INTEGER PRIMARY KEY,identity_hash TEXT)",
+      "INSERT OR REPLACE INTO room_master_table (id,identity_hash) VALUES(42, 'fb73ed8674efb1d82a586551baba5ef0')"
+    ]
+  }
+}

android/app/src/main/AndroidManifest.xml

@@ -8,7 +8,20 @@
     <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 (M489 #5347): 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
+         grants the silent path only when the installer opts in via
+         SessionParams.setRequireUserAction(USER_ACTION_NOT_REQUIRED), the
+         installed app targets API 29+, the installer holds this permission, and
+         the target is the installer itself — all true here, since Minstrel is
+         updating Minstrel. See update/data/SelfUpdateSession.kt. -->
     <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
+    <uses-permission android:name="android.permission.UPDATE_PACKAGES_WITHOUT_USER_ACTION" />
     <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
     <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
 
@@ -19,9 +32,9 @@
         android:fullBackupContent="@xml/backup_rules"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
+        android:networkSecurityConfig="@xml/network_security_config"
         android:supportsRtl="true"
         android:theme="@style/Theme.Minstrel"
-        android:usesCleartextTraffic="true"
         tools:targetApi="34">
 
         <!-- Portrait-locked until a tablet/landscape layout exists.
@@ -48,15 +61,34 @@
             </intent-filter>
         </service>
 
-        <provider
-            android:name="androidx.core.content.FileProvider"
-            android:authorities="${applicationId}.fileprovider"
+        <!-- Keeps the process alive so notifications arrive with the app
+             closed. specialUse: dataSync is stopped after six hours on
+             Android 15, and shortService after three minutes. -->
+        <service
+            android:name=".notifications.delivery.DeliveryService"
             android:exported="false"
-            android:grantUriPermissions="true">
-            <meta-data
-                android:name="android.support.FILE_PROVIDER_PATHS"
-                android:resource="@xml/file_paths" />
-        </provider>
+            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>
+
+        <!-- The FileProvider that used to live here existed solely to expose the
+             downloaded update APK as a content:// URI for the old ACTION_VIEW
+             install intent. A PackageInstaller session takes a stream instead,
+             so both the provider and res/xml/file_paths.xml are gone — nothing
+             else in the app ever used that authority. -->
 
         <!-- On-demand WorkManager initialization: MinstrelApplication
              implements Configuration.Provider and supplies the

android/app/src/main/java/com/fabledsword/minstrel/MainActivity.kt

@@ -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,15 +20,24 @@ 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
+import com.fabledsword.minstrel.connectivity.ServerHealth
+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
@@ -32,46 +45,83 @@ 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
 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
-    // any other entry point that asks for the full player). The App
-    // composable observes this, navigates to NowPlaying once the
-    // NavHost is ready, then calls back to reset the flag so the
-    // navigation doesn't re-fire on the next recomposition.
-    private val pendingOpenNowPlaying = MutableStateFlow(false)
+    // Set when the user taps a notification: the media one asks for the full
+    // player, a Minstrel notice for what it is about. The App composable
+    // navigates there once the NavHost is ready, then calls back to clear it
+    // so the navigation doesn't re-fire on the next recomposition.
+    private val pendingRoute = MutableStateFlow<Any?>(null)
+
+    // 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,
-                pendingOpenNowPlaying = pendingOpenNowPlaying.asStateFlow(),
-                onOpenedNowPlaying = { pendingOpenNowPlaying.value = false },
+                serverHealth = serverHealth,
+                pendingRoute = pendingRoute.asStateFlow(),
+                onOpenedRoute = { pendingRoute.value = null },
             )
         }
     }
 
     override fun onNewIntent(intent: Intent) {
         super.onNewIntent(intent)
-        consumeOpenNowPlayingIntent(intent)
+        consumeRouteIntent(intent)
     }
 
-    private fun consumeOpenNowPlayingIntent(intent: Intent?) {
-        if (intent?.getBooleanExtra(EXTRA_OPEN_NOW_PLAYING, false) == true) {
-            pendingOpenNowPlaying.value = true
+    private fun consumeRouteIntent(intent: Intent?) {
+        if (intent == null) return
+        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 (M489 #5347).
+     * 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 {
@@ -79,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"
     }
 }
 
@@ -86,18 +140,21 @@ class MainActivity : ComponentActivity() {
 private fun App(
     seedCache: DetailSeedCache,
     cachedTrackIds: CachedTrackIds,
-    pendingOpenNowPlaying: StateFlow<Boolean>,
-    onOpenedNowPlaying: () -> Unit,
+    serverHealth: NetworkStatusController,
+    pendingRoute: StateFlow<Any?>,
+    onOpenedRoute: () -> Unit,
     themeVm: ThemePreferenceViewModel = hiltViewModel(),
     gate: AuthGateViewModel = hiltViewModel(),
 ) {
     val theme by themeVm.themeMode.collectAsStateWithLifecycle()
     val cached by cachedTrackIds.ids.collectAsStateWithLifecycle()
-    val pending by pendingOpenNowPlaying.collectAsStateWithLifecycle()
+    val health: ServerHealth by serverHealth.state.collectAsStateWithLifecycle()
+    val pending by pendingRoute.collectAsStateWithLifecycle()
     MinstrelTheme(darkOverride = theme.toDarkOverride()) {
         CompositionLocalProvider(
             LocalDetailSeedCache provides seedCache,
             LocalCachedTrackIds provides cached,
+            LocalServerHealth provides health,
         ) {
             val startDestination by gate.startDestination.collectAsStateWithLifecycle()
             val resolved = startDestination
@@ -111,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
-                // NowPlaying if the user taps the notification while
-                // already on it; the callback clears the flag so a later
-                // recomposition (config change, theme switch) doesn't
-                // re-navigate.
+                // mounted. launchSingleTop avoids stacking copies of a
+                // screen if the user taps the notification while already
+                // on it; the callback clears it so a later recomposition
+                // (config change, theme switch) doesn't re-navigate.
                 LaunchedEffect(pending, navController) {
-                    if (pending) {
-                        navController.navigate(NowPlaying) { launchSingleTop = true }
-                        onOpenedNowPlaying()
-                    }
+                    val route = pending ?: return@LaunchedEffect
+                    navController.navigate(route) { launchSingleTop = true }
+                    onOpenedRoute()
                 }
                 MinstrelNavGraph(
                     navController = navController,

android/app/src/main/java/com/fabledsword/minstrel/MinstrelApplication.kt

@@ -6,20 +6,24 @@ import androidx.work.Configuration
 import coil3.ImageLoader
 import coil3.SingletonImageLoader
 import coil3.network.okhttp.OkHttpNetworkFetcherFactory
+import coil3.request.crossfade
 import com.fabledsword.minstrel.cache.CacheIndexer
 import com.fabledsword.minstrel.cache.mutations.MutationReplayer
 import com.fabledsword.minstrel.cache.sync.SyncController
 import com.fabledsword.minstrel.di.ApplicationScope
+import com.fabledsword.minstrel.diagnostics.DiagnosticsReporter
+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.PlayEventsReporter
 import com.fabledsword.minstrel.player.PlaybackErrorReporter
 import com.fabledsword.minstrel.player.ResumeController
 import com.fabledsword.minstrel.update.data.UpdateBannerController
-import com.fabledsword.minstrel.update.data.VersionCheckController
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import dagger.hilt.android.HiltAndroidApp
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.launch
@@ -27,6 +31,10 @@ import okhttp3.OkHttpClient
 import timber.log.Timber
 import javax.inject.Inject
 
+// Cover-art fade-in. Coil skips the transition for memory-cache hits, so
+// already-loaded art still appears instantly — only a genuine fetch fades.
+private const val ART_CROSSFADE_MS = 220
+
 @HiltAndroidApp
 class MinstrelApplication :
     Application(),
@@ -68,6 +76,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 (M489 #5347). 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
@@ -114,12 +130,13 @@ class MinstrelApplication :
     @Suppress("unused") @Inject lateinit var audioPrefetcher: AudioPrefetcher
 
     /**
-     * Same construct-the-singleton trick — VersionCheckController's
-     * init block starts a 5-min poll loop against /healthz so the
-     * shell-level VersionTooOldBanner can surface min_client_version
-     * mismatches without waiting for the next user-driven request.
+     * Same construct-the-singleton trick — NetworkStatusController owns the
+     * /healthz poll loop + the device-link collector + the reachability state
+     * machine, and is the single authority on the tri-state ServerHealth
+     * signal (plus the VersionTooOld byproduct). It must exist from launch so
+     * the poll loop runs and the StateFlow stays warm for every consumer.
      */
-    @Suppress("unused") @Inject lateinit var versionCheckController: VersionCheckController
+    @Suppress("unused") @Inject lateinit var networkStatusController: NetworkStatusController
 
     /**
      * Same construct-the-singleton trick — UpdateBannerController polls
@@ -154,6 +171,11 @@ class MinstrelApplication :
      */
     @Suppress("unused") @Inject lateinit var liveEventsDispatcher: LiveEventsDispatcher
 
+    // Device diagnostics (M9). 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
+
     @Inject @ApplicationScope lateinit var appScope: CoroutineScope
 
     override fun onCreate() {
@@ -205,11 +227,18 @@ class MinstrelApplication :
      * OkHttp client as the network fetcher. The `callFactory` lambda
      * is invoked lazily so Hilt has time to inject `okHttpClient`
      * 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
+     * landing a beat after its tile was the most visible pop-in on Home
+     * (issue #2327); `ServerImage` fades its placeholder out over the
+     * same window so the two read as one cross-dissolve.
      */
     override fun newImageLoader(context: android.content.Context): ImageLoader =
         ImageLoader.Builder(context)
             .components {
                 add(OkHttpNetworkFetcherFactory(callFactory = { okHttpClient }))
             }
+            .crossfade(ART_CROSSFADE_MS)
             .build()
 }

android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminRequestsRepository.kt

@@ -11,8 +11,6 @@ import javax.inject.Singleton
 
 /**
  * Read-through accessor for the admin cross-user requests queue.
- * Mirrors `flutter_client/lib/admin/admin_providers.dart`'s
- * AdminRequestsController.
  *
  * No Room caching — admin actions are infrequent and don't benefit
  * from offline scrollback. `approve` and `reject` fire direct REST

android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminTagSourcesRepository.kt

@@ -0,0 +1,48 @@
+package com.fabledsword.minstrel.admin.data
+
+import com.fabledsword.minstrel.api.endpoints.AdminTagSourcesApi
+import com.fabledsword.minstrel.api.endpoints.UpdateTagSourceBody
+import com.fabledsword.minstrel.models.AdminTagSourceRef
+import com.fabledsword.minstrel.models.TagSourceTestResult
+import com.fabledsword.minstrel.models.wire.AdminTagSourceWire
+import com.fabledsword.minstrel.models.wire.TestTagSourceWire
+import retrofit2.Retrofit
+import retrofit2.create
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Read-through accessor for the tag-enrichment provider settings (#1521).
+ * 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).
+ */
+@Singleton
+class AdminTagSourcesRepository @Inject constructor(
+    retrofit: Retrofit,
+) {
+    private val api: AdminTagSourcesApi = retrofit.create()
+
+    suspend fun list(): List<AdminTagSourceRef> = api.list().providers.map { it.toDomain() }
+
+    suspend fun setEnabled(id: String, enabled: Boolean): AdminTagSourceRef =
+        api.update(id, UpdateTagSourceBody(enabled = enabled)).toDomain()
+
+    suspend fun setApiKey(id: String, apiKey: String): AdminTagSourceRef =
+        api.update(id, UpdateTagSourceBody(apiKey = apiKey)).toDomain()
+
+    suspend fun test(id: String): TagSourceTestResult = api.test(id).toResult()
+}
+
+private fun AdminTagSourceWire.toDomain(): AdminTagSourceRef = AdminTagSourceRef(
+    id = id,
+    displayName = displayName,
+    requiresApiKey = requiresApiKey,
+    supports = supports,
+    enabled = enabled,
+    apiKeySet = apiKeySet,
+    testable = testable,
+)
+
+private fun TestTagSourceWire.toResult(): TagSourceTestResult =
+    TagSourceTestResult(ok = ok, durationMs = durationMs, error = error)

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminInvitesViewModel.kt

@@ -4,6 +4,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.admin.data.AdminInvitesRepository
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.models.Invite
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.channels.Channel
@@ -25,6 +27,7 @@ data class AdminInvitesUiState(
 @HiltViewModel
 class AdminInvitesViewModel @Inject constructor(
     private val repository: AdminInvitesRepository,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val internal = MutableStateFlow(AdminInvitesUiState())
@@ -36,6 +39,13 @@ class AdminInvitesViewModel @Inject constructor(
 
     init {
         refresh()
+        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // when server health returns instead of waiting for a manual pull.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value.message != null) refresh()
+            }
+        }
     }
 
     fun refresh() {

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminLandingScreen.kt

@@ -28,16 +28,20 @@ import androidx.lifecycle.viewModelScope
 import androidx.navigation.NavHostController
 import com.composables.icons.lucide.Inbox
 import com.composables.icons.lucide.Lucide
+import com.composables.icons.lucide.Music
 import com.composables.icons.lucide.TriangleAlert
 import com.composables.icons.lucide.Users
 import com.fabledsword.minstrel.admin.data.AdminQuarantineRepository
 import com.fabledsword.minstrel.admin.data.AdminRequestsRepository
+import com.fabledsword.minstrel.admin.data.AdminTagSourcesRepository
 import com.fabledsword.minstrel.admin.data.AdminUsersRepository
 import com.fabledsword.minstrel.api.ErrorCopy
 import com.fabledsword.minstrel.nav.Admin
 import com.fabledsword.minstrel.nav.AdminQuarantine
 import com.fabledsword.minstrel.nav.AdminRequests
+import com.fabledsword.minstrel.nav.AdminTagSources
 import com.fabledsword.minstrel.nav.AdminUsers
+import com.fabledsword.minstrel.shared.widgets.ShellContentWindowInsets
 import com.fabledsword.minstrel.shared.widgets.EmptyState
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
@@ -54,7 +58,7 @@ import javax.inject.Inject
 
 // ─── State ───────────────────────────────────────────────────────────
 
-data class AdminCounts(val requests: Int, val quarantine: Int, val users: Int)
+data class AdminCounts(val requests: Int, val quarantine: Int, val users: Int, val tagSources: Int)
 
 sealed interface AdminLandingUiState {
     data object Loading : AdminLandingUiState
@@ -69,6 +73,7 @@ class AdminLandingViewModel @Inject constructor(
     private val requestsRepo: AdminRequestsRepository,
     private val quarantineRepo: AdminQuarantineRepository,
     private val usersRepo: AdminUsersRepository,
+    private val tagSourcesRepo: AdminTagSourcesRepository,
 ) : ViewModel() {
 
     private val internal = MutableStateFlow<AdminLandingUiState>(AdminLandingUiState.Loading)
@@ -85,7 +90,8 @@ class AdminLandingViewModel @Inject constructor(
                 val req = async { requestsRepo.list().size }
                 val qua = async { quarantineRepo.list().size }
                 val usr = async { usersRepo.list().size }
-                AdminCounts(req.await(), qua.await(), usr.await())
+                val tag = async { tagSourcesRepo.list().count { it.enabled } }
+                AdminCounts(req.await(), qua.await(), usr.await(), tag.await())
             }
             internal.value = AdminLandingUiState.Success(counts)
         } catch (
@@ -107,6 +113,7 @@ fun AdminLandingScreen(
 ) {
     val state by viewModel.uiState.collectAsStateWithLifecycle()
     Scaffold(
+        contentWindowInsets = ShellContentWindowInsets,
         modifier = Modifier.fillMaxSize(),
         topBar = {
             MinstrelTopAppBar(
@@ -170,6 +177,15 @@ private fun SectionList(counts: AdminCounts, navController: NavHostController) {
                 onClick = { navController.navigate(AdminUsers) },
             )
         }
+        item {
+            SectionCard(
+                icon = Lucide.Music,
+                title = "Tag sources",
+                subtitle = "Metadata enrichment providers",
+                count = counts.tagSources,
+                onClick = { navController.navigate(AdminTagSources) },
+            )
+        }
     }
 }
 

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminQuarantineScreen.kt

@@ -15,10 +15,14 @@ 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
@@ -28,7 +32,9 @@ import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.navigation.NavHostController
 import com.fabledsword.minstrel.models.AdminQuarantineItemRef
 import com.fabledsword.minstrel.nav.AdminQuarantine
+import com.fabledsword.minstrel.shared.widgets.ShellContentWindowInsets
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -40,7 +46,14 @@ 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(),
         topBar = {
             MinstrelTopAppBar(
@@ -50,6 +63,7 @@ fun AdminQuarantineScreen(
                 onBack = { navController.popBackStack() },
             )
         },
+        snackbarHost = { SnackbarHost(snackbarHostState) },
     ) { inner ->
         PullToRefreshScaffold(
             onRefresh = { viewModel.refresh().join() },
@@ -62,9 +76,10 @@ fun AdminQuarantineScreen(
                     body = "When users flag tracks as bad rips, wrong tags, or " +
                         "duplicates, their reports get aggregated and surfaced here.",
                 )
-                is AdminQuarantineUiState.Error -> EmptyState(
+                is AdminQuarantineUiState.Error -> ErrorRetry(
                     title = "Couldn't load queue",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                 )
                 is AdminQuarantineUiState.Success -> QueueList(
                     rows = s.rows,

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminQuarantineViewModel.kt

@@ -4,14 +4,19 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.admin.data.AdminQuarantineRepository
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 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
 
@@ -26,11 +31,21 @@ sealed interface AdminQuarantineUiState {
 class AdminQuarantineViewModel @Inject constructor(
     private val repository: AdminQuarantineRepository,
     private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     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 the
+     * operator can fix (#3918).
+     */
+    private val transientMessagesChannel = Channel<String>(Channel.BUFFERED)
+    val transientMessages: Flow<String> = transientMessagesChannel.receiveAsFlow()
+
     init {
         refresh()
         viewModelScope.launch {
@@ -38,6 +53,13 @@ class AdminQuarantineViewModel @Inject constructor(
                 .filter { it.kind.startsWith("quarantine.") }
                 .collect { refresh() }
         }
+        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // when server health returns instead of waiting for a manual pull.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AdminQuarantineUiState.Error) refresh()
+            }
+        }
     }
 
     fun refresh(): Job = viewModelScope.launch {
@@ -76,8 +98,9 @@ class AdminQuarantineViewModel @Inject constructor(
             try {
                 action(trackId)
             } catch (
-                @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
+                @Suppress("TooGenericExceptionCaught") e: Throwable,
             ) {
+                transientMessagesChannel.trySend(ErrorCopy.fromThrowable(e))
                 refresh()
             }
         }

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminRequestsScreen.kt

@@ -27,7 +27,9 @@ import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.navigation.NavHostController
 import com.fabledsword.minstrel.models.RequestRef
 import com.fabledsword.minstrel.nav.AdminRequests
+import com.fabledsword.minstrel.shared.widgets.ShellContentWindowInsets
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -40,6 +42,7 @@ fun AdminRequestsScreen(
 ) {
     val state by viewModel.uiState.collectAsStateWithLifecycle()
     Scaffold(
+        contentWindowInsets = ShellContentWindowInsets,
         modifier = Modifier.fillMaxSize(),
         topBar = {
             MinstrelTopAppBar(
@@ -61,9 +64,10 @@ fun AdminRequestsScreen(
                     body = "When users ask Lidarr for new music, their pending " +
                         "requests show up here for approval.",
                 )
-                is AdminRequestsUiState.Error -> EmptyState(
+                is AdminRequestsUiState.Error -> ErrorRetry(
                     title = "Couldn't load requests",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                 )
                 is AdminRequestsUiState.Success -> RequestList(
                     rows = s.rows,

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminRequestsViewModel.kt

@@ -5,6 +5,8 @@ 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
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.RequestRef
 import dagger.hilt.android.lifecycle.HiltViewModel
@@ -35,6 +37,7 @@ class AdminRequestsViewModel @Inject constructor(
     private val repository: AdminRequestsRepository,
     private val usersRepository: AdminUsersRepository,
     private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val internal = MutableStateFlow<AdminRequestsUiState>(AdminRequestsUiState.Loading)
@@ -47,6 +50,13 @@ class AdminRequestsViewModel @Inject constructor(
                 .filter { it.kind in RELEVANT_EVENT_KINDS }
                 .collect { refresh() }
         }
+        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // when server health returns instead of waiting for a manual pull.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AdminRequestsUiState.Error) refresh()
+            }
+        }
     }
 
     fun refresh(): Job = viewModelScope.launch {

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminTagSourcesScreen.kt

@@ -0,0 +1,222 @@
+package com.fabledsword.minstrel.admin.ui
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material3.Button
+import androidx.compose.material3.ElevatedCard
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.input.PasswordVisualTransformation
+import androidx.compose.ui.unit.dp
+import androidx.hilt.navigation.compose.hiltViewModel
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import androidx.navigation.NavHostController
+import com.fabledsword.minstrel.models.AdminTagSourceRef
+import com.fabledsword.minstrel.models.TagSourceTestResult
+import com.fabledsword.minstrel.nav.AdminTagSources
+import com.fabledsword.minstrel.shared.widgets.ShellContentWindowInsets
+import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
+import com.fabledsword.minstrel.shared.widgets.LoadingCentered
+import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
+import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun AdminTagSourcesScreen(
+    navController: NavHostController,
+    viewModel: AdminTagSourcesViewModel = hiltViewModel(),
+) {
+    val state by viewModel.uiState.collectAsStateWithLifecycle()
+    Scaffold(
+        contentWindowInsets = ShellContentWindowInsets,
+        modifier = Modifier.fillMaxSize(),
+        topBar = {
+            MinstrelTopAppBar(
+                title = "Admin · Tag sources",
+                navController = navController,
+                currentRouteName = AdminTagSources::class.qualifiedName,
+                onBack = { navController.popBackStack() },
+            )
+        },
+    ) { inner ->
+        PullToRefreshScaffold(
+            onRefresh = { viewModel.refresh().join() },
+            modifier = Modifier.fillMaxSize().padding(inner),
+        ) {
+            when (val s = state) {
+                AdminTagSourcesUiState.Loading -> LoadingCentered()
+                AdminTagSourcesUiState.Empty -> EmptyState(
+                    title = "No tag sources",
+                    body = "Tag-enrichment providers register on the server; none are available.",
+                )
+                is AdminTagSourcesUiState.Error -> ErrorRetry(
+                    title = "Couldn't load tag sources",
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
+                )
+                is AdminTagSourcesUiState.Success -> TagSourceList(
+                    providers = s.providers,
+                    testResults = s.testResults,
+                    onToggle = viewModel::setEnabled,
+                    onSaveKey = viewModel::saveApiKey,
+                    onTest = viewModel::test,
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun TagSourceList(
+    providers: List<AdminTagSourceRef>,
+    testResults: Map<String, TagSourceTestResult>,
+    onToggle: (String, Boolean) -> Unit,
+    onSaveKey: (String, String) -> Unit,
+    onTest: (String) -> Unit,
+) {
+    LazyColumn(
+        modifier = Modifier.fillMaxSize(),
+        contentPadding = PaddingValues(16.dp),
+        verticalArrangement = Arrangement.spacedBy(12.dp),
+    ) {
+        items(items = providers, key = { it.id }) { provider ->
+            TagSourceCard(
+                provider = provider,
+                testResult = testResults[provider.id],
+                onToggle = onToggle,
+                onSaveKey = onSaveKey,
+                onTest = onTest,
+            )
+        }
+    }
+}
+
+@Composable
+private fun TagSourceCard(
+    provider: AdminTagSourceRef,
+    testResult: TagSourceTestResult?,
+    onToggle: (String, Boolean) -> Unit,
+    onSaveKey: (String, String) -> Unit,
+    onTest: (String) -> Unit,
+) {
+    ElevatedCard(modifier = Modifier.fillMaxWidth()) {
+        Column(
+            modifier = Modifier.fillMaxWidth().padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(10.dp),
+        ) {
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                verticalAlignment = Alignment.CenterVertically,
+                horizontalArrangement = Arrangement.SpaceBetween,
+            ) {
+                Column(modifier = Modifier.weight(1f)) {
+                    Text(provider.displayName, style = MaterialTheme.typography.titleMedium)
+                    Text(
+                        text = provider.supports.joinToString(", ") { it.replace('_', ' ') },
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                Switch(
+                    checked = provider.enabled,
+                    onCheckedChange = { onToggle(provider.id, it) },
+                )
+            }
+            if (provider.requiresApiKey) {
+                ApiKeyRow(provider = provider, onSaveKey = onSaveKey)
+            }
+            if (provider.testable) {
+                TestRow(provider = provider, testResult = testResult, onTest = onTest)
+            }
+        }
+    }
+}
+
+@Composable
+private fun ApiKeyRow(provider: AdminTagSourceRef, onSaveKey: (String, String) -> Unit) {
+    var key by remember(provider.id) { mutableStateOf("") }
+    OutlinedTextField(
+        value = key,
+        onValueChange = { key = it },
+        modifier = Modifier.fillMaxWidth(),
+        label = { Text("API key") },
+        placeholder = {
+            Text(
+                if (provider.apiKeySet) {
+                    "••• saved — leave blank to keep"
+                } else {
+                    "Paste your API key to enable this source"
+                },
+            )
+        },
+        singleLine = true,
+        visualTransformation = PasswordVisualTransformation(),
+        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+    )
+    Row(
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        Button(
+            onClick = {
+                onSaveKey(provider.id, key)
+                key = ""
+            },
+            enabled = key.isNotBlank(),
+        ) { Text("Save key") }
+        if (provider.apiKeySet) {
+            Text("✓ Set", style = MaterialTheme.typography.bodySmall)
+        }
+    }
+}
+
+@Composable
+private fun TestRow(
+    provider: AdminTagSourceRef,
+    testResult: TagSourceTestResult?,
+    onTest: (String) -> Unit,
+) {
+    Row(
+        horizontalArrangement = Arrangement.spacedBy(8.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        OutlinedButton(onClick = { onTest(provider.id) }) { Text("Test connection") }
+        testResult?.let { result ->
+            if (result.ok) {
+                Text(
+                    text = "OK (${result.durationMs}ms)",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.primary,
+                )
+            } else {
+                Text(
+                    text = "Failed — ${result.error}",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.error,
+                )
+            }
+        }
+    }
+}

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminTagSourcesViewModel.kt

@@ -0,0 +1,116 @@
+package com.fabledsword.minstrel.admin.ui
+
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.viewModelScope
+import com.fabledsword.minstrel.admin.data.AdminTagSourcesRepository
+import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
+import com.fabledsword.minstrel.models.AdminTagSourceRef
+import com.fabledsword.minstrel.models.TagSourceTestResult
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+
+sealed interface AdminTagSourcesUiState {
+    data object Loading : AdminTagSourcesUiState
+    data object Empty : AdminTagSourcesUiState
+    data class Success(
+        val providers: List<AdminTagSourceRef>,
+        val testResults: Map<String, TagSourceTestResult>,
+    ) : AdminTagSourcesUiState
+    data class Error(val message: String) : AdminTagSourcesUiState
+}
+
+@HiltViewModel
+class AdminTagSourcesViewModel @Inject constructor(
+    private val repository: AdminTagSourcesRepository,
+    networkStatus: NetworkStatusController,
+) : ViewModel() {
+
+    private val internal = MutableStateFlow<AdminTagSourcesUiState>(AdminTagSourcesUiState.Loading)
+    val uiState: StateFlow<AdminTagSourcesUiState> = internal.asStateFlow()
+
+    init {
+        refresh()
+        // Screen-level auto-recovery: reload a failed list when server
+        // health returns instead of waiting for a manual pull (issue #1245).
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AdminTagSourcesUiState.Error) refresh()
+            }
+        }
+    }
+
+    fun refresh(): Job = viewModelScope.launch {
+        internal.value = AdminTagSourcesUiState.Loading
+        try {
+            val providers = repository.list()
+            internal.value = if (providers.isEmpty()) {
+                AdminTagSourcesUiState.Empty
+            } else {
+                AdminTagSourcesUiState.Success(providers, emptyMap())
+            }
+        } catch (
+            @Suppress("TooGenericExceptionCaught") e: Throwable,
+        ) {
+            internal.value = AdminTagSourcesUiState.Error(ErrorCopy.fromThrowable(e))
+        }
+    }
+
+    fun setEnabled(id: String, enabled: Boolean) {
+        val before = internal.value as? AdminTagSourcesUiState.Success ?: return
+        // Optimistic toggle; reconcile via refresh() if the server rejects.
+        internal.value = before.copy(
+            providers = before.providers.map {
+                if (it.id == id) it.copy(enabled = enabled) else it
+            },
+        )
+        viewModelScope.launch {
+            try {
+                repository.setEnabled(id, enabled)
+            } catch (
+                @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
+            ) {
+                refresh()
+            }
+        }
+    }
+
+    fun saveApiKey(id: String, apiKey: String) {
+        viewModelScope.launch {
+            try {
+                replaceProvider(repository.setApiKey(id, apiKey))
+            } catch (
+                @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
+            ) {
+                refresh()
+            }
+        }
+    }
+
+    fun test(id: String) {
+        viewModelScope.launch {
+            val result = try {
+                repository.test(id)
+            } catch (
+                @Suppress("TooGenericExceptionCaught") e: Throwable,
+            ) {
+                TagSourceTestResult(ok = false, error = ErrorCopy.fromThrowable(e))
+            }
+            val current = internal.value as? AdminTagSourcesUiState.Success ?: return@launch
+            internal.value = current.copy(testResults = current.testResults + (id to result))
+        }
+    }
+
+    private fun replaceProvider(updated: AdminTagSourceRef) {
+        val current = internal.value as? AdminTagSourcesUiState.Success ?: return
+        internal.value = current.copy(
+            providers = current.providers.map { if (it.id == updated.id) updated else it },
+        )
+    }
+}

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminUsersScreen.kt

@@ -49,6 +49,7 @@ import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.navigation.NavHostController
 import com.fabledsword.minstrel.models.AdminUserRef
 import com.fabledsword.minstrel.nav.AdminUsers
+import com.fabledsword.minstrel.shared.widgets.ShellContentWindowInsets
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import kotlinx.coroutines.launch
@@ -127,6 +128,7 @@ private fun AdminUsersScaffold(
     onRevokeInvite: (String) -> Unit,
 ) {
     Scaffold(
+        contentWindowInsets = ShellContentWindowInsets,
         modifier = Modifier.fillMaxSize(),
         topBar = {
             MinstrelTopAppBar(

android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminUsersViewModel.kt

@@ -4,6 +4,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 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
 import com.fabledsword.minstrel.models.AdminUserRef
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
@@ -23,6 +25,7 @@ sealed interface AdminUsersUiState {
 @HiltViewModel
 class AdminUsersViewModel @Inject constructor(
     private val repository: AdminUsersRepository,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val internal = MutableStateFlow<AdminUsersUiState>(AdminUsersUiState.Loading)
@@ -30,6 +33,13 @@ class AdminUsersViewModel @Inject constructor(
 
     init {
         refresh()
+        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // when server health returns instead of waiting for a manual pull.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AdminUsersUiState.Error) refresh()
+            }
+        }
     }
 
     fun refresh(): Job = viewModelScope.launch {

android/app/src/main/java/com/fabledsword/minstrel/api/BaseUrlInterceptor.kt

@@ -50,7 +50,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 {

android/app/src/main/java/com/fabledsword/minstrel/api/CleartextGuard.kt

@@ -0,0 +1,84 @@
+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 (family security baseline #5105,
+ * practice 13).
+ *
+ * Cleartext stays permitted app-wide for LAN servers and UPnP
+ * (network_security_config.xml, #2439), 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
+}

android/app/src/main/java/com/fabledsword/minstrel/api/ErrorCopy.kt

@@ -8,8 +8,7 @@ import java.io.IOException
 
 /**
  * Maps server error codes (and common transport failures) to
- * friendly, sentence-case copy. Mirrors
- * `flutter_client/assets/error-copy.json` + `error_copy.dart`.
+ * friendly, sentence-case copy.
  *
  * Server errors are `{"error":{"code":"...","message":"..."}}`.
  * [fromThrowable] pulls the code out of a Retrofit [HttpException]'s
@@ -38,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 the operator needs in
+     * order to act — which directory, which uid — that fixed copy cannot say.
+     * For these the message follows the copy (#3918). 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"
-        val code = runCatching { json.decodeFromString<Envelope>(raw).error?.code }
-            .getOrNull()
-            .orEmpty()
-        return code.ifEmpty { "unknown" }
+            ?: return Body()
+        return runCatching { json.decodeFromString<Envelope>(raw).error }
+            .getOrNull() ?: Body()
     }
 
     private val TABLE: Map<String, String> = mapOf(
@@ -59,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.",
@@ -84,6 +102,9 @@ 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.",
+        "cleartext_public" to
+            "This server is on the internet, so its URL must start with https://. " +
+            "Plain http:// only works on your home network.",
         "lidarr_unreachable" to
             "Lidarr is unreachable right now. Try again, or check Admin → Integrations.",
         "lidarr_disabled" to "Lidarr integration is not enabled.",
@@ -100,6 +121,8 @@ object ErrorCopy {
         "request_not_pending" to "This request is no longer pending.",
         "request_not_found" to "That request 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.",

android/app/src/main/java/com/fabledsword/minstrel/api/NetworkModule.kt

@@ -1,6 +1,7 @@
 package com.fabledsword.minstrel.api
 
 import com.fabledsword.minstrel.BuildConfig
+import com.fabledsword.minstrel.connectivity.ReachabilityReportingInterceptor
 import com.jakewharton.retrofit2.converter.kotlinx.serialization.asConverterFactory
 import dagger.Module
 import dagger.Provides
@@ -45,9 +46,15 @@ object NetworkModule {
     fun provideOkHttp(
         baseUrl: BaseUrlInterceptor,
         auth: AuthCookieInterceptor,
+        reachability: ReachabilityReportingInterceptor,
         logging: HttpLoggingInterceptor,
     ): OkHttpClient =
         OkHttpClient.Builder()
+            // ReachabilityReportingInterceptor MUST run first: it identifies
+            // Minstrel-bound requests by the still-unrewritten PLACEHOLDER_HOST
+            // (so external artwork fetches don't read as server reachability)
+            // and observes the final transport outcome by wrapping the chain.
+            .addInterceptor(reachability)
             // AuthCookieInterceptor MUST run before BaseUrlInterceptor.
             // Both scope on `host == PLACEHOLDER_HOST` to distinguish
             // Minstrel-server requests from external image fetches
@@ -63,6 +70,9 @@ object NetworkModule {
             .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()

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminInvitesApi.kt

@@ -10,8 +10,7 @@ import retrofit2.http.POST
 import retrofit2.http.Path
 
 /**
- * Retrofit interface for `/api/admin/invites`. Mirrors
- * `flutter_client/lib/api/endpoints/admin_invites.dart`.
+ * Retrofit interface for `/api/admin/invites`.
  *
  * Server TTL is hardcoded at 24h; the only configurable field is the
  * optional `note` on create.

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminQuarantineApi.kt

@@ -6,8 +6,7 @@ import retrofit2.http.POST
 import retrofit2.http.Path
 
 /**
- * Retrofit interface for `/api/admin/quarantine`. Mirrors
- * `flutter_client/lib/api/endpoints/admin_quarantine.dart`.
+ * Retrofit interface for `/api/admin/quarantine`.
  *
  * Three resolution endpoints:
  *   - `resolve`        → admin reviewed, no action taken (clears flags).

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminRequestsApi.kt

@@ -6,8 +6,7 @@ import retrofit2.http.POST
 import retrofit2.http.Path
 
 /**
- * Retrofit interface for `/api/admin/requests`. Mirrors
- * `flutter_client/lib/api/endpoints/admin_requests.dart`.
+ * Retrofit interface for `/api/admin/requests`.
  *
  * Server returns the same `requestView` shape as the user-side
  * `/api/requests`, so RequestWire is reused. Different listing scope —

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminTagSourcesApi.kt

@@ -0,0 +1,41 @@
+package com.fabledsword.minstrel.api.endpoints
+
+import com.fabledsword.minstrel.models.wire.AdminTagSourceWire
+import com.fabledsword.minstrel.models.wire.AdminTagSourcesListWire
+import com.fabledsword.minstrel.models.wire.TestTagSourceWire
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import retrofit2.http.Body
+import retrofit2.http.GET
+import retrofit2.http.PATCH
+import retrofit2.http.POST
+import retrofit2.http.Path
+
+/**
+ * Retrofit interface for `/api/admin/tag-sources` (#1521) — the admin
+ * surface for the tag-enrichment provider settings (#1490). Mirrors the
+ * web 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.
+ */
+interface AdminTagSourcesApi {
+    @GET("api/admin/tag-sources")
+    suspend fun list(): AdminTagSourcesListWire
+
+    @PATCH("api/admin/tag-sources/{id}")
+    suspend fun update(@Path("id") id: String, @Body body: UpdateTagSourceBody): AdminTagSourceWire
+
+    @POST("api/admin/tag-sources/{id}/test")
+    suspend fun test(@Path("id") id: String): TestTagSourceWire
+}
+
+/**
+ * PATCH body. Both fields are nullable + default-null so kotlinx omits the
+ * untouched one (the server reads a missing/null field as "leave
+ * unchanged"): send only `enabled` to toggle, only `apiKey` to set a key.
+ */
+@Serializable
+data class UpdateTagSourceBody(
+    val enabled: Boolean? = null,
+    @SerialName("api_key") val apiKey: String? = null,
+)

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminUsersApi.kt

@@ -10,8 +10,7 @@ import retrofit2.http.PUT
 import retrofit2.http.Path
 
 /**
- * Retrofit interface for `/api/admin/users`. Mirrors
- * `flutter_client/lib/api/endpoints/admin_users.dart`.
+ * Retrofit interface for `/api/admin/users`.
  *
  * Note: the PUT-auto-approve body field is `auto_approve`, NOT
  * `auto_approve_requests` — the request shape differs from the

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AuthApi.kt

@@ -6,8 +6,7 @@ import retrofit2.http.Body
 import retrofit2.http.POST
 
 /**
- * Retrofit interface for `/api/auth`. Mirrors
- * `flutter_client/lib/api/endpoints/auth.dart`.
+ * Retrofit interface for `/api/auth`.
  *
  * The actual session-cookie capture happens in
  * [com.fabledsword.minstrel.api.AuthCookieInterceptor]; we don't

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/CastApi.kt

@@ -29,21 +29,39 @@ 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 (M464 #5001): 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,
 )
 
 /**
  * Response body. [url] is a fully-formed stream URL with [token] and
  * [exp] already embedded as query params — callers pass it verbatim
- * to `AVTransport.SetAVTransportURI`.
+ * to `AVTransport.SetAVTransportURI`. [mime] + [title] are the bits
+ * the client needs to build DIDL-Lite metadata for that call: Sonos
+ * rejects empty DIDL with vendor error 1023, so the server hands back
+ * the track's MIME (from `tracks.file_format`) and title so the
+ * client can populate `<res protocolInfo>` and `<dc:title>` without
+ * a follow-up round trip.
  */
 @Serializable
 data class StreamTokenResponse(
     val token: String,
     val exp: Long,
     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,
 )

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiagnosticsApi.kt

@@ -0,0 +1,36 @@
+package com.fabledsword.minstrel.api.endpoints
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+import retrofit2.http.Body
+import retrofit2.http.POST
+
+/**
+ * Retrofit interface for device diagnostics ingest (M9). 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).
+ */
+interface DiagnosticsApi {
+    @POST("api/diagnostics")
+    suspend fun report(@Body body: DiagnosticsReportRequest)
+}
+
+@Serializable
+data class DiagnosticsReportRequest(
+    @SerialName("client_id") val clientId: String,
+    @SerialName("app_version") val appVersion: String? = null,
+    @SerialName("os_version") val osVersion: String? = null,
+    val events: List<DiagnosticEventWire>,
+)
+
+@Serializable
+data class DiagnosticEventWire(
+    val kind: String,
+    // Device-clock epoch milliseconds. The server stamps its own
+    // received_at; both are stored so a skewed device clock is visible.
+    @SerialName("occurred_at") val occurredAt: Long,
+    // Opaque structured payload carrying the event sub-type + fields.
+    val payload: JsonElement,
+)

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiscoverApi.kt

@@ -3,14 +3,17 @@ 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.SnoozeSuggestionBody
+import com.fabledsword.minstrel.models.wire.SuggestionSnoozeWire
 import retrofit2.http.Body
+import retrofit2.http.DELETE
 import retrofit2.http.GET
 import retrofit2.http.POST
+import retrofit2.http.Path
 import retrofit2.http.Query
 
 /**
  * Retrofit interface for Discover / Lidarr search / request creation.
- * Mirrors `flutter_client/lib/api/endpoints/discover.dart`.
  *
  * `/api/lidarr/search` has a 60s LRU on the server so quick re-types
  * of the same query are cheap.
@@ -30,4 +33,30 @@ interface DiscoverApi {
 
     @POST("api/requests")
     suspend fun createRequest(@Body body: CreateRequestBody)
+
+    /**
+     * Parks a suggestion — "not right now", NOT a dislike. Time-boxed
+     * server-side (90 days) and never fed into the taste profile.
+     *
+     * [body] must carry the artist's name: candidates are out-of-library, so
+     * the server has no local row to resolve a display name from and returns
+     * 400 without it.
+     */
+    @POST("api/discover/suggestions/{mbid}/snooze")
+    suspend fun snoozeSuggestion(
+        @Path("mbid") mbid: String,
+        @Body body: SnoozeSuggestionBody,
+    )
+
+    /** Brings a parked suggestion back. 404 when it wasn't snoozed. */
+    @DELETE("api/discover/suggestions/{mbid}/snooze")
+    suspend fun unsnoozeSuggestion(@Path("mbid") mbid: String)
+
+    /**
+     * Currently-parked suggestions. Server filters expired rows, so every
+     * row returned is still snoozed. This is the only route back to an
+     * un-snooze once the card has left the deck.
+     */
+    @GET("api/discover/snoozes")
+    suspend fun listSnoozes(): List<SuggestionSnoozeWire>
 }

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/EventsApi.kt

@@ -9,8 +9,7 @@ import retrofit2.http.Body
 import retrofit2.http.POST
 
 /**
- * Retrofit interface for `POST /api/events`. Mirrors the relevant
- * slice of `flutter_client/lib/api/endpoints/events.dart`. All four
+ * Retrofit interface for `POST /api/events`. All four
  * variants share the same URL — the discriminator is in the request
  * body's `type` field. Server contract is best-effort per spec;
  * callers (the live path in PlayEventsReporter) swallow errors and

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/HistoryApi.kt

@@ -5,10 +5,9 @@ import retrofit2.http.GET
 import retrofit2.http.Query
 
 /**
- * Retrofit interface for `/api/me/history`. Mirrors the relevant
- * subset of `flutter_client/lib/api/endpoints/me.dart` (only
- * `history()`; profile / timezone / quarantine endpoints land with
- * their respective phases).
+ * Retrofit interface for `/api/me/history` — history only. The profile,
+ * timezone and quarantine endpoints on `/api/me` live with their own
+ * features rather than here.
  */
 interface HistoryApi {
     @GET("api/me/history")

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/HomeApi.kt

@@ -4,10 +4,9 @@ import com.fabledsword.minstrel.models.wire.HomeIndexWire
 import retrofit2.http.GET
 
 /**
- * Retrofit interface for the Home discovery endpoint. Mirrors
- * `flutter_client/lib/api/endpoints/home.dart` — just the ID-only
- * `/api/home/index` variant. The Flutter port has a heavier
- * `/api/home` (full embedded payload) too; we don't use it because
+ * Retrofit interface for the Home discovery endpoint. Only the ID-only
+ * `/api/home/index` variant is used. The server also serves a heavier
+ * `/api/home` (full embedded payload); we don't use it because
  * the per-item hydration path (sync controller → Room → Flow) is
  * the only one the native client needs.
  */

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/LibraryApi.kt

@@ -2,14 +2,17 @@ package com.fabledsword.minstrel.api.endpoints
 
 import com.fabledsword.minstrel.models.wire.AlbumDetailWire
 import com.fabledsword.minstrel.models.wire.ArtistDetailWire
+import com.fabledsword.minstrel.models.wire.ArtistWire
+import com.fabledsword.minstrel.models.wire.GenreCountWire
+import com.fabledsword.minstrel.models.wire.PagedAlbumsWire
 import com.fabledsword.minstrel.models.wire.TrackWire
+import com.fabledsword.minstrel.models.wire.YearCountWire
 import retrofit2.http.GET
 import retrofit2.http.Path
 import retrofit2.http.Query
 
 /**
  * Retrofit interface for the server's native `/api/...` library surface.
- * Mirrors `flutter_client/lib/api/endpoints/library.dart` 1:1.
  *
  * Notes on shapes:
  *   - `GET /api/artists/{id}` returns ArtistDetailWire (ArtistRef fields
@@ -35,9 +38,69 @@ interface LibraryApi {
     @GET("api/artists/{id}/tracks")
     suspend fun getArtistTracks(@Path("id") id: String): List<TrackWire>
 
+    @GET("api/artists/{id}/similar")
+    suspend fun getSimilarArtists(
+        @Path("id") id: String,
+        @Query("limit") limit: Int = SIMILAR_ARTISTS_LIMIT,
+    ): List<ArtistWire>
+
+    @GET("api/artists/{id}/top-tracks")
+    suspend fun getArtistTopTracks(
+        @Path("id") id: String,
+        @Query("limit") limit: Int = TOP_TRACKS_LIMIT,
+    ): List<TrackWire>
+
     @GET("api/albums/{id}")
     suspend fun getAlbumDetail(@Path("id") id: String): AlbumDetailWire
 
     @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
+    // 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
+    // is a full mirror of the library, but /api/library/sync ships tracks whose
+    // files are missing and carries no flag for it (#2704), while the browse
+    // index filters them out -- so a locally-computed index would disagree with
+    // the server's and with the web client. One source of truth wins over
+    // offline capability here until #2704 is resolved.
+    @GET("api/library/genres")
+    suspend fun getGenres(): List<GenreCountWire>
+
+    @GET("api/library/years")
+    suspend fun getAlbumYears(): List<YearCountWire>
+
+    /**
+     * Albums carrying [genre] on any of their tracks.
+     *
+     * @Query, never @Path: "Rock/Pop" is a real ID3 tag and a slash cannot
+     * survive a path segment. Retrofit percent-encodes query values correctly;
+     * a @Path would either 404 or silently address a different genre.
+     */
+    @GET("api/library/albums")
+    suspend fun getAlbumsByGenre(
+        @Query("genre") genre: String,
+        @Query("limit") limit: Int,
+        @Query("offset") offset: Int,
+    ): PagedAlbumsWire
+
+    /**
+     * Albums released in an inclusive year range. Pass the same year twice for
+     * a single year. Sending a genre alongside these is a deliberate 400 on the
+     * server (`unsupported_filter_combination`) -- they are separate axes.
+     */
+    @GET("api/library/albums")
+    suspend fun getAlbumsByYear(
+        @Query("year_from") yearFrom: Int,
+        @Query("year_to") yearTo: Int,
+        @Query("limit") limit: Int,
+        @Query("offset") offset: Int,
+    ): PagedAlbumsWire
+
+    private companion object {
+        const val SIMILAR_ARTISTS_LIMIT = 12
+        const val TOP_TRACKS_LIMIT = 5
+    }
 }

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/LikesApi.kt

@@ -7,8 +7,7 @@ import retrofit2.http.POST
 import retrofit2.http.Path
 
 /**
- * Retrofit interface for `/api/likes`. Mirrors
- * `flutter_client/lib/api/endpoints/likes.dart`.
+ * Retrofit interface for `/api/likes`.
  *
  * Path segment `kind` is one of "artists" | "albums" | "tracks"
  * (plural, matching the server route). The Repository hides that

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/MeApi.kt

@@ -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
@@ -11,7 +12,6 @@ import retrofit2.http.PUT
 
 /**
  * Retrofit interface for the `/api/me` endpoints — caller-scoped account endpoints.
- * Mirrors the relevant slice of `flutter_client/lib/api/endpoints/settings.dart`.
  *
  * History + timezone + system-playlists-status live under /api/me too
  * but are handled by their respective feature repositories; this
@@ -60,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
 }
 
 /**

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/NotificationsApi.kt

@@ -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 (M489). 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>)

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/PlaylistsApi.kt

@@ -11,8 +11,7 @@ import retrofit2.http.Path
 import retrofit2.http.Query
 
 /**
- * Retrofit interface for `/api/playlists`. Mirrors
- * `flutter_client/lib/api/endpoints/playlists.dart`.
+ * Retrofit interface for `/api/playlists`.
  */
 interface PlaylistsApi {
     /**
@@ -54,7 +53,7 @@ interface PlaylistsApi {
      * 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
-     * the stored order. Mirrors `playlists.dart.systemShuffle`.
+     * the stored order.
      */
     @GET("api/playlists/system/{kind}/shuffle")
     suspend fun systemShuffle(@Path("kind") variant: String): PlaylistDetailWire

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/QuarantineApi.kt

@@ -8,9 +8,8 @@ import retrofit2.http.POST
 import retrofit2.http.Path
 
 /**
- * Retrofit interface for `/api/quarantine`. Mirrors the relevant
- * parts of `flutter_client/lib/api/endpoints/quarantine.dart` (flag
- * and unflag) plus the `/api/quarantine/mine` endpoint from `me.dart`.
+ * Retrofit interface for `/api/quarantine`: flag and unflag, plus the
+ * `/api/quarantine/mine` listing.
  *
  * Both flag and unflag are user-scoped — callers act on their own
  * quarantine entries. The cross-user admin surface is a separate

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/RadioApi.kt

@@ -5,9 +5,7 @@ import retrofit2.http.GET
 import retrofit2.http.Query
 
 /**
- * Retrofit interface for `/api/radio`. Mirrors the relevant slice of
- * `flutter_client/lib/api/endpoints/radio.dart` (a single GET that
- * returns the seeded queue). The server picks a fresh shuffle each
+ * Retrofit interface for `/api/radio`. The server picks a fresh shuffle each
  * invocation — clients call this once per radio start.
  */
 interface RadioApi {

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/ReplayGainApi.kt

@@ -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 (#4997), 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
+}

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/RequestsApi.kt

@@ -6,8 +6,7 @@ import retrofit2.http.GET
 import retrofit2.http.Path
 
 /**
- * Retrofit interface for the user-side `/api/requests`. Mirrors
- * `flutter_client/lib/api/endpoints/requests.dart`.
+ * Retrofit interface for the user-side `/api/requests`.
  *
  * Server scopes results to the caller — admins see only their own
  * requests through this endpoint. The cross-user admin view lives on

android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/SearchApi.kt

@@ -5,8 +5,7 @@ import retrofit2.http.GET
 import retrofit2.http.Query
 
 /**
- * Retrofit interface for `GET /api/search`. Mirrors
- * `flutter_client/lib/api/endpoints/search.dart`. Server returns 400
+ * Retrofit interface for `GET /api/search`. Server returns 400
  * on empty/whitespace-only `q` — the caller is responsible for
  * guarding.
  */

android/app/src/main/java/com/fabledsword/minstrel/auth/AuthController.kt

@@ -1,6 +1,7 @@
 package com.fabledsword.minstrel.auth
 
 import com.fabledsword.minstrel.api.endpoints.AuthApi
+import com.fabledsword.minstrel.api.endpoints.MeApi
 import com.fabledsword.minstrel.di.ApplicationScope
 import com.fabledsword.minstrel.models.UserRef
 import com.fabledsword.minstrel.models.wire.LoginRequestBody
@@ -16,8 +17,7 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Singleton facade over the auth state machine. Mirrors Flutter's
- * `AuthController` from `auth_provider.dart`.
+ * Singleton facade over the auth state machine.
  *
  * Cookie persistence is handled by [AuthCookieInterceptor] capturing
  * Set-Cookie on the login response; the user identity itself
@@ -35,6 +35,7 @@ class AuthController @Inject constructor(
     retrofit: Retrofit,
 ) {
     private val api: AuthApi = retrofit.create()
+    private val meApi: MeApi = retrofit.create()
 
     private val currentUserState = MutableStateFlow<UserRef?>(null)
     val currentUser: StateFlow<UserRef?> = currentUserState.asStateFlow()
@@ -55,6 +56,10 @@ class AuthController @Inject constructor(
                 currentUserState.value = raw?.let { decodeUser(it) }
             }
         }
+        // Refresh from /api/me on startup so a remotely-changed account
+        // flag (e.g. admin enabling debug mode, M9) reaches the device
+        // without a re-login. Best-effort; failures keep the cached value.
+        scope.launch { refreshProfile() }
     }
 
     /**
@@ -72,9 +77,32 @@ class AuthController @Inject constructor(
         )
         currentUserState.value = user
         authStore.setUserJson(json.encodeToString(UserRef.serializer(), user))
+        // Pull the fuller /me shape (carries debug_mode_enabled) right
+        // after login so the diagnostics gate is correct without waiting
+        // for the next startup refresh.
+        scope.launch { refreshProfile() }
         return user
     }
 
+    /**
+     * Re-fetch the caller's profile from /api/me and update currentUser
+     * + persisted userJson. Carries account-level flags (debug mode)
+     * that aren't in the login response. Best-effort: a network failure
+     * leaves the cached identity untouched. No-op when signed out.
+     */
+    suspend fun refreshProfile() {
+        if (!isSignedIn) return
+        val p = runCatching { meApi.getProfile() }.getOrNull() ?: return
+        val user = UserRef(
+            id = p.id,
+            username = p.username,
+            isAdmin = p.isAdmin,
+            debugModeEnabled = p.debugModeEnabled,
+        )
+        currentUserState.value = user
+        authStore.setUserJson(json.encodeToString(UserRef.serializer(), user))
+    }
+
     /**
      * Clears the local session immediately and best-effort hits
      * `/api/auth/logout` so the server can drop its session row.

android/app/src/main/java/com/fabledsword/minstrel/auth/AuthStore.kt

@@ -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** (M462 #4985): it is persisted
+ * through [SessionVault] (Keystore-encrypted), not the Room row. On the
+ * first launch after the upgrade, a cookie still in the row is moved into
+ * the vault and the column cleared, so nobody is signed out by the change.
+ * If the Keystore cannot be used on a device, the cookie stays in the row
+ * as before 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)
@@ -59,17 +75,42 @@ class AuthStore @Inject constructor(
     private val cacheSettingsState = MutableStateFlow(CacheSettings.DEFAULT)
     val cacheSettings: StateFlow<CacheSettings> = cacheSettingsState.asStateFlow()
 
+    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 (M489 #5347): 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
             }
         }
     }
@@ -81,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 (rule 156: a wedged
+     * Keystore must not 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) {
@@ -112,7 +201,29 @@ class AuthStore @Inject constructor(
         scope.launch { persistCacheSettings(encoded) }
     }
 
-    private suspend fun persistCookie(value: String?) {
+    fun setDiagnosticsOptOut(value: Boolean) {
+        diagnosticsOptOutState.value = value
+        scope.launch { persistDiagnosticsOptOut(value) }
+    }
+
+    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 {
@@ -160,9 +271,27 @@ class AuthStore @Inject constructor(
         }
     }
 
+    private suspend fun persistDiagnosticsOptOut(value: Boolean) {
+        if (dao.get() == null) {
+            dao.upsert(currentEntity().copy(diagnosticsOptOut = value))
+        } else {
+            dao.setDiagnosticsOptOut(value)
+        }
+    }
+
+    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,
@@ -171,10 +300,20 @@ class AuthStore @Inject constructor(
             CacheSettings.serializer(),
             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
     }
 }

android/app/src/main/java/com/fabledsword/minstrel/auth/SessionVault.kt

@@ -0,0 +1,147 @@
+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 (M462 #4985).
+ *
+ * The cookie is a bearer credential: anyone holding it is signed in as the
+ * user until the server expires or revokes it. It used to sit in plain text
+ * in the Room `auth_session` row, readable from any copy of the app's data
+ * directory (a rooted device, an adb backup of a debuggable build, a
+ * forensic image). Now 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
+}

android/app/src/main/java/com/fabledsword/minstrel/auth/ui/AuthGateViewModel.kt

@@ -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
- * than AuthStore's StateFlow because the StateFlow defaults to null
- * until Room's first async emission — we need a definitive answer
- * before drawing any nav graph.
+ * persisted auth state. Reads the row from AuthSessionDao directly, and
+ * the session cookie only after [AuthStore.awaitSessionHydrated]: both
+ * StateFlows default to null until their async load lands, and we need a
+ * definitive answer before drawing any nav graph. The cookie is no longer
+ * in the row (it lives in the Keystore-backed SessionVault, #4985).
  *
  *   - 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() ->
-                    ServerUrl
-                row.sessionCookie.isNullOrEmpty() -> Login
+                row.baseUrl == AuthStore.DEFAULT_BASE_URL && !signedIn -> ServerUrl
+                !signedIn -> Login
                 else -> Home
             }
         }

android/app/src/main/java/com/fabledsword/minstrel/cache/ShuffleSource.kt

@@ -12,8 +12,7 @@ import javax.inject.Singleton
 private const val POOL_LIMIT = 100
 
 /**
- * Offline play sources over the local audio-cache index. Mirrors
- * `flutter_client/lib/cache/shuffle_source.dart`.
+ * Offline play sources over the local audio-cache index.
  *
  * Both pools are UNIONs over the cache regardless of storage bucket
  * (liked AND recently-played both included). The two-bucket split is
@@ -58,6 +57,14 @@ class ShuffleSource @Inject constructor(
     private suspend fun materialize(orderedIds: List<String>): List<TrackRef> {
         if (orderedIds.isEmpty()) return emptyList()
         val byId = trackDao.getByIds(orderedIds).associateBy { it.id }
-        return orderedIds.mapNotNull { byId[it]?.toDomain() }
+        return orderedIds.mapNotNull { id ->
+            // Clear the server's missing mark (#2704). 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
+            // would otherwise throw away tracks that work perfectly. Missing
+            // means "cannot stream", not "cannot play".
+            byId[id]?.toDomain()?.copy(unavailable = false)
+        }
     }
 }

android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheConfig.kt

@@ -1,7 +1,7 @@
 package com.fabledsword.minstrel.cache.audiocache
 
 /**
- * Defaults for the 2-bucket audio cache. Matches the Flutter client.
+ * 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

android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheSettings.kt

@@ -6,8 +6,7 @@ private const val FIVE_GIB_BYTES = 5L * 1024 * 1024 * 1024
 private const val DEFAULT_PREFETCH_WINDOW = 5
 
 /**
- * User-tunable audio cache settings. Mirrors Flutter's `CacheSettings`
- * (cache_settings_provider.dart) field-for-field. Persisted as a JSON
+ * 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

android/app/src/main/java/com/fabledsword/minstrel/cache/db/AppDatabase.kt

@@ -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,11 +13,13 @@ 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
 import com.fabledsword.minstrel.cache.db.dao.CachedQuarantineDao
 import com.fabledsword.minstrel.cache.db.dao.CachedTrackDao
+import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
 import com.fabledsword.minstrel.cache.db.dao.SyncMetadataDao
 import com.fabledsword.minstrel.cache.db.entities.AudioCacheIndexEntity
 import com.fabledsword.minstrel.cache.db.entities.AuthSessionEntity
@@ -25,11 +29,14 @@ 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
 import com.fabledsword.minstrel.cache.db.entities.CachedQuarantineEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedTrackEntity
+import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
 import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity
 
 /**
@@ -61,8 +68,31 @@ import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity
         CachedHomeIndexEntity::class,
         CachedHistorySnapshotEntity::class,
         AuthSessionEntity::class,
+        DiagnosticEventEntity::class,
+        CachedNotificationEntity::class,
+        CachedNotificationSettingsEntity::class,
     ],
-    version = 6,
+    // v12: + auth_session.backgroundDelivery and notifiedUpTo, the device's
+    // background-delivery choice and its shade high-water mark (M489 #5347).
+    // v11: + cached_notifications and cached_notification_settings, the
+    // notifications inbox and its settings (M489). 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 (M464 #5000).
+    // 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 (M464 #4998). 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 (#2704),
+    // so cache-first surfaces stop offering files that cannot stream.
+    // v7: + diagnostic_events table (M9) and the diagnosticsOptOut column
+    // on auth_session. Pre-v1 destructive fallback rebuilds on mismatch —
+    // which is exactly right here: the next sync refills every row with the
+    // new column populated, so there is nothing to migrate by hand.
+    version = 12,
     exportSchema = true,
 )
 @TypeConverters(MinstrelTypeConverters::class)
@@ -81,4 +111,59 @@ abstract class AppDatabase : RoomDatabase() {
     abstract fun cachedHomeIndexDao(): CachedHomeIndexDao
     abstract fun cachedHistorySnapshotDao(): CachedHistorySnapshotDao
     abstract fun authSessionDao(): AuthSessionDao
+    abstract fun diagnosticEventDao(): DiagnosticEventDao
+    abstract fun cachedNotificationDao(): CachedNotificationDao
+}
+
+/** v8 → v9: add the nullable normalization preference column (#4998). */
+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 (#5000). 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 (M489). 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 (M489 #5347). 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")
+    }
 }

android/app/src/main/java/com/fabledsword/minstrel/cache/db/DatabaseModule.kt

@@ -10,6 +10,8 @@ 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
 import com.fabledsword.minstrel.cache.db.dao.CachedQuarantineDao
@@ -36,6 +38,7 @@ object DatabaseModule {
             // launch, so users lose only the unsynced mutation queue
             // (acceptable while we're iterating). Replace with explicit
             // Migration entries before the first tagged release.
+            .addMigrations(MIGRATION_8_9, MIGRATION_9_10, MIGRATION_10_11, MIGRATION_11_12)
             .fallbackToDestructiveMigration(dropAllTables = true)
             .build()
 
@@ -105,5 +108,15 @@ object DatabaseModule {
     fun provideAudioCacheIndexDao(db: AppDatabase): AudioCacheIndexDao =
         db.audioCacheIndexDao()
 
+    @Provides
+    @Singleton
+    fun provideDiagnosticEventDao(db: AppDatabase): DiagnosticEventDao =
+        db.diagnosticEventDao()
+
+    @Provides
+    @Singleton
+    fun provideCachedNotificationDao(db: AppDatabase): CachedNotificationDao =
+        db.cachedNotificationDao()
+
     private const val DATABASE_NAME = "minstrel.db"
 }

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/AuthSessionDao.kt

@@ -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 {
@@ -42,4 +43,20 @@ interface AuthSessionDao {
     /** Partial update: change only the serialized cache settings. */
     @Query("UPDATE auth_session SET cacheSettingsJson = :json WHERE id = 0")
     suspend fun setCacheSettingsJson(json: String?)
+
+    /** 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?)
 }

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedAlbumDao.kt

@@ -24,6 +24,14 @@ interface CachedAlbumDao {
     @Query("SELECT * FROM cached_albums WHERE id = :id")
     fun observeById(id: String): Flow<CachedAlbumEntity?>
 
+    @Query(
+        "SELECT * FROM cached_albums " +
+            "WHERE title LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "ORDER BY sortTitle COLLATE NOCASE ASC " +
+            "LIMIT :limit",
+    )
+    suspend fun searchByTitle(q: String, limit: Int): List<CachedAlbumEntity>
+
     @Query("SELECT id FROM cached_albums WHERE fetchedAt < :before LIMIT :limit")
     suspend fun idsStaleBefore(before: Long, limit: Int): List<String>
 

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedArtistDao.kt

@@ -18,6 +18,14 @@ interface CachedArtistDao {
     @Query("SELECT * FROM cached_artists WHERE id = :id")
     fun observeById(id: String): Flow<CachedArtistEntity?>
 
+    @Query(
+        "SELECT * FROM cached_artists " +
+            "WHERE name LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "ORDER BY sortName COLLATE NOCASE ASC " +
+            "LIMIT :limit",
+    )
+    suspend fun searchByName(q: String, limit: Int): List<CachedArtistEntity>
+
     @Query("SELECT id FROM cached_artists WHERE fetchedAt < :before LIMIT :limit")
     suspend fun idsStaleBefore(before: Long, limit: Int): List<String>
 

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedHomeIndexDao.kt

@@ -4,6 +4,7 @@ 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.CachedHomeIndexEntity
 import kotlinx.coroutines.flow.Flow
 
@@ -21,12 +22,32 @@ interface CachedHomeIndexDao {
     )
     suspend fun getBySection(section: String): List<CachedHomeIndexEntity>
 
+    /** True when Home has any cached section rows to render. */
+    @Query("SELECT EXISTS(SELECT 1 FROM cached_home_index)")
+    suspend fun hasAny(): Boolean
+
     @Insert(onConflict = OnConflictStrategy.REPLACE)
     suspend fun upsertAll(rows: List<CachedHomeIndexEntity>)
 
-    /** Replace-all pattern; sync wipes a section then re-inserts. */
-    @Query("DELETE FROM cached_home_index WHERE section = :section")
-    suspend fun deleteBySection(section: String)
+    @Query("DELETE FROM cached_home_index WHERE section IN (:sections)")
+    suspend fun deleteSections(sections: List<String>)
+
+    /**
+     * Swaps every listed section's rows in ONE transaction.
+     *
+     * Atomicity is the point, not just tidiness: Room's
+     * InvalidationTracker only notifies observers after the transaction
+     * commits, so [observeBySection] never sees the empty gap between the
+     * delete and the re-insert. Replacing sections one at a time (and
+     * un-transacted) made each Home row emit `emptyList()` — visibly
+     * collapsing — before refilling, and made the seven sections do it in
+     * sequence rather than as a single content swap.
+     */
+    @Transaction
+    suspend fun replaceSections(sections: List<String>, rows: List<CachedHomeIndexEntity>) {
+        deleteSections(sections)
+        if (rows.isNotEmpty()) upsertAll(rows)
+    }
 
     @Query("DELETE FROM cached_home_index")
     suspend fun clear()

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedMutationDao.kt

@@ -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
 }

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedNotificationDao.kt

@@ -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)
+}

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedPlaylistDao.kt

@@ -31,6 +31,20 @@ interface CachedPlaylistDao {
     @Query("SELECT * FROM cached_playlists WHERE id = :id")
     suspend fun getById(id: String): CachedPlaylistEntity?
 
+    /**
+     * Per-playlist count of member tracks resident in the audio cache index.
+     * LEFT JOINs so playlists with zero cached tracks still appear
+     * (cachedCount = 0). Drives the offline "fully cached" greying.
+     */
+    @Query(
+        "SELECT p.id AS playlistId, COUNT(a.trackId) AS cachedCount " +
+            "FROM cached_playlists p " +
+            "LEFT JOIN cached_playlist_tracks t ON t.playlistId = p.id " +
+            "LEFT JOIN audio_cache_index a ON a.trackId = t.trackId " +
+            "GROUP BY p.id",
+    )
+    fun observeCachedCounts(): Flow<List<PlaylistCachedCount>>
+
     @Insert(onConflict = OnConflictStrategy.REPLACE)
     suspend fun upsertAll(rows: List<CachedPlaylistEntity>)
 
@@ -45,7 +59,6 @@ interface CachedPlaylistDao {
 
     /**
      * Atomically reconciles the cache against the fresh list response.
-     * Mirrors `flutter_client/lib/playlists/playlists_provider.dart:54` —
      * `BuildSystemPlaylists` rotates system-playlist UUIDs every
      * rebuild, so upsert alone leaves stale rows whose detail fetch
      * 404s. Delete any of the user's rows not in [freshOwnedIds] (this

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedPlaylistTrackDao.kt

@@ -4,6 +4,7 @@ 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.CachedPlaylistTrackEntity
 import kotlinx.coroutines.flow.Flow
 
@@ -35,10 +36,33 @@ interface CachedPlaylistTrackDao {
     @Query("SELECT MAX(position) FROM cached_playlist_tracks WHERE playlistId = :playlistId")
     suspend fun maxPosition(playlistId: String): Int?
 
-    /** Replace-all pattern for a playlist; called after a sync delta lands. */
     @Query("DELETE FROM cached_playlist_tracks WHERE playlistId = :playlistId")
     suspend fun deleteByPlaylist(playlistId: String)
 
+    /**
+     * Replaces a playlist's whole membership in ONE transaction; called
+     * after a refresh or a sync delta lands.
+     *
+     * 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
+     * collapse to empty and refill before issue #2327 fixed the equivalent
+     * write in `CachedHomeIndexDao`.
+     *
+     * Nothing observes [observeByPlaylist] live today, so this is
+     * pre-emptive: it means making playlist detail cache-first later can't
+     * silently reintroduce that flicker.
+     */
+    @Transaction
+    suspend fun replacePlaylistTracks(
+        playlistId: String,
+        rows: List<CachedPlaylistTrackEntity>,
+    ) {
+        deleteByPlaylist(playlistId)
+        if (rows.isNotEmpty()) upsertAll(rows)
+    }
+
     @Query(
         "DELETE FROM cached_playlist_tracks " +
             "WHERE playlistId = :playlistId AND trackId IN (:trackIds)",

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedTrackDao.kt

@@ -24,12 +24,41 @@ interface CachedTrackDao {
     @Query("SELECT * FROM cached_tracks WHERE id IN (:ids)")
     suspend fun getByIds(ids: List<String>): List<CachedTrackEntity>
 
+    @Query(
+        "SELECT * FROM cached_tracks " +
+            "WHERE title LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "ORDER BY title COLLATE NOCASE ASC " +
+            "LIMIT :limit",
+    )
+    suspend fun searchByTitle(q: String, limit: Int): List<CachedTrackEntity>
+
     @Query("SELECT id FROM cached_tracks WHERE fetchedAt < :before LIMIT :limit")
     suspend fun idsStaleBefore(before: Long, limit: Int): List<String>
 
     @Insert(onConflict = OnConflictStrategy.REPLACE)
     suspend fun upsertAll(rows: List<CachedTrackEntity>)
 
+    /**
+     * ReplayGain values for [ids] (M464 #5000): 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?,
+)

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/DiagnosticEventDao.kt

@@ -0,0 +1,35 @@
+package com.fabledsword.minstrel.cache.db.dao
+
+import androidx.room.Dao
+import androidx.room.Insert
+import androidx.room.Query
+import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
+
+@Dao
+interface DiagnosticEventDao {
+    @Insert
+    suspend fun insert(row: DiagnosticEventEntity): Long
+
+    /** FIFO drain order so the uploader sends oldest-first. */
+    @Query("SELECT * FROM diagnostic_events ORDER BY id ASC LIMIT :limit")
+    suspend fun takeBatch(limit: Int): List<DiagnosticEventEntity>
+
+    @Query("SELECT COUNT(*) FROM diagnostic_events")
+    suspend fun count(): Int
+
+    @Query("DELETE FROM diagnostic_events WHERE id IN (:ids)")
+    suspend fun deleteByIds(ids: List<Long>)
+
+    /**
+     * Ring-buffer trim: drop the oldest rows beyond [keep]. Called after
+     * insert so a long offline stretch can't grow the buffer unbounded.
+     */
+    @Query(
+        "DELETE FROM diagnostic_events WHERE id NOT IN " +
+            "(SELECT id FROM diagnostic_events ORDER BY id DESC LIMIT :keep)",
+    )
+    suspend fun trimToNewest(keep: Int)
+
+    @Query("DELETE FROM diagnostic_events")
+    suspend fun clear()
+}

android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/PlaylistCachedCount.kt

@@ -0,0 +1,11 @@
+package com.fabledsword.minstrel.cache.db.dao
+
+/**
+ * Projection: how many of a playlist's member tracks are resident in the audio
+ * cache index. Backs the offline "fully cached" greying — a playlist is fully
+ * available offline when [cachedCount] reaches its `trackCount`.
+ */
+data class PlaylistCachedCount(
+    val playlistId: String,
+    val cachedCount: Int,
+)

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AudioCacheIndexEntity.kt

@@ -8,7 +8,7 @@ import kotlinx.datetime.Instant
 
 /**
  * One row per fully-downloaded audio file. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `AudioCacheIndex` Drift table.
+ * the Flutter client's `AudioCacheIndex` Drift table.
  *
  * Drives the 2-bucket LRU eviction (Phase 12 AudioCacheEvictionWorker):
  *   - `incidental` files (streamed-and-cached side effect) evict first

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AuthSessionEntity.kt

@@ -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
@@ -36,4 +38,30 @@ data class AuthSessionEntity(
      * CacheSettings shape evolves.
      */
     val cacheSettingsJson: String? = null,
+    /**
+     * Per-device opt-out of diagnostics reporting (M9). 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 (M464 #4998). Null = never fetched; the
+     * defaults apply. Kept so offline playback still levels.
+     */
+    val normalizationJson: String? = null,
+    /**
+     * "Notifications when the app is closed" (M489 #5347): 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,
 )

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedAlbumEntity.kt

@@ -6,7 +6,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * Cache row for one album. Mirrors `flutter_client/lib/cache/db.dart`'s
+ * Cache row for one album. Mirrors the Flutter client's
  * `CachedAlbums` Drift table.
  */
 @Entity(tableName = "cached_albums")
@@ -18,5 +18,8 @@ data class CachedAlbumEntity(
     val releaseDate: String? = null,
     val coverPath: String? = null,
     val mbid: String? = null,
+    // ReplayGain 2.0 album values (M464); null until every track is measured.
+    val albumGain: Float? = null,
+    val albumPeak: Float? = null,
     val fetchedAt: Instant = Clock.System.now(),
 )

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedArtistEntity.kt

@@ -6,7 +6,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * Cache row for one artist. Mirrors `flutter_client/lib/cache/db.dart`'s
+ * Cache row for one artist. Mirrors the Flutter client's
  * `CachedArtists` Drift table.
  *
  * Column names follow Kotlin idiom (camelCase) rather than Drift's

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedHomeIndexEntity.kt

@@ -6,7 +6,7 @@ import kotlinx.datetime.Instant
 
 /**
  * Per-item row driving the Home screen sections. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedHomeIndex` Drift table.
+ * the Flutter client's `CachedHomeIndex` Drift table.
  *
  * `section` is one of (matching /api/home keys):
  *   - "recently_added_albums"
@@ -14,6 +14,11 @@ import kotlinx.datetime.Instant
  *   - "rediscover_artists"
  *   - "most_played_tracks"
  *   - "last_played_artists"
+ *   - "you_might_like_albums"
+ *   - "you_might_like_artists"
+ *
+ * New `section` values need no schema change — the column stores the
+ * string verbatim and the DAO keys on it.
  *
  * `entityType` is "album" | "artist" | "track" — dispatches hydration
  * to the right per-entity endpoint when a tile is rendered.

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedLikeEntity.kt

@@ -5,7 +5,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * Like membership row. Mirrors `flutter_client/lib/cache/db.dart`'s
+ * Like membership row. Mirrors the Flutter client's
  * `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.

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedMutationEntity.kt

@@ -7,7 +7,7 @@ import kotlinx.datetime.Instant
 
 /**
  * One row per pending offline-write. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedMutations` Drift table.
+ * 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

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationEntity.kt

@@ -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 (M489), 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?,
+)

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationSettingsEntity.kt

@@ -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 (M489), 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
+    }
+}

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistEntity.kt

@@ -7,7 +7,7 @@ import kotlinx.datetime.Instant
 
 /**
  * Cache row for one playlist (user or system). Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedPlaylists` Drift table.
+ * 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.

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistTrackEntity.kt

@@ -4,7 +4,7 @@ import androidx.room.Entity
 
 /**
  * Ordered membership of tracks within a playlist. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedPlaylistTracks` Drift table.
+ * the Flutter client's `CachedPlaylistTracks` Drift table.
  * Composite PK so the same track can only appear once per playlist;
  * `position` carries the ordering.
  */

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedQuarantineEntity.kt

@@ -7,7 +7,7 @@ import kotlinx.datetime.Instant
 
 /**
  * The current user's quarantine flag for one track. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedQuarantineMine` Drift
+ * the Flutter client's `CachedQuarantineMine` Drift
  * table.
  *
  * The flat denormalized track/album/artist columns let the Quarantine

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedResumeStateEntity.kt

@@ -8,7 +8,7 @@ import kotlinx.datetime.Instant
 /**
  * Single-row snapshot of the last playback session — queue (as JSON),
  * current index, position, and source tag. Mirrors
- * `flutter_client/lib/cache/db.dart`'s `CachedResumeState` Drift table.
+ * 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

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedTrackEntity.kt

@@ -6,8 +6,12 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * Cache row for one track. Mirrors `flutter_client/lib/cache/db.dart`'s
+ * Cache row for one track. Mirrors the Flutter client's
  * `CachedTracks` Drift table.
+ *
+ * [missing] carries the server's missing-file mark (#2704). 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.
  */
 @Entity(tableName = "cached_tracks")
 data class CachedTrackEntity(
@@ -21,5 +25,10 @@ data class CachedTrackEntity(
     val filePath: String? = null,
     val fileFormat: String? = null,
     val genre: String? = null,
+    val missing: Boolean = false,
+    // ReplayGain 2.0 track values (M464), 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(),
 )

android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/DiagnosticEventEntity.kt

@@ -0,0 +1,28 @@
+package com.fabledsword.minstrel.cache.db.entities
+
+import androidx.room.Entity
+import androidx.room.PrimaryKey
+
+/**
+ * One buffered device-diagnostics event (M9). 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
+ * offline — so events must persist locally through the dead zone and
+ * upload on recovery, without clogging the user-data mutation replay.
+ *
+ * `occurredAtMillis` is the device-clock epoch-ms when the event happened
+ * (the server also stamps its own received_at). `payloadJson` is an
+ * opaque JSON object carrying the event sub-type + fields.
+ */
+@Entity(tableName = "diagnostic_events")
+data class DiagnosticEventEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val kind: String,
+    val occurredAtMillis: Long,
+    val payloadJson: String,
+)

android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationQueue.kt

@@ -1,13 +1,21 @@
 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
+import kotlinx.coroutines.flow.asSharedFlow
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
 import javax.inject.Inject
 import javax.inject.Singleton
 
+private const val QUEUED_MESSAGE = "Saved — will sync when online"
+
 /**
  * Stable mutation kinds the queue knows how to replay. Strings are
  * persisted in `cached_mutations.kind` so renaming a variant breaks
@@ -22,6 +30,35 @@ object MutationKind {
     const val PLAY_OFFLINE: String = "play_offline"
     const val REQUEST_CANCEL: String = "request_cancel"
     const val PLAYBACK_ERROR_REPORT: String = "playback_error_report"
+
+    // 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
+    // background avoids the duplicate + orphan row the old offline-on-stop
+    // path produced (see 2026-06-11 contract audit).
+    const val PLAY_ENDED: String = "play_ended"
+
+    // #2374 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"
+
+    // M464 #4998 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"
+
+    // M489 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"
+
+    // M489 per-kind channel setting. 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"
 }
 
 /**
@@ -66,52 +103,65 @@ data class RequestCreatePayload(
  * This matches `feedback_offline_first_for_server_writes` — writes
  * 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,
     private val json: Json,
 ) {
+    // capacity=1 DROP_OLDEST so a burst of user enqueues (e.g. liking N
+    // tracks while offline) surfaces as one snackbar rather than queueing
+    // N. replay=0 because a hint observed at enqueue time isn't useful
+    // to a screen that mounts later.
+    private val _userEnqueueHints = MutableSharedFlow<String>(
+        replay = 0,
+        extraBufferCapacity = 1,
+        onBufferOverflow = BufferOverflow.DROP_OLDEST,
+    )
+
+    /**
+     * Hint stream consumed by [com.fabledsword.minstrel.shared.widgets.ShellScaffold]
+     * to surface "Saved — will sync when online" as a snackbar whenever a
+     * user-driven write hits the offline-fallback path. Background-only
+     * enqueues (play-events, playback-error reports) do not emit — those
+     * fire from non-foreground paths where a snackbar would be either
+     * dropped (no shell mounted) or jarring (lock-screen toggle).
+     */
+    val userEnqueueHints: SharedFlow<String> = _userEnqueueHints.asSharedFlow()
+
     suspend fun enqueueLikeToggle(
         entityType: String,
         entityId: String,
         desiredState: Boolean,
-    ): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.LIKE_TOGGLE,
-            payload = json.encodeToString(
-                LikeTogglePayload.serializer(),
-                LikeTogglePayload(entityType, entityId, desiredState),
-            ),
+    ): Long = insertUserDriven(
+        MutationKind.LIKE_TOGGLE,
+        json.encodeToString(
+            LikeTogglePayload.serializer(),
+            LikeTogglePayload(entityType, entityId, desiredState),
         ),
     )
 
-    suspend fun enqueueRequestCreate(payload: RequestCreatePayload): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.REQUEST_CREATE,
-            payload = json.encodeToString(RequestCreatePayload.serializer(), payload),
-        ),
+    suspend fun enqueueRequestCreate(payload: RequestCreatePayload): Long = insertUserDriven(
+        MutationKind.REQUEST_CREATE,
+        json.encodeToString(RequestCreatePayload.serializer(), payload),
     )
 
-    suspend fun enqueueQuarantineUnflag(trackId: String): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.QUARANTINE_UNFLAG,
-            payload = json.encodeToString(
-                QuarantineUnflagPayload.serializer(),
-                QuarantineUnflagPayload(trackId),
-            ),
+    suspend fun enqueueQuarantineUnflag(trackId: String): Long = insertUserDriven(
+        MutationKind.QUARANTINE_UNFLAG,
+        json.encodeToString(
+            QuarantineUnflagPayload.serializer(),
+            QuarantineUnflagPayload(trackId),
         ),
     )
 
     suspend fun enqueuePlaylistAppend(
         playlistId: String,
         trackIds: List<String>,
-    ): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.PLAYLIST_APPEND,
-            payload = json.encodeToString(
-                PlaylistAppendPayload.serializer(),
-                PlaylistAppendPayload(playlistId, trackIds),
-            ),
+    ): Long = insertUserDriven(
+        MutationKind.PLAYLIST_APPEND,
+        json.encodeToString(
+            PlaylistAppendPayload.serializer(),
+            PlaylistAppendPayload(playlistId, trackIds),
         ),
     )
 
@@ -119,13 +169,63 @@ class MutationQueue @Inject constructor(
         trackId: String,
         reason: String,
         notes: String,
-    ): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.QUARANTINE_FLAG,
-            payload = json.encodeToString(
-                QuarantineFlagPayload.serializer(),
-                QuarantineFlagPayload(trackId, reason, notes),
-            ),
+    ): Long = insertUserDriven(
+        MutationKind.QUARANTINE_FLAG,
+        json.encodeToString(
+            QuarantineFlagPayload.serializer(),
+            QuarantineFlagPayload(trackId, reason, notes),
+        ),
+    )
+
+    /**
+     * Queues a suggestion snooze (or its undo) for replay. [desiredSnoozed]
+     * is the TARGET state, so repeated taps collapse to one replay.
+     *
+     * [name] is carried even for an un-snooze, where the server ignores it,
+     * so a single payload shape serves both directions.
+     */
+    suspend fun enqueueSuggestionSnoozeToggle(
+        mbid: String,
+        name: String,
+        desiredSnoozed: Boolean,
+    ): Long = insertUserDriven(
+        MutationKind.SUGGESTION_SNOOZE_TOGGLE,
+        json.encodeToString(
+            SuggestionSnoozeTogglePayload.serializer(),
+            SuggestionSnoozeTogglePayload(mbid, name, desiredSnoozed),
+        ),
+    )
+
+    /** 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(
+            RequestCancelPayload.serializer(),
+            RequestCancelPayload(requestId),
         ),
     )
 
@@ -136,24 +236,46 @@ class MutationQueue @Inject constructor(
         ),
     )
 
-    suspend fun enqueueRequestCancel(requestId: String): Long = dao.insert(
-        CachedMutationEntity(
-            kind = MutationKind.REQUEST_CANCEL,
-            payload = json.encodeToString(
-                RequestCancelPayload.serializer(),
-                RequestCancelPayload(requestId),
-            ),
-        ),
-    )
-
     suspend fun enqueuePlaybackErrorReport(payload: PlaybackErrorReportPayload): Long = dao.insert(
         CachedMutationEntity(
             kind = MutationKind.PLAYBACK_ERROR_REPORT,
             payload = json.encodeToString(PlaybackErrorReportPayload.serializer(), payload),
         ),
     )
+
+    /**
+     * Durable close-by-id for an already-open server play row. Background
+     * path only (no user hint) — same as [enqueuePlayOffline].
+     */
+    suspend fun enqueuePlayEnded(payload: PlayEndedPayload): Long = dao.insert(
+        CachedMutationEntity(
+            kind = MutationKind.PLAY_ENDED,
+            payload = json.encodeToString(PlayEndedPayload.serializer(), payload),
+        ),
+    )
+
+    private suspend fun insertUserDriven(kind: String, payload: String): Long {
+        val id = dao.insert(CachedMutationEntity(kind = kind, payload = payload))
+        _userEnqueueHints.tryEmit(QUEUED_MESSAGE)
+        return id
+    }
 }
 
+/**
+ * Persisted payload for `MutationKind.SUGGESTION_SNOOZE_TOGGLE` (#2374).
+ * `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
+ * extends the window, and un-snoozing something already back is a 404 the
+ * replayer treats as permanent (nothing left to do).
+ */
+@Serializable
+data class SuggestionSnoozeTogglePayload(
+    val mbid: String,
+    val name: String,
+    val desiredSnoozed: Boolean,
+)
+
 /**
  * Persisted payload for `MutationKind.QUARANTINE_UNFLAG` — the
  * `DELETE /api/quarantine/{trackId}` call lost during a connectivity
@@ -201,6 +323,22 @@ data class PlayOfflinePayload(
     val atIso: String,
     val durationPlayedMs: Long,
     val source: String? = null,
+    // #1551: device class for context conditioning; null on payloads queued
+    // before this field existed (decodes to null → server stores NULL).
+    val deviceClass: String? = null,
+)
+
+/**
+ * Persisted payload for `MutationKind.PLAY_ENDED`. The replayer re-fires
+ * `POST /api/events` with type=play_ended, closing the already-open server
+ * row [playEventId] at [durationPlayedMs]. Server-side close-by-id is
+ * idempotent (re-ending updates the same row and skips a duplicate
+ * skip_events insert), so a lost-response retry can't duplicate history.
+ */
+@Serializable
+data class PlayEndedPayload(
+    val playEventId: String,
+    val durationPlayedMs: Long,
 )
 
 /**
@@ -228,3 +366,36 @@ data class PlaybackErrorReportPayload(
     val detail: String? = null,
     val clientId: String,
 )
+
+/** Persisted payload for `MutationKind.NOTIFICATION_READ` (M489). */
+@Serializable
+data class NotificationReadPayload(val id: String)
+
+/**
+ * Persisted payload for `MutationKind.NOTIFICATIONS_READ_ALL` (M489).
+ * `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` (M489): 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
+    }

android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationReplayer.kt

@@ -1,3 +1,5 @@
+@file:Suppress("TooManyFunctions") // one dispatcher per mutation kind + replay helpers
+
 package com.fabledsword.minstrel.cache.mutations
 
 import com.fabledsword.minstrel.api.endpoints.AppendTracksRequest
@@ -5,26 +7,39 @@ 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
 import com.fabledsword.minstrel.api.endpoints.QuarantineApi
 import com.fabledsword.minstrel.api.endpoints.RequestsApi
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
+import com.fabledsword.minstrel.models.wire.PlayEndedRequest
 import com.fabledsword.minstrel.models.wire.PlayOfflineRequest
+import com.fabledsword.minstrel.models.wire.SnoozeSuggestionBody
 import com.fabledsword.minstrel.auth.AuthStore
 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
+import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.datetime.Clock
+import kotlinx.serialization.SerializationException
 import kotlinx.serialization.json.Json
+import retrofit2.HttpException
 import retrofit2.Retrofit
 import retrofit2.create
 import javax.inject.Inject
@@ -34,25 +49,24 @@ import javax.inject.Singleton
  * Drains the offline MutationQueue. Reads pending rows in FIFO order,
  * re-fires each call against the raw Retrofit API (NOT the high-level
  * Repository, which would re-enqueue on failure → infinite loop), and
- * deletes the row on 2xx success.
+ * resolves each to an [Outcome]:
+ *  - SENT  — server accepted (2xx) → delete the row.
+ *  - DROP  — permanently un-sendable (4xx, unknown kind/variant, corrupt
+ *            payload) → delete the row so it can't wedge the queue forever.
+ *  - RETRY — transient (transport, 5xx, 408, 429) → leave queued, bump
+ *            attempts, retry on the next trigger.
  *
  * Triggered by:
- *   - app start (MinstrelApplication @Inject forces the singleton's
- *     init block to subscribe)
- *   - every time AuthStore.sessionCookie transitions to a non-null
- *     value (sign-in, app launch with persisted cookie)
+ *   - app start (MinstrelApplication @Inject forces the singleton's init)
+ *   - AuthStore.sessionCookie transitioning to non-null (sign-in / cold
+ *     start with a persisted cookie)
+ *   - NetworkStatusController recovering to Healthy (server reachable again
+ *     mid-session — covers offline→online without needing a cold start)
  *
- * Single in-flight via the `mutex` — back-to-back triggers collapse
- * into one drain pass. A proper connectivity-listener / WorkManager
- * job that re-tries on Wi-Fi-came-back is a follow-up; for MVP the
- * sign-in + app-open triggers cover the common offline → online
- * transition (operator unlocks phone, opens app).
- *
- * Failed rows stay in the queue with their `attempts` and
- * `lastAttemptAt` updated. They get another chance on the next
- * trigger; no exponential backoff or max-attempts yet — the rows are
- * small (low single-digit count for typical use) so retry-forever is
- * cheap.
+ * Single in-flight via the [mutex]; back-to-back triggers collapse into one
+ * drain pass. No exponential backoff / max-attempts: the rows are few for
+ * typical use, and permanent failures are now dropped rather than retried
+ * forever.
  */
 @Singleton
 class MutationReplayer @Inject constructor(
@@ -60,6 +74,7 @@ class MutationReplayer @Inject constructor(
     private val authStore: AuthStore,
     private val json: Json,
     @ApplicationScope private val scope: CoroutineScope,
+    networkStatus: NetworkStatusController,
     retrofit: Retrofit,
 ) {
     private val likesApi: LikesApi = retrofit.create()
@@ -69,9 +84,13 @@ 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()
 
+    private enum class Outcome { SENT, DROP, RETRY }
+
     init {
         scope.launch {
             authStore.sessionCookie
@@ -79,6 +98,16 @@ class MutationReplayer @Inject constructor(
                 .distinctUntilChanged()
                 .collect { drainSafe() }
         }
+        // Server-reachable-again: replay queued writes the moment the
+        // health signal recovers, so an offline→online transition mid-
+        // session doesn't wait for the next cold start / re-auth.
+        scope.launch {
+            networkStatus.state
+                .map { it == ServerHealth.Healthy }
+                .distinctUntilChanged()
+                .filter { it }
+                .collect { drainSafe() }
+        }
     }
 
     /** Public entry-point; coalesces concurrent triggers via a Mutex. */
@@ -93,193 +122,284 @@ class MutationReplayer @Inject constructor(
 
     private suspend fun drain() {
         val rows = dao.getAll()
+        // Collapse superseded toggles (likes, suggestion snoozes): only the
+        // latest desired state per entity is replayed; older toggles for the
+        // same entity are dropped unsent. Without this, partial-failure +
+        // differential retry could replay an older toggle last and invert the
+        // final state — a snooze the user already undid would come back.
+        val superseded = supersededToggleIds(rows, json)
         for (row in rows) {
-            val sent = runCatching { dispatch(row) }.getOrDefault(false)
-            if (sent) {
+            if (row.id in superseded) {
                 dao.delete(row.id)
-            } else {
-                dao.recordAttempt(row.id, Clock.System.now())
+                continue
+            }
+            when (outcomeFor(row)) {
+                Outcome.SENT, Outcome.DROP -> dao.delete(row.id)
+                Outcome.RETRY -> dao.recordAttempt(row.id, Clock.System.now())
             }
         }
     }
 
+    private suspend fun outcomeFor(row: CachedMutationEntity): Outcome = try {
+        dispatch(row)
+    } catch (e: HttpException) {
+        if (isPermanent(e.code())) Outcome.DROP else Outcome.RETRY
+    } catch (@Suppress("SwallowedException") e: SerializationException) {
+        // Corrupt / schema-incompatible payload — permanent, drop it.
+        Outcome.DROP
+    } catch (@Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable) {
+        // Transport / unknown — leave queued for the next pass.
+        Outcome.RETRY
+    }
+
+    /** 4xx are permanent except the two "retry me" statuses. */
+    private fun isPermanent(code: Int): Boolean =
+        code in HTTP_CLIENT_ERR_MIN..HTTP_CLIENT_ERR_MAX &&
+            code != HTTP_TIMEOUT && code != HTTP_TOO_MANY
+
     /**
-     * Returns true if the server accepted the call, false on any
-     * failure (transport, server error, decode). The replayer treats
-     * false as "leave the row for next pass" — it doesn't try to
-     * distinguish permanent rejections from transient ones; a row
-     * that consistently fails will accumulate attempt count and
-     * lastAttemptAt for diagnostics.
+     * 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.
      */
-    private suspend fun dispatch(row: CachedMutationEntity): Boolean = when (row.kind) {
+    private suspend fun dispatch(row: CachedMutationEntity): Outcome = when (row.kind) {
         MutationKind.LIKE_TOGGLE -> dispatchLikeToggle(row.payload)
         MutationKind.REQUEST_CREATE -> dispatchRequestCreate(row.payload)
         MutationKind.QUARANTINE_UNFLAG -> dispatchQuarantineUnflag(row.payload)
         MutationKind.PLAYLIST_APPEND -> dispatchPlaylistAppend(row.payload)
         MutationKind.QUARANTINE_FLAG -> dispatchQuarantineFlag(row.payload)
         MutationKind.PLAY_OFFLINE -> dispatchPlayOffline(row.payload)
+        MutationKind.PLAY_ENDED -> dispatchPlayEnded(row.payload)
         MutationKind.REQUEST_CANCEL -> dispatchRequestCancel(row.payload)
         MutationKind.PLAYBACK_ERROR_REPORT -> dispatchPlaybackErrorReport(row.payload)
-        else -> {
-            // Unknown kind — drop the row by claiming success so a
-            // stale schema entry can't wedge the queue forever.
-            true
-        }
+        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
     }
 
-    private suspend fun dispatchLikeToggle(payload: String): Boolean {
+    /** The notifications inbox's kinds (M489), 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) {
             LikesRepository.ENTITY_ARTIST -> "artists"
             LikesRepository.ENTITY_ALBUM -> "albums"
             LikesRepository.ENTITY_TRACK -> "tracks"
-            else -> return true  // unknown variant — drop.
+            else -> return Outcome.DROP
         }
-        return try {
-            if (decoded.desiredState) {
-                likesApi.like(kindPath, decoded.entityId)
-            } else {
-                likesApi.unlike(kindPath, decoded.entityId)
-            }
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: the row stays in the queue with
-            // attempts + lastAttemptAt incremented; next drain pass
-            // retries. Per-attempt diagnostic logging lands when we
-            // wire up Timber at the replayer level.
-            false
+        if (decoded.desiredState) {
+            likesApi.like(kindPath, decoded.entityId)
+        } else {
+            likesApi.unlike(kindPath, decoded.entityId)
         }
+        return Outcome.SENT
     }
 
-    private suspend fun dispatchRequestCreate(payload: String): Boolean {
+    private suspend fun dispatchRequestCreate(payload: String): Outcome {
         val decoded = json.decodeFromString(RequestCreatePayload.serializer(), payload)
-        val body = CreateRequestBody(
-            kind = decoded.kind,
-            artistMbid = decoded.artistMbid,
-            artistName = decoded.artistName,
-            albumMbid = decoded.albumMbid,
-            albumTitle = decoded.albumTitle,
-            trackMbid = decoded.trackMbid,
-            trackTitle = decoded.trackTitle,
+        discoverApi.createRequest(
+            CreateRequestBody(
+                kind = decoded.kind,
+                artistMbid = decoded.artistMbid,
+                artistName = decoded.artistName,
+                albumMbid = decoded.albumMbid,
+                albumTitle = decoded.albumTitle,
+                trackMbid = decoded.trackMbid,
+                trackTitle = decoded.trackTitle,
+            ),
         )
-        return try {
-            discoverApi.createRequest(body)
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: the row stays in the queue with
-            // attempts + lastAttemptAt incremented; next drain pass
-            // retries. Per-attempt diagnostic logging lands when we
-            // wire up Timber at the replayer level.
-            false
-        }
+        return Outcome.SENT
     }
 
-    private suspend fun dispatchQuarantineUnflag(payload: String): Boolean {
+    private suspend fun dispatchQuarantineUnflag(payload: String): Outcome {
         val decoded = json.decodeFromString(QuarantineUnflagPayload.serializer(), payload)
-        return try {
-            quarantineApi.unflag(decoded.trackId)
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: the row stays in the queue with
-            // attempts + lastAttemptAt incremented; next drain pass
-            // retries. Per-attempt diagnostic logging lands when we
-            // wire up Timber at the replayer level.
-            false
-        }
+        quarantineApi.unflag(decoded.trackId)
+        return Outcome.SENT
     }
 
-    private suspend fun dispatchPlaylistAppend(payload: String): Boolean {
+    private suspend fun dispatchPlaylistAppend(payload: String): Outcome {
         val decoded = json.decodeFromString(PlaylistAppendPayload.serializer(), payload)
-        return try {
-            playlistsApi.appendTracks(
-                playlistId = decoded.playlistId,
-                body = AppendTracksRequest(trackIds = decoded.trackIds),
-            )
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
-        }
+        playlistsApi.appendTracks(
+            playlistId = decoded.playlistId,
+            body = AppendTracksRequest(trackIds = decoded.trackIds),
+        )
+        return Outcome.SENT
     }
 
-    private suspend fun dispatchQuarantineFlag(payload: String): Boolean {
+    private suspend fun dispatchQuarantineFlag(payload: String): Outcome {
         val decoded = json.decodeFromString(QuarantineFlagPayload.serializer(), payload)
-        return try {
-            quarantineApi.flag(
-                FlagRequest(
-                    trackId = decoded.trackId,
-                    reason = decoded.reason,
-                    notes = decoded.notes,
-                ),
-            )
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
-        }
+        quarantineApi.flag(
+            FlagRequest(
+                trackId = decoded.trackId,
+                reason = decoded.reason,
+                notes = decoded.notes,
+            ),
+        )
+        return Outcome.SENT
     }
 
-    private suspend fun dispatchPlayOffline(payload: String): Boolean {
+    private suspend fun dispatchPlayOffline(payload: String): Outcome {
         val decoded = json.decodeFromString(PlayOfflinePayload.serializer(), payload)
-        return try {
-            eventsApi.playOffline(
-                PlayOfflineRequest(
-                    trackId = decoded.trackId,
-                    clientId = decoded.clientId,
-                    at = decoded.atIso,
-                    durationPlayedMs = decoded.durationPlayedMs,
-                    source = decoded.source,
-                ),
-            )
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
-        }
+        eventsApi.playOffline(
+            PlayOfflineRequest(
+                trackId = decoded.trackId,
+                clientId = decoded.clientId,
+                at = decoded.atIso,
+                durationPlayedMs = decoded.durationPlayedMs,
+                source = decoded.source,
+                deviceClass = decoded.deviceClass,
+            ),
+        )
+        return Outcome.SENT
     }
 
-    private suspend fun dispatchRequestCancel(payload: String): Boolean {
+    private suspend fun dispatchPlayEnded(payload: String): Outcome {
+        val decoded = json.decodeFromString(PlayEndedPayload.serializer(), payload)
+        eventsApi.playEnded(
+            PlayEndedRequest(
+                playEventId = decoded.playEventId,
+                durationPlayedMs = decoded.durationPlayedMs,
+            ),
+        )
+        return Outcome.SENT
+    }
+
+    private suspend fun dispatchRequestCancel(payload: String): Outcome {
         val decoded = json.decodeFromString(RequestCancelPayload.serializer(), payload)
-        return try {
-            requestsApi.cancel(decoded.requestId)
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
-        }
+        requestsApi.cancel(decoded.requestId)
+        return Outcome.SENT
     }
 
-    private suspend fun dispatchPlaybackErrorReport(payload: String): Boolean {
-        val decoded = json.decodeFromString(PlaybackErrorReportPayload.serializer(), payload)
-        return try {
-            playbackErrorsApi.report(
-                PlaybackErrorReportRequest(
-                    trackId = decoded.trackId,
-                    kind = decoded.kind,
-                    detail = decoded.detail,
-                    clientId = decoded.clientId,
-                ),
-            )
-            true
-        } catch (
-            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-        ) {
-            // Intentional swallow: row stays queued; next drain pass retries.
-            false
+    /**
+     * Replays a suggestion snooze in whichever direction the payload asks for.
+     *
+     * The un-snooze branch can legitimately 404 (the row already lapsed, or a
+     * previous attempt landed and the response was lost). [outcomeFor] classes
+     * 404 as permanent → DROP, which is right: the user's intended end state
+     * already holds, so there is nothing left to send.
+     */
+    private suspend fun dispatchSuggestionSnoozeToggle(payload: String): Outcome {
+        val decoded = json.decodeFromString(SuggestionSnoozeTogglePayload.serializer(), payload)
+        if (decoded.desiredSnoozed) {
+            discoverApi.snoozeSuggestion(decoded.mbid, SnoozeSuggestionBody(name = decoded.name))
+        } else {
+            discoverApi.unsnoozeSuggestion(decoded.mbid)
         }
+        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(
+            PlaybackErrorReportRequest(
+                trackId = decoded.trackId,
+                kind = decoded.kind,
+                detail = decoded.detail,
+                clientId = decoded.clientId,
+            ),
+        )
+        return Outcome.SENT
+    }
+
+    private companion object {
+        const val HTTP_CLIENT_ERR_MIN = 400
+        const val HTTP_CLIENT_ERR_MAX = 499
+        const val HTTP_TIMEOUT = 408
+        const val HTTP_TOO_MANY = 429
     }
 }
+
+/**
+ * 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, suggestion snoozes (#2374) and the
+ * normalization preference (#4998) — 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
+ * instance. [rows] must be ascending by id (FIFO), which is what
+ * `CachedMutationDao.getAll()` returns.
+ */
+internal fun supersededToggleIds(rows: List<CachedMutationEntity>, json: Json): Set<Long> {
+    val latestByEntity = HashMap<String, Long>()
+    val superseded = HashSet<Long>()
+    rows.asSequence()
+        .mapNotNull { row -> toggleKeyOf(row, json)?.let { key -> key to row.id } }
+        .forEach { (key, id) ->
+            // Ascending ids mean a prior entry for this key is always older.
+            latestByEntity.put(key, id)?.let(superseded::add)
+        }
+    return superseded
+}
+
+/**
+ * Collapse key for a toggle row, or null when the row isn't a toggle — or its
+ * payload won't decode. Undecodable rows are deliberately left alone rather
+ * than grouped under a shared "corrupt" key, so one bad row can't suppress a
+ * good one behind it; the dispatcher DROPs it on its own.
+ *
+ * The kind is part of the key so two toggle kinds can never collide on the
+ * same entity id.
+ */
+private fun toggleKeyOf(row: CachedMutationEntity, json: Json): String? = when (row.kind) {
+    MutationKind.LIKE_TOGGLE -> runCatching {
+        json.decodeFromString(LikeTogglePayload.serializer(), row.payload)
+    }.getOrNull()?.let { "${row.kind}:${it.entityType}:${it.entityId}" }
+
+    MutationKind.SUGGESTION_SNOOZE_TOGGLE -> runCatching {
+        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
+}

android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/OfflineWriteHintViewModel.kt

@@ -0,0 +1,20 @@
+package com.fabledsword.minstrel.cache.mutations
+
+import androidx.lifecycle.ViewModel
+import dagger.hilt.android.lifecycle.HiltViewModel
+import kotlinx.coroutines.flow.Flow
+import javax.inject.Inject
+
+/**
+ * Hilt-injectable wrapper exposing [MutationQueue.userEnqueueHints] to
+ * ShellScaffold. The queue itself is an app-scoped singleton; this VM
+ * just bridges its SharedFlow into a `hiltViewModel()`-resolvable
+ * surface so ShellScaffold can collect it without an EntryPoint
+ * accessor. Mirrors PlaybackErrorViewModel.
+ */
+@HiltViewModel
+class OfflineWriteHintViewModel @Inject constructor(
+    mutationQueue: MutationQueue,
+) : ViewModel() {
+    val messages: Flow<String> = mutationQueue.userEnqueueHints
+}

android/app/src/main/java/com/fabledsword/minstrel/cache/sync/SyncController.kt

@@ -1,7 +1,10 @@
 package com.fabledsword.minstrel.cache.sync
 
+import com.fabledsword.minstrel.api.ErrorCopy
 import com.fabledsword.minstrel.api.endpoints.SyncApi
 import com.fabledsword.minstrel.auth.AuthStore
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
 import com.fabledsword.minstrel.cache.db.dao.CachedAlbumDao
 import com.fabledsword.minstrel.cache.db.dao.CachedArtistDao
 import com.fabledsword.minstrel.cache.db.dao.CachedTrackDao
@@ -15,9 +18,15 @@ import com.fabledsword.minstrel.models.wire.SyncAlbumWire
 import com.fabledsword.minstrel.models.wire.SyncArtistWire
 import com.fabledsword.minstrel.models.wire.SyncTrackWire
 import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Mutex
 import kotlinx.datetime.Clock
 import retrofit2.Retrofit
 import retrofit2.create
@@ -50,10 +59,26 @@ class SyncController @Inject constructor(
     private val trackDao: CachedTrackDao,
     private val authStore: AuthStore,
     @ApplicationScope private val scope: CoroutineScope,
+    networkStatus: NetworkStatusController,
     retrofit: Retrofit,
 ) {
     private val api: SyncApi = retrofit.create()
 
+    // Single in-flight guard: the cookie + health-recovery triggers (and a
+    // pull-to-refresh) can fire concurrently; coalesce them into one pass.
+    private val mutex = Mutex()
+
+    private val lastSyncErrorInternal = MutableStateFlow<String?>(null)
+
+    /**
+     * Human copy for the most recent sync failure; null after any clean
+     * pass. Lets the Library screen distinguish "empty because the first
+     * sync failed" (show error + retry) from "genuinely empty library"
+     * (show welcome copy) — a failed sync over a populated cache stays
+     * silent, since the cached content is still the better surface.
+     */
+    val lastSyncError: StateFlow<String?> = lastSyncErrorInternal.asStateFlow()
+
     init {
         scope.launch {
             authStore.sessionCookie
@@ -61,11 +86,27 @@ class SyncController @Inject constructor(
                 .distinctUntilChanged()
                 .collect { syncSafe() }
         }
+        // Re-sync when the server becomes reachable again mid-session, so a
+        // delta missed while offline lands without waiting for a cold start.
+        scope.launch {
+            networkStatus.state
+                .map { it == ServerHealth.Healthy }
+                .distinctUntilChanged()
+                .filter { it }
+                .collect { syncSafe() }
+        }
     }
 
-    /** Public entry-point for "Sync now" affordances. Swallows errors. */
+    /** Public entry-point for "Sync now" affordances. Swallows errors into [lastSyncError]. */
     suspend fun syncSafe() {
-        runCatching { sync() }
+        if (!mutex.tryLock()) return
+        try {
+            runCatching { sync() }
+                .onSuccess { lastSyncErrorInternal.value = null }
+                .onFailure { lastSyncErrorInternal.value = ErrorCopy.fromThrowable(it) }
+        } finally {
+            mutex.unlock()
+        }
     }
 
     private suspend fun sync() {
@@ -165,6 +206,8 @@ private fun SyncAlbumWire.toEntity(): CachedAlbumEntity = CachedAlbumEntity(
     releaseDate = releaseDate,
     coverPath = coverArtPath,
     mbid = mbid,
+    albumGain = albumGain,
+    albumPeak = albumPeak,
 )
 
 private fun SyncTrackWire.toEntity(): CachedTrackEntity = CachedTrackEntity(
@@ -178,4 +221,7 @@ private fun SyncTrackWire.toEntity(): CachedTrackEntity = CachedTrackEntity(
     filePath = filePath,
     fileFormat = fileFormat,
     genre = genre,
+    missing = missing,
+    trackGain = trackGain,
+    trackPeak = trackPeak,
 )

android/app/src/main/java/com/fabledsword/minstrel/connectivity/ConnectivityObserver.kt

@@ -14,11 +14,23 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Single source of truth for the device's "is the internet usable
- * right now" signal — wraps [ConnectivityManager] and exposes a hot
- * cold-startable Flow that emits `false` while the active network
- * lacks INTERNET + VALIDATED capabilities (airplane mode, no carrier,
- * captive portal, etc.) and `true` once a usable network appears.
+ * Single source of truth for "does the device have a network link at
+ * all" — wraps [ConnectivityManager] and exposes a hot cold-startable
+ * Flow that emits `false` only when there is no active INTERNET-capable
+ * network (airplane mode, no carrier/Wi-Fi) and `true` once any network
+ * link appears.
+ *
+ * Deliberately does NOT require `NET_CAPABILITY_VALIDATED`. VALIDATED
+ * tracks whether Android reached its own WAN internet-validation probe
+ * (Google's `generate_204`) — which is the wrong question for a
+ * self-hosted server that is usually on the LAN. A transient WAN/DNS
+ * blip (or Android's periodic re-validation) momentarily drops VALIDATED
+ * while the Minstrel box stays perfectly reachable; gating on it flipped
+ * the app to Offline with no debounce and fast-failed in-flight playback
+ * via [com.fabledsword.minstrel.player.OfflineGatedDataSource]. The
+ * authority on whether *Minstrel* is reachable is the `/healthz` poll
+ * ([com.fabledsword.minstrel.connectivity.NetworkStatusController], which
+ * has its own failure hysteresis), not this coarse device-link signal.
  *
  * Used by the shell-level ConnectionErrorBanner; downstream
  * repositories can also collect this to gate retry loops.
@@ -35,36 +47,36 @@ class ConnectivityObserver @Inject constructor(
             .build()
         val callback = object : ConnectivityManager.NetworkCallback() {
             override fun onAvailable(network: Network) {
-                trySend(hasUsableInternet())
+                trySend(hasActiveNetwork())
             }
             override fun onLost(network: Network) {
-                trySend(hasUsableInternet())
+                trySend(hasActiveNetwork())
             }
             override fun onCapabilitiesChanged(
                 network: Network,
                 capabilities: NetworkCapabilities,
             ) {
+                // INTERNET only -- NOT VALIDATED. A WAN/validation flicker
+                // must not read as "device offline" when the LAN (and the
+                // Minstrel server on it) is still reachable. /healthz is the
+                // authority on server reachability.
                 trySend(
                     capabilities.hasCapability(
                         NetworkCapabilities.NET_CAPABILITY_INTERNET,
-                    ) &&
-                        capabilities.hasCapability(
-                            NetworkCapabilities.NET_CAPABILITY_VALIDATED,
-                        ),
+                    ),
                 )
             }
         }
         cm.registerNetworkCallback(request, callback)
         // Seed the initial value so the banner doesn't flash before the
         // first capability callback fires.
-        trySend(hasUsableInternet())
+        trySend(hasActiveNetwork())
         awaitClose { cm.unregisterNetworkCallback(callback) }
     }.distinctUntilChanged()
 
-    private fun hasUsableInternet(): Boolean {
+    private fun hasActiveNetwork(): Boolean {
         val caps = cm.activeNetwork?.let { cm.getNetworkCapabilities(it) }
         return caps != null &&
-            caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) &&
-            caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)
+            caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
     }
 }

android/app/src/main/java/com/fabledsword/minstrel/connectivity/NetworkStatusController.kt

@@ -0,0 +1,200 @@
+package com.fabledsword.minstrel.connectivity
+
+import androidx.compose.runtime.staticCompositionLocalOf
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.ProcessLifecycleOwner
+import com.fabledsword.minstrel.BuildConfig
+import com.fabledsword.minstrel.auth.AuthStore
+import com.fabledsword.minstrel.di.ApplicationScope
+import com.fabledsword.minstrel.update.api.HealthzApi
+import com.fabledsword.minstrel.update.api.HealthzResponse
+import com.fabledsword.minstrel.update.data.VersionResult
+import com.fabledsword.minstrel.update.data.isVersionNewer
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import retrofit2.Retrofit
+import timber.log.Timber
+import java.util.concurrent.atomic.AtomicLong
+import javax.inject.Inject
+import javax.inject.Singleton
+
+private const val POLL_HEALTHY_MS = 5 * 60 * 1000L
+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
+ * VersionCheckController (the /healthz poll + version parsing) and
+ * ServerHealthController (the tri-state derive) into one signal-driven unit so
+ * the app has one place that answers "can we reach Minstrel?" — not three
+ * 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).
+ *  - 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
+ *    it a stale ServerDown outlived the condition that caused it: the poll
+ *    loop's delay() is throttled while screen-off/doze, so recovery waited on
+ *    whenever the OS next let the loop run. Meanwhile ServerDown makes
+ *    OfflineGatedDataSource refuse every uncached track, so the app declined
+ *    to play music that would have played fine.
+ *
+ * Version compatibility is a byproduct of the same /healthz response.
+ *
+ * Constructed at launch via the construct-the-singleton trick in
+ * [com.fabledsword.minstrel.MinstrelApplication].
+ */
+@Singleton
+class NetworkStatusController @Inject constructor(
+    @ApplicationScope private val scope: CoroutineScope,
+    connectivity: ConnectivityObserver,
+    private val authStore: AuthStore,
+    retrofit: Retrofit,
+) : DefaultLifecycleObserver {
+    private val api: HealthzApi = retrofit.create(HealthzApi::class.java)
+    private val machine = ReachabilityMachine()
+    private val lastProbeAtMs = AtomicLong(0)
+
+    private val stateInternal = MutableStateFlow(ServerHealth.Healthy)
+    val state: StateFlow<ServerHealth> = stateInternal.asStateFlow()
+
+    private val versionInternal = MutableStateFlow(VersionResult.SKIPPED)
+    val versionResult: StateFlow<VersionResult> = versionInternal.asStateFlow()
+
+    private sealed interface Intent {
+        data class Link(val up: Boolean) : Intent
+        data class Probe(val resp: HealthzResponse?) : Intent
+        object OpSuccess : Intent
+        object OpFailure : Intent
+    }
+
+    private val intents = Channel<Intent>(Channel.UNLIMITED)
+
+    init {
+        ProcessLifecycleOwner.get().lifecycle.addObserver(this)
+        scope.launch { reduceLoop() }
+        scope.launch {
+            connectivity.online.collect { up ->
+                intents.trySend(Intent.Link(up))
+                if (up) probeOnce()
+            }
+        }
+        scope.launch { pollLoop() }
+    }
+
+    /** A real server op verifiably succeeded — self-proving recovery. Cheap; safe on hot paths. */
+    fun reportSuccess() {
+        if (stateInternal.value != ServerHealth.Healthy) intents.trySend(Intent.OpSuccess)
+    }
+
+    /** A real network op failed — triggers /healthz arbitration. No-op when already Offline. */
+    fun reportFailure() {
+        if (stateInternal.value == ServerHealth.Offline) return
+        intents.trySend(Intent.OpFailure)
+    }
+
+    /** One-shot recheck for pull-to-refresh and the banner. */
+    fun recheck() {
+        scope.launch { probeOnce(force = true) }
+    }
+
+    /**
+     * App returned to the foreground — probe now rather than waiting for the
+     * poll loop (#1209).
+     *
+     * 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.
+     * force = true so this also bypasses the ARBITRATE_MIN_GAP_MS throttle —
+     * a user bringing the app up is exactly when a stale banner and a refused
+     * track are most visible, and it's a once-per-foreground cost.
+     */
+    override fun onStart(owner: LifecycleOwner) {
+        recheck()
+    }
+
+    private suspend fun reduceLoop() {
+        for (intent in intents) {
+            val now = System.currentTimeMillis()
+            when (intent) {
+                is Intent.Link -> machine.onLinkChange(intent.up)
+                is Intent.Probe -> applyProbe(intent.resp, now)
+                Intent.OpSuccess -> machine.onSuccess()
+                Intent.OpFailure -> {
+                    machine.onOpFailure(now)
+                    // Arbitrate off the reducer thread: awaiting a stalled
+                    // /healthz here would block a concurrent self-proving
+                    // success from snapping us straight back to Healthy.
+                    scope.launch { probeOnce() }
+                }
+            }
+            emit(machine.health())
+        }
+    }
+
+    private fun applyProbe(resp: HealthzResponse?, now: Long) {
+        if (resp == null) {
+            machine.onProbeFailure(now)
+        } else {
+            machine.onSuccess()
+            versionInternal.value = versionResultFor(resp)
+        }
+    }
+
+    private fun emit(next: ServerHealth) {
+        if (stateInternal.value != next) {
+            Timber.w("NetworkStatus -> %s", next)
+            stateInternal.value = next
+        }
+    }
+
+    private suspend fun pollLoop() {
+        probeOnce()
+        while (true) {
+            val interval =
+                if (stateInternal.value == ServerHealth.Healthy) POLL_HEALTHY_MS
+                else POLL_DEGRADED_MS
+            delay(interval)
+            probeOnce()
+        }
+    }
+
+    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.
+        if (authStore.baseUrl.value == AuthStore.DEFAULT_BASE_URL) return
+        val now = System.currentTimeMillis()
+        if (!force && now - lastProbeAtMs.get() < ARBITRATE_MIN_GAP_MS) return
+        lastProbeAtMs.set(now)
+        val resp = runCatching { api.check() }.getOrNull()
+        intents.trySend(Intent.Probe(resp))
+    }
+
+    private fun versionResultFor(resp: HealthzResponse): VersionResult {
+        val min = resp.minClientVersion
+        return when {
+            min.isEmpty() -> VersionResult.SKIPPED
+            isVersionNewer(min, BuildConfig.VERSION_NAME) -> VersionResult.TOO_OLD
+            else -> VersionResult.OK
+        }
+    }
+}
+
+/**
+ * Reactive [ServerHealth] snapshot provided once at the app root. Lets leaf
+ * composables (TrackRow gating, write-affordance disabling) branch on health
+ * without re-injecting the controller. Defaults to Healthy so previews/tests
+ * don't crash.
+ */
+val LocalServerHealth = staticCompositionLocalOf { ServerHealth.Healthy }

android/app/src/main/java/com/fabledsword/minstrel/connectivity/ReachabilityMachine.kt

@@ -0,0 +1,114 @@
+package com.fabledsword.minstrel.connectivity
+
+internal const val ESCALATE_AFTER_MS = 120_000L
+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
+ * (#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
+ * straight to Unreachable, and ServerDown makes OfflineGatedDataSource refuse
+ * every uncached track. The app declined to play music that would have played
+ * 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
+ * retries. The sustained-time backstop covers the case where nothing retries
+ * at all — and if nothing is asking, a late ServerDown costs nothing.
+ */
+internal const val CORROBORATION_MIN_SPACING_MS = 3_000L
+
+/**
+ * Pure reachability state machine. No Android, no coroutines, no real clock —
+ * every entry point takes `nowMs`, so it is fully deterministic and unit-
+ * testable. [NetworkStatusController] wires real time + signals around it.
+ *
+ * Reachability (independent of the device link):
+ *  - Reachable   last evidence says the server answered.
+ *  - Unstable    a probe failed; arbitration/escalation pending.
+ *  - Unreachable corroborated or sustained failure.
+ *
+ * [health] folds the device link over that: no link → Offline; otherwise the
+ * reachability maps Reachable→Healthy, Unstable→Unstable, Unreachable→ServerDown.
+ *
+ * Principle: **success is self-proving, failure is ambiguous.** [onSuccess]
+ * (a real server byte-read or API 2xx, or a successful /healthz) snaps straight
+ * back to Reachable. A failure only escalates when a /healthz probe corroborates
+ * it ([onProbeFailure]) — either via fresh op-failure corroboration or the
+ * sustained-time backstop.
+ */
+class ReachabilityMachine {
+
+    private enum class Reachability { Reachable, Unstable, Unreachable }
+
+    private var linkUp = true
+    private var reachability = Reachability.Reachable
+    private var failureStreakStartMs: Long? = null
+    private val recentOpFailures = ArrayDeque<Long>()
+
+    fun onLinkChange(up: Boolean) {
+        linkUp = up
+        // Link transitions don't reset reachability — a restored link keeps the
+        // last-known server reachability until a fresh probe/op result arrives.
+        if (!up) recentOpFailures.clear()
+    }
+
+    /** A real successful server op (stream read, API 2xx) or a successful /healthz. */
+    fun onSuccess() {
+        reachability = Reachability.Reachable
+        failureStreakStartMs = null
+        recentOpFailures.clear()
+    }
+
+    /**
+     * A real network op failed. Ambiguous on its own — records corroboration.
+     *
+     * Failures arriving within [CORROBORATION_MIN_SPACING_MS] of the last
+     * recorded one are dropped rather than stacked: see that constant for why
+     * a burst must not corroborate itself.
+     */
+    fun onOpFailure(nowMs: Long) {
+        pruneOpFailures(nowMs)
+        val last = recentOpFailures.lastOrNull()
+        if (last != null && nowMs - last < CORROBORATION_MIN_SPACING_MS) return
+        recentOpFailures.addLast(nowMs)
+    }
+
+    /** A /healthz probe failed — the arbiter. Escalates per corroboration/backstop. */
+    fun onProbeFailure(nowMs: Long) {
+        pruneOpFailures(nowMs)
+        if (reachability == Reachability.Reachable) {
+            reachability = Reachability.Unstable
+            failureStreakStartMs = nowMs
+        }
+        if (reachability == Reachability.Unstable && shouldEscalate(nowMs)) {
+            reachability = Reachability.Unreachable
+        }
+    }
+
+    fun health(): ServerHealth = when {
+        !linkUp -> ServerHealth.Offline
+        reachability == Reachability.Reachable -> ServerHealth.Healthy
+        reachability == Reachability.Unstable -> ServerHealth.Unstable
+        else -> ServerHealth.ServerDown
+    }
+
+    private fun shouldEscalate(nowMs: Long): Boolean {
+        val corroborated = recentOpFailures.size >= CORROBORATION_OP_THRESHOLD
+        val sustained =
+            failureStreakStartMs?.let { nowMs - it >= ESCALATE_AFTER_MS } ?: false
+        return corroborated || sustained
+    }
+
+    private fun pruneOpFailures(nowMs: Long) {
+        while (recentOpFailures.isNotEmpty() &&
+            nowMs - recentOpFailures.first() > CORROBORATION_WINDOW_MS
+        ) {
+            recentOpFailures.removeFirst()
+        }
+    }
+}

android/app/src/main/java/com/fabledsword/minstrel/connectivity/ReachabilityReportingInterceptor.kt

@@ -0,0 +1,49 @@
+package com.fabledsword.minstrel.connectivity
+
+import com.fabledsword.minstrel.api.BaseUrlInterceptor.Companion.PLACEHOLDER_HOST
+import dagger.Lazy
+import okhttp3.Interceptor
+import okhttp3.Response
+import java.io.IOException
+import javax.inject.Inject
+import javax.inject.Singleton
+
+private const val HEALTHZ_PATH = "/healthz"
+
+/**
+ * Feeds real Minstrel API outcomes into [NetworkStatusController]. A 2xx is
+ * self-proving proof the server is reachable → reportSuccess(); a transport
+ * [IOException] (no response at all) → reportFailure(), which triggers /healthz
+ * arbitration.
+ *
+ * MUST run first in the OkHttp chain (before [BaseUrlInterceptor]) so the host
+ * is still the [PLACEHOLDER_HOST] sentinel: this shared client also fetches
+ * EXTERNAL artwork (musicbrainz / coverartarchive), and an external image
+ * loading must NOT be read as "our server is reachable" — only sentinel-host
+ * requests are Minstrel-bound. 5xx is deliberately NOT a failure (the server
+ * answered), and /healthz is skipped to avoid a feedback loop with the poll.
+ *
+ * [NetworkStatusController] is injected as a [Lazy] to break the Hilt cycle:
+ * the controller needs `Retrofit`, which needs `OkHttpClient`, which needs this
+ * interceptor. By the time a request flows through, the controller singleton is
+ * already constructed (construct-the-singleton trick in MinstrelApplication).
+ */
+@Singleton
+class ReachabilityReportingInterceptor @Inject constructor(
+    private val networkStatus: Lazy<NetworkStatusController>,
+) : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request()
+        val isMinstrel = request.url.host == PLACEHOLDER_HOST
+        val isHealthz = request.url.encodedPath.endsWith(HEALTHZ_PATH)
+        if (!isMinstrel || isHealthz) return chain.proceed(request)
+        return try {
+            val response = chain.proceed(request)
+            if (response.isSuccessful) networkStatus.get().reportSuccess()
+            response
+        } catch (e: IOException) {
+            networkStatus.get().reportFailure()
+            throw e
+        }
+    }
+}

android/app/src/main/java/com/fabledsword/minstrel/connectivity/Recovery.kt

@@ -0,0 +1,27 @@
+package com.fabledsword.minstrel.connectivity
+
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.drop
+import kotlinx.coroutines.flow.filter
+import kotlinx.coroutines.flow.map
+
+/**
+ * Emits once each time server health RETURNS to [ServerHealth.Healthy]
+ * after the collector subscribed — the StateFlow's replayed current value
+ * is dropped, so only genuine down→up transitions fire (a screen that
+ * subscribes while already Healthy doesn't double-load).
+ *
+ * This is the screen-level half of the recovery idiom the app-lifetime
+ * singletons (SyncController / MutationReplayer / DiagnosticsUploader)
+ * already use: a ViewModel collects this in its viewModelScope and re-runs
+ * its load, so a surface that failed while the server was unreachable
+ * heals itself the moment connectivity returns instead of sitting in the
+ * failed state until a manual pull-to-refresh.
+ */
+fun NetworkStatusController.recoveries(): Flow<Unit> = state
+    .map { it == ServerHealth.Healthy }
+    .distinctUntilChanged()
+    .drop(1)
+    .filter { it }
+    .map { }

android/app/src/main/java/com/fabledsword/minstrel/connectivity/ServerHealth.kt

@@ -0,0 +1,15 @@
+package com.fabledsword.minstrel.connectivity
+
+/**
+ * The single reachability signal every consumer branches on.
+ *
+ *  - [Healthy]    link up, /healthz ok — normal network behavior.
+ *  - [Unstable]   link up, a recent failure with arbitration pending —
+ *                 INFORMATIONAL ONLY. Does NOT gate playback; preserves the
+ *                 anti-flicker intent of commit 5c0db429 while still warning
+ *                 the user that something is flaky.
+ *  - [ServerDown] link up but /healthz failing, corroborated or sustained —
+ *                 gate to cache-only.
+ *  - [Offline]    no device link at all — gate to cache-only.
+ */
+enum class ServerHealth { Healthy, Unstable, ServerDown, Offline }

android/app/src/main/java/com/fabledsword/minstrel/connectivity/ui/ConnectionErrorBanner.kt

@@ -14,77 +14,121 @@ import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.unit.dp
 import androidx.hilt.navigation.compose.hiltViewModel
 import androidx.lifecycle.SavedStateHandle
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
-import androidx.lifecycle.viewModelScope
 import com.composables.icons.lucide.CloudOff
 import com.composables.icons.lucide.Lucide
-import com.fabledsword.minstrel.connectivity.ConnectivityObserver
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
 import dagger.hilt.android.lifecycle.HiltViewModel
-import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.StateFlow
-import kotlinx.coroutines.flow.stateIn
 import javax.inject.Inject
 
-private const val ONLINE_SHARE_STOP_TIMEOUT_MS = 5_000L
+private const val BACK_ONLINE_FLASH_MS = 2_000L
 
 /**
- * Tiny VM that just lifts the [ConnectivityObserver] singleton's
- * Flow into a StateFlow with the standard sharing strategy. Keeps
- * the banner composable pure-presentation.
+ * Exposes [NetworkStatusController]'s tri-state directly to the banner. No
+ * re-wrapping StateFlow — the controller's is already app-scoped and warm.
  */
 @HiltViewModel
 class ConnectivityBannerViewModel @Inject constructor(
-    observer: ConnectivityObserver,
+    networkStatus: NetworkStatusController,
     @Suppress("UnusedPrivateProperty") savedStateHandle: SavedStateHandle,
 ) : ViewModel() {
-    val online: StateFlow<Boolean> = observer.online.stateIn(
-        scope = viewModelScope,
-        started = SharingStarted.WhileSubscribed(ONLINE_SHARE_STOP_TIMEOUT_MS),
-        initialValue = true,
-    )
+    val health: StateFlow<ServerHealth> = networkStatus.state
 }
 
 /**
- * Banner shown at the top of the shell when the device has no usable
- * internet. Mirrors Flutter's ConnectionErrorBanner: red-tinted error
- * surface, CloudOff icon, "No connection — check Wi-Fi or mobile
- * data" copy. Auto-hides via slide+fade when connectivity returns.
+ * Shell banner. Tells the user *why* they're degraded — no link vs server-down
+ * — plus a non-alarming "Reconnecting…" for the transient [ServerHealth.Unstable]
+ * window, and a brief "Back online" confirmation when health recovers so
+ * recovery is unmistakable. Sentence case, understated voice (design system).
  */
 @Composable
 fun ConnectionErrorBanner(
     viewModel: ConnectivityBannerViewModel = hiltViewModel(),
 ) {
-    val online by viewModel.online.collectAsStateWithLifecycle()
+    val health by viewModel.health.collectAsStateWithLifecycle()
+    var showBackOnline by remember { mutableStateOf(false) }
+    var wasDown by remember { mutableStateOf(false) }
+
+    LaunchedEffect(health) {
+        val down = health == ServerHealth.Offline || health == ServerHealth.ServerDown
+        if (health == ServerHealth.Healthy && wasDown) {
+            // try/finally so a mid-delay cancellation (health flips again) can't
+            // orphan the flag and leave "Back online" stuck on screen.
+            try {
+                showBackOnline = true
+                delay(BACK_ONLINE_FLASH_MS)
+            } finally {
+                showBackOnline = false
+            }
+        }
+        wasDown = down
+    }
+
     AnimatedVisibility(
-        visible = !online,
+        visible = health != ServerHealth.Healthy || showBackOnline,
         enter = expandVertically() + fadeIn(),
         exit = shrinkVertically() + fadeOut(),
     ) {
-        Row(
-            modifier = Modifier
-                .fillMaxWidth()
-                .background(MaterialTheme.colorScheme.errorContainer)
-                .padding(horizontal = 16.dp, vertical = 10.dp),
-            verticalAlignment = Alignment.CenterVertically,
-            horizontalArrangement = Arrangement.spacedBy(12.dp),
-        ) {
-            Icon(
-                imageVector = Lucide.CloudOff,
-                contentDescription = null,
-                tint = MaterialTheme.colorScheme.onErrorContainer,
-            )
-            Text(
-                text = "No connection — check Wi-Fi or mobile data.",
-                style = MaterialTheme.typography.bodyMedium,
-                color = MaterialTheme.colorScheme.onErrorContainer,
-            )
-        }
+        BannerContent(health = health, backOnline = showBackOnline)
     }
 }
+
+@Composable
+private fun BannerContent(health: ServerHealth, backOnline: Boolean) {
+    val scheme = MaterialTheme.colorScheme
+    val background: Color
+    val foreground: Color
+    when {
+        backOnline -> {
+            background = scheme.secondaryContainer
+            foreground = scheme.onSecondaryContainer
+        }
+        health == ServerHealth.Unstable -> {
+            background = scheme.surfaceVariant
+            foreground = scheme.onSurfaceVariant
+        }
+        else -> {
+            background = scheme.errorContainer
+            foreground = scheme.onErrorContainer
+        }
+    }
+    Row(
+        modifier = Modifier
+            .fillMaxWidth()
+            .background(background)
+            .padding(horizontal = 16.dp, vertical = 10.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.spacedBy(12.dp),
+    ) {
+        Icon(imageVector = Lucide.CloudOff, contentDescription = null, tint = foreground)
+        Text(
+            text = bannerText(health, backOnline),
+            style = MaterialTheme.typography.bodyMedium,
+            color = foreground,
+        )
+    }
+}
+
+private fun bannerText(health: ServerHealth, backOnline: Boolean): String = when {
+    backOnline -> "Back online."
+    health == ServerHealth.Offline -> "No connection — check Wi-Fi or mobile data."
+    health == ServerHealth.ServerDown ->
+        "Server unreachable — your cached content is still available."
+    health == ServerHealth.Unstable -> "Reconnecting…"
+    else -> ""
+}