Merge PR #95: You-might-like liked-entity fallback (#790)

golangci-lint v2 (CI-only; local is v1) flagged the field-by-field struct
literals — the fallback and you-might-like row types are identical, so convert
directly instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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/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/java/com/fabledsword/minstrel/MainActivity.kt

@@ -23,7 +23,7 @@ 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.ServerHealthController
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.nav.DetailSeedCache
 import com.fabledsword.minstrel.nav.LocalDetailSeedCache
 import com.fabledsword.minstrel.nav.MinstrelNavGraph
@@ -41,7 +41,7 @@ import javax.inject.Inject
 class MainActivity : ComponentActivity() {
     @Inject lateinit var seedCache: DetailSeedCache
     @Inject lateinit var cachedTrackIds: CachedTrackIds
-    @Inject lateinit var serverHealth: ServerHealthController
+    @Inject lateinit var serverHealth: NetworkStatusController
 
     // Flipped to true when the user taps the media notification (or
     // any other entry point that asks for the full player). The App
@@ -91,7 +91,7 @@ class MainActivity : ComponentActivity() {
 private fun App(
     seedCache: DetailSeedCache,
     cachedTrackIds: CachedTrackIds,
-    serverHealth: ServerHealthController,
+    serverHealth: NetworkStatusController,
     pendingOpenNowPlaying: StateFlow<Boolean>,
     onOpenedNowPlaying: () -> Unit,
     themeVm: ThemePreferenceViewModel = hiltViewModel(),

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

@@ -19,8 +19,7 @@ import com.fabledsword.minstrel.player.PlayEventsReporter
 import com.fabledsword.minstrel.player.PlaybackErrorReporter
 import com.fabledsword.minstrel.player.ResumeController
 import com.fabledsword.minstrel.update.data.UpdateBannerController
-import com.fabledsword.minstrel.connectivity.ServerHealthController
-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
@@ -115,21 +114,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
-
-    /**
-     * Same construct-the-singleton trick — ServerHealthController combines
-     * ConnectivityObserver + VersionCheckController.reachable into the
-     * tri-state ServerHealth signal. Its stateIn is `SharingStarted.Eagerly`
-     * so the StateFlow needs an active subscriber from launch onward; the
-     * @Inject keeps the singleton alive and the flow collecting.
-     */
-    @Suppress("unused") @Inject lateinit var serverHealthController: ServerHealthController
+    @Suppress("unused") @Inject lateinit var networkStatusController: NetworkStatusController
 
     /**
      * Same construct-the-singleton trick — UpdateBannerController polls

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

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

@@ -2,6 +2,7 @@ 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.TrackWire
 import retrofit2.http.GET
 import retrofit2.http.Path
@@ -35,9 +36,26 @@ 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>
+
+    private companion object {
+        const val SIMILAR_ARTISTS_LIMIT = 12
+        const val TOP_TRACKS_LIMIT = 5
+    }
 }

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

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/CachedHomeIndexEntity.kt

@@ -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/mutations/MutationQueue.kt

@@ -28,6 +28,13 @@ 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"
 }
 
 /**
@@ -167,6 +174,17 @@ class MutationQueue @Inject constructor(
         ),
     )
 
+    /**
+     * 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)
@@ -223,6 +241,19 @@ data class PlayOfflinePayload(
     val source: 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,
+)
+
 /**
  * Persisted payload for `MutationKind.REQUEST_CANCEL` — the
  * `POST /api/requests/{id}/cancel` call lost during a connectivity

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
@@ -10,6 +12,9 @@ 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.auth.AuthStore
 import com.fabledsword.minstrel.cache.db.dao.CachedMutationDao
@@ -19,12 +24,16 @@ import com.fabledsword.minstrel.likes.data.LikesRepository
 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 +43,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 +68,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()
@@ -72,6 +81,8 @@ class MutationReplayer @Inject constructor(
 
     private val mutex = Mutex()
 
+    private enum class Outcome { SENT, DROP, RETRY }
+
     init {
         scope.launch {
             authStore.sessionCookie
@@ -79,6 +90,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 +114,185 @@ class MutationReplayer @Inject constructor(
 
     private suspend fun drain() {
         val rows = dao.getAll()
+        // Collapse superseded like-toggles: 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 like state.
+        val superseded = supersededLikeToggleIds(rows)
         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())
             }
         }
     }
 
+    /** Row ids of like-toggles superseded by a later toggle for the same entity. */
+    private fun supersededLikeToggleIds(rows: List<CachedMutationEntity>): Set<Long> {
+        val latestByEntity = HashMap<String, Long>()
+        val superseded = HashSet<Long>()
+        rows.asSequence()
+            .filter { it.kind == MutationKind.LIKE_TOGGLE }
+            .forEach { row ->
+                val decoded = runCatching {
+                    json.decodeFromString(LikeTogglePayload.serializer(), row.payload)
+                }.getOrNull()
+                if (decoded != null) {
+                    val key = "${decoded.entityType}:${decoded.entityId}"
+                    // `rows` is ascending by id, so a prior entry is always older.
+                    latestByEntity.put(key, row.id)?.let(superseded::add)
+                }
+            }
+        return superseded
+    }
+
+    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
-        }
+        // Unknown kind — drop so a stale schema entry can't wedge the queue.
+        else -> Outcome.DROP
     }
 
-    private suspend fun dispatchLikeToggle(payload: String): Boolean {
+    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,
+            ),
+        )
+        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 {
+    private suspend fun dispatchPlaybackErrorReport(payload: String): Outcome {
         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
-        }
+        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
     }
 }

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

@@ -2,6 +2,8 @@ package com.fabledsword.minstrel.cache.sync
 
 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
@@ -16,8 +18,11 @@ import com.fabledsword.minstrel.models.wire.SyncArtistWire
 import com.fabledsword.minstrel.models.wire.SyncTrackWire
 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.datetime.Clock
 import retrofit2.Retrofit
 import retrofit2.create
@@ -50,10 +55,15 @@ 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()
+
     init {
         scope.launch {
             authStore.sessionCookie
@@ -61,11 +71,25 @@ 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. */
     suspend fun syncSafe() {
-        runCatching { sync() }
+        if (!mutex.tryLock()) return
+        try {
+            runCatching { sync() }
+        } finally {
+            mutex.unlock()
+        }
     }
 
     private suspend fun sync() {

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

@@ -29,7 +29,7 @@ import javax.inject.Singleton
  * 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.update.data.VersionCheckController], which
+ * ([com.fabledsword.minstrel.connectivity.NetworkStatusController], which
  * has its own failure hysteresis), not this coarse device-link signal.
  *
  * Used by the shell-level ConnectionErrorBanner; downstream

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

@@ -0,0 +1,176 @@
+package com.fabledsword.minstrel.connectivity
+
+import androidx.compose.runtime.staticCompositionLocalOf
+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.
+ *
+ * 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,
+) {
+    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 {
+        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) }
+    }
+
+    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,88 @@
+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
+
+/**
+ * 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. */
+    fun onOpFailure(nowMs: Long) {
+        pruneOpFailures(nowMs)
+        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/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/ServerHealthController.kt

@@ -1,75 +0,0 @@
-package com.fabledsword.minstrel.connectivity
-
-import androidx.compose.runtime.staticCompositionLocalOf
-import com.fabledsword.minstrel.di.ApplicationScope
-import com.fabledsword.minstrel.update.data.VersionCheckController
-import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.flow.SharingStarted
-import kotlinx.coroutines.flow.StateFlow
-import kotlinx.coroutines.flow.combine
-import kotlinx.coroutines.flow.distinctUntilChanged
-import kotlinx.coroutines.flow.onEach
-import kotlinx.coroutines.flow.stateIn
-import timber.log.Timber
-import javax.inject.Inject
-import javax.inject.Singleton
-
-/**
- * Tri-state server-reachability signal that downstream consumers can branch
- * on to decide whether to hit the network, gate writes, or fall back to
- * cache-only behavior.
- *
- * Composed from two existing signals -- this controller doesn't poll its own
- * endpoint:
- *
- *  - [ConnectivityObserver.online] -- system-level NetworkCallback that
- *    answers only "is there an active INTERNET-capable network link" (NOT
- *    VALIDATED -- a WAN-validation flicker must not read as offline when
- *    the LAN server is reachable).
- *  - [VersionCheckController.reachable] -- did the last `/healthz` poll
- *    succeed. This is the authority on whether *Minstrel* is reachable;
- *    it has its own failure hysteresis. Distinguishes "device has a link
- *    but our server is down" from "no network at all."
- *
- * `version too old` is intentionally *not* folded in here -- it's a separate
- * UX (the VersionTooOldBanner) and conflating it with offline would mask the
- * real cause.
- */
-enum class ServerHealth { Healthy, Offline, ServerDown }
-
-@Singleton
-class ServerHealthController @Inject constructor(
-    @ApplicationScope scope: CoroutineScope,
-    connectivity: ConnectivityObserver,
-    versionCheck: VersionCheckController,
-) {
-    val state: StateFlow<ServerHealth> = combine(
-        connectivity.online,
-        versionCheck.reachable,
-    ) { online, serverReachable ->
-        when {
-            !online -> ServerHealth.Offline
-            !serverReachable -> ServerHealth.ServerDown
-            else -> ServerHealth.Healthy
-        }
-    }
-        // Transition log -- the signal had no instrumentation, which is why a
-        // false-offline (WAN flicker flipping playback to "Source error") was
-        // hard to diagnose from logcat. WARN-tier so ReleaseTree surfaces it.
-        .distinctUntilChanged()
-        .onEach { Timber.w("ServerHealth -> %s", it) }
-        .stateIn(
-            scope = scope,
-            started = SharingStarted.Eagerly,
-            initialValue = ServerHealth.Healthy,
-        )
-}
-
-/**
- * Reactive [ServerHealth] snapshot provided once at the app root from the
- * controller's StateFlow. Lets leaf composables (TrackRow gating, write-
- * affordance disabling) branch on health without each ViewModel re-
- * injecting the controller. Defaults to Healthy so unwrapped previews
- * and tests don't crash.
- */
-val LocalServerHealth = staticCompositionLocalOf { ServerHealth.Healthy }

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

@@ -14,83 +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.NetworkStatusController
 import com.fabledsword.minstrel.connectivity.ServerHealth
-import com.fabledsword.minstrel.connectivity.ServerHealthController
 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 HEALTH_SHARE_STOP_TIMEOUT_MS = 5_000L
+private const val BACK_ONLINE_FLASH_MS = 2_000L
 
 /**
- * Lifts [ServerHealthController]'s tri-state into a StateFlow for the banner
- * composable. Keeps the banner 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(
-    health: ServerHealthController,
+    networkStatus: NetworkStatusController,
     @Suppress("UnusedPrivateProperty") savedStateHandle: SavedStateHandle,
 ) : ViewModel() {
-    val health: StateFlow<ServerHealth> = health.state.stateIn(
-        scope = viewModelScope,
-        started = SharingStarted.WhileSubscribed(HEALTH_SHARE_STOP_TIMEOUT_MS),
-        initialValue = ServerHealth.Healthy,
-    )
+    val health: StateFlow<ServerHealth> = networkStatus.state
 }
 
 /**
- * Banner shown at the top of the shell when the user can't reach the server.
- * Tri-state so we tell the user *why*: no device network vs server-down.
- * Copy choices match the Flutter analogues. Auto-hides via slide+fade when
- * health returns to [ServerHealth.Healthy].
+ * 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 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 = health != ServerHealth.Healthy,
+        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 = when (health) {
-                    ServerHealth.Offline ->
-                        "No connection — check Wi-Fi or mobile data."
-                    ServerHealth.ServerDown ->
-                        "Server unreachable — your cached content is still available."
-                    ServerHealth.Healthy -> ""
-                },
-                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 -> ""
+}

android/app/src/main/java/com/fabledsword/minstrel/home/data/HomeRepository.kt

@@ -39,6 +39,9 @@ import javax.inject.Singleton
  * pre-warms the top artists via [HomeArtistPrewarmer].
  */
 @Singleton
+// Per-section observe accessors (one per Home row) inflate the function
+// count past detekt's 11 default — accessor density, not complexity.
+@Suppress("TooManyFunctions")
 class HomeRepository @Inject constructor(
     private val homeIndexDao: CachedHomeIndexDao,
     private val metadataProvider: MetadataProvider,
@@ -76,6 +79,12 @@ class HomeRepository @Inject constructor(
     fun observeLastPlayedArtists(): Flow<List<HomeTile<ArtistRef>>> =
         observeArtistSection(SECTION_LAST_PLAYED_ARTISTS)
 
+    fun observeYouMightLikeAlbums(): Flow<List<HomeTile<AlbumRef>>> =
+        observeAlbumSection(SECTION_YOU_MIGHT_LIKE_ALBUMS)
+
+    fun observeYouMightLikeArtists(): Flow<List<HomeTile<ArtistRef>>> =
+        observeArtistSection(SECTION_YOU_MIGHT_LIKE_ARTISTS)
+
     /**
      * Pulls /api/home/index, replaces each cached_home_index section,
      * and pre-warms the top artists. The section Flows re-fire on the
@@ -88,7 +97,11 @@ class HomeRepository @Inject constructor(
         replaceSection(SECTION_REDISCOVER_ARTISTS, "artist", wire.rediscoverArtists)
         replaceSection(SECTION_MOST_PLAYED_TRACKS, "track", wire.mostPlayedTracks)
         replaceSection(SECTION_LAST_PLAYED_ARTISTS, "artist", wire.lastPlayedArtists)
-        prewarmer.warm(wire.rediscoverArtists + wire.lastPlayedArtists)
+        replaceSection(SECTION_YOU_MIGHT_LIKE_ALBUMS, "album", wire.youMightLikeAlbums)
+        replaceSection(SECTION_YOU_MIGHT_LIKE_ARTISTS, "artist", wire.youMightLikeArtists)
+        prewarmer.warm(
+            wire.rediscoverArtists + wire.lastPlayedArtists + wire.youMightLikeArtists,
+        )
     }
 
     private suspend fun replaceSection(section: String, entityType: String, ids: List<String>) {
@@ -148,5 +161,7 @@ class HomeRepository @Inject constructor(
         const val SECTION_REDISCOVER_ARTISTS = "rediscover_artists"
         const val SECTION_MOST_PLAYED_TRACKS = "most_played_tracks"
         const val SECTION_LAST_PLAYED_ARTISTS = "last_played_artists"
+        const val SECTION_YOU_MIGHT_LIKE_ALBUMS = "you_might_like_albums"
+        const val SECTION_YOU_MIGHT_LIKE_ARTISTS = "you_might_like_artists"
     }
 }

android/app/src/main/java/com/fabledsword/minstrel/home/ui/HomeScreen.kt

@@ -54,6 +54,7 @@ import com.composables.icons.lucide.History
 import com.composables.icons.lucide.Lucide
 import com.composables.icons.lucide.Music
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.ServerHealth
 import com.fabledsword.minstrel.home.data.HomeRepository
 import com.fabledsword.minstrel.library.data.LibraryRepository
 import com.fabledsword.minstrel.library.widgets.AlbumCard
@@ -115,6 +116,8 @@ data class HomeSections(
     val rediscoverArtists: List<HomeTile<ArtistRef>> = emptyList(),
     val mostPlayedTracks: List<HomeTile<TrackRef>> = emptyList(),
     val lastPlayedArtists: List<HomeTile<ArtistRef>> = emptyList(),
+    val youMightLikeAlbums: List<HomeTile<AlbumRef>> = emptyList(),
+    val youMightLikeArtists: List<HomeTile<ArtistRef>> = emptyList(),
 ) {
     val isAllEmpty: Boolean
         get() = playlists.isEmpty() &&
@@ -122,7 +125,9 @@ data class HomeSections(
             rediscoverAlbums.isEmpty() &&
             rediscoverArtists.isEmpty() &&
             mostPlayedTracks.isEmpty() &&
-            lastPlayedArtists.isEmpty()
+            lastPlayedArtists.isEmpty() &&
+            youMightLikeAlbums.isEmpty() &&
+            youMightLikeArtists.isEmpty()
 }
 
 // ─── ViewModel ───────────────────────────────────────────────────────
@@ -134,7 +139,7 @@ class HomeViewModel @Inject constructor(
     private val libraryRepository: LibraryRepository,
     private val player: com.fabledsword.minstrel.player.PlayerController,
     private val shuffleSource: com.fabledsword.minstrel.cache.ShuffleSource,
-    connectivity: com.fabledsword.minstrel.connectivity.ConnectivityObserver,
+    networkStatus: com.fabledsword.minstrel.connectivity.NetworkStatusController,
 ) : ViewModel() {
 
     private val systemStatusInternal = MutableStateFlow(SystemPlaylistsStatus())
@@ -142,9 +147,13 @@ class HomeViewModel @Inject constructor(
     /** System-playlist build status for the Home placeholder cards. */
     val systemStatus: StateFlow<SystemPlaylistsStatus> = systemStatusInternal.asStateFlow()
 
-    /** True when the device has no usable internet — gates the offline-pool cards. */
-    val offline: StateFlow<Boolean> = connectivity.online
-        .map { !it }
+    /**
+     * Cache-only when there's no link OR the server is unreachable. Reads the
+     * unified [NetworkStatusController] (not the raw device link) so Home reacts
+     * to ServerDown too; the transient Unstable state stays calm (not offline).
+     */
+    val offline: StateFlow<Boolean> = networkStatus.state
+        .map { it == ServerHealth.Offline || it == ServerHealth.ServerDown }
         .stateIn(
             scope = viewModelScope,
             started = SharingStarted.WhileSubscribed(SHARE_STOP_TIMEOUT_MS),
@@ -284,13 +293,14 @@ class HomeViewModel @Inject constructor(
         combineHomeFlows().asCacheFirstStateFlow(viewModelScope)
 
     /**
-     * Five home-section flows merged into the sections struct without
-     * playlists; then merged with the playlists flow in [combineHomeFlows].
-     * Splitting it like this keeps each combine call inside the
-     * coroutines built-in arity limit (5) and avoids the typed-vararg
-     * acrobatics needed for a 6-flow combine across heterogeneous types.
+     * The core five section flows merged into the sections struct. Split
+     * out so each combine call stays inside the coroutines built-in arity
+     * limit (5) and avoids the typed-vararg acrobatics a wider combine
+     * across heterogeneous types would need. [observeHomeSections] then
+     * folds in the two you-might-like flows, and [combineHomeFlows] the
+     * playlists flow.
      */
-    private fun observeHomeSections() = combine(
+    private fun observeCoreSections() = combine(
         homeRepository.observeRecentlyAddedAlbums(),
         homeRepository.observeRediscoverAlbums(),
         homeRepository.observeRediscoverArtists(),
@@ -306,6 +316,14 @@ class HomeViewModel @Inject constructor(
         )
     }
 
+    private fun observeHomeSections() = combine(
+        observeCoreSections(),
+        homeRepository.observeYouMightLikeAlbums(),
+        homeRepository.observeYouMightLikeArtists(),
+    ) { core, ymlAlbums, ymlArtists ->
+        core.copy(youMightLikeAlbums = ymlAlbums, youMightLikeArtists = ymlArtists)
+    }
+
     private fun combineHomeFlows() =
         observeHomeSections().combine(playlistsRepository.observeAll()) { sections, playlists ->
             val merged = sections.copy(playlists = playlists)
@@ -458,6 +476,14 @@ private fun HomeSuccessContent(
                 onPlayPlaylist = onPlayPlaylist,
             )
         }
+        youMightLikeSection(
+            albums = sections.youMightLikeAlbums,
+            artists = sections.youMightLikeArtists,
+            onAlbumClick = onAlbumClick,
+            onArtistClick = onArtistClick,
+            onPlayAlbum = onPlayAlbum,
+            onPlayArtist = onPlayArtist,
+        )
         recentlyAddedSection(sections.recentlyAddedAlbums, onAlbumClick, onPlayAlbum)
         rediscoverSection(
             albums = sections.rediscoverAlbums,
@@ -662,6 +688,61 @@ private fun RediscoverBlock(
     }
 }
 
+/**
+ * "You might like" — in-library albums/artists predicted from the user's
+ * taste that they don't actively spin (server section, daily-built, cold-
+ * start gated). Sits directly under the system-playlists row. Same
+ * albums-then-artists block shape as Rediscover; the artist sub-row drops
+ * its title when an album sub-row precedes it so the two read as one section.
+ */
+private fun LazyListScope.youMightLikeSection(
+    albums: List<HomeTile<AlbumRef>>,
+    artists: List<HomeTile<ArtistRef>>,
+    onAlbumClick: (String) -> Unit,
+    onArtistClick: (String) -> Unit,
+    onPlayAlbum: suspend (String) -> Unit,
+    onPlayArtist: suspend (String) -> Unit,
+) {
+    item {
+        if (albums.isNotEmpty() || artists.isNotEmpty()) {
+            YouMightLikeBlock(
+                albums = albums,
+                artists = artists,
+                onAlbumClick = onAlbumClick,
+                onArtistClick = onArtistClick,
+                onPlayAlbum = onPlayAlbum,
+                onPlayArtist = onPlayArtist,
+            )
+        } else {
+            EmptySection(
+                title = "You might like",
+                body = "We're still learning your taste — keep listening and " +
+                    "picks you might like will show up here.",
+            )
+        }
+    }
+}
+
+@Composable
+private fun YouMightLikeBlock(
+    albums: List<HomeTile<AlbumRef>>,
+    artists: List<HomeTile<ArtistRef>>,
+    onAlbumClick: (String) -> Unit,
+    onArtistClick: (String) -> Unit,
+    onPlayAlbum: suspend (String) -> Unit,
+    onPlayArtist: suspend (String) -> Unit,
+) {
+    Column {
+        if (albums.isNotEmpty()) {
+            AlbumsRow("You might like", albums, onAlbumClick, onPlayAlbum)
+        }
+        if (artists.isNotEmpty()) {
+            val title = if (albums.isEmpty()) "You might like" else ""
+            ArtistsRow(title, artists, onArtistClick, onPlayArtist)
+        }
+    }
+}
+
 @Composable
 private fun AlbumsRow(
     title: String,
@@ -701,18 +782,19 @@ private fun PlaylistsRow(
                     icon = iconForPool(item.kind),
                     onClick = { onPlayPool(item.kind) },
                 )
-                is PlaylistRowItem.Real -> PlaylistCard(
-                    playlist = item.playlist,
-                    onClick = { onPlaylistClick(item.playlist.id) },
-                    onPlay = { onPlayPlaylist(item.playlist) },
-                    // Match Flutter: refreshable system playlists need
-                    // the live server endpoints, so disable their play
-                    // overlay when offline (user can still tap into the
-                    // detail and shuffle all from cache). User playlists
-                    // play from cache + survive offline.
-                    playEnabled = item.playlist.trackCount > 0 &&
-                        !(offline && item.playlist.refreshable),
-                )
+                is PlaylistRowItem.Real -> {
+                    // Greyed offline when the tile needs the live server or
+                    // isn't fully cached — dimmed but still tappable into the
+                    // detail to shuffle whatever subset is cached.
+                    val greyed = offline && item.playlist.unavailableOffline
+                    PlaylistCard(
+                        playlist = item.playlist,
+                        onClick = { onPlaylistClick(item.playlist.id) },
+                        onPlay = { onPlayPlaylist(item.playlist) },
+                        playEnabled = item.playlist.trackCount > 0 && !greyed,
+                        greyed = greyed,
+                    )
+                }
                 is PlaylistRowItem.Placeholder -> PlaylistPlaceholderCard(
                     label = item.label,
                     variant = item.variant,
@@ -728,7 +810,7 @@ private fun iconForPool(kind: OfflinePoolKind) = when (kind) {
 }
 
 /** A cache-backed offline pool, a real playlist tile, or a not-yet-generated slot. */
-private sealed interface PlaylistRowItem {
+internal sealed interface PlaylistRowItem {
     data class OfflinePool(val kind: OfflinePoolKind) : PlaylistRowItem
     data class Real(val playlist: PlaylistRef) : PlaylistRowItem
     data class Placeholder(val label: String, val variant: String) : PlaylistRowItem
@@ -741,55 +823,81 @@ enum class OfflinePoolKind(val label: String) {
 }
 
 /**
- * Builds the Home Playlists row. When [offline], the two cache-backed
- * pool cards (Recently played, Liked) lead the row. Then For You +
- * Discover + 3× Songs-like fixed slots (real card when generated,
- * placeholder otherwise), then the secondary system kinds (deep cuts /
- * rediscover / new for you / on this day / first listens) when they
- * exist — no placeholders for these since they're conditional on
- * library shape, not guaranteed singletons. Finally user-owned
- * playlists.
+ * Builds the Home Playlists row.
+ *
+ * Online: For You + Discover + 3× Songs-like fixed slots (real card when
+ * generated, placeholder otherwise), then the secondary system kinds (deep cuts
+ * / rediscover / new for you / on this day / first listens) when they exist —
+ * no placeholders for these since they're conditional on library shape — then
+ * user-owned playlists.
+ *
+ * Offline: the two cache-backed pools (Recently played, Liked) lead, then the
+ * same real playlists in curated order but stably partitioned fully-cached
+ * first / greyed after, and the "building/pending" placeholders are dropped
+ * (they need the server to generate, so they're meaningless offline).
  *
  * Diverges from Flutter (`flutter_client/lib/library/home_screen.dart`
  * `_buildPlaylistsRow`) which only shows the 5 fixed slots and never
  * surfaces the secondary kinds on Home. Operator authorized the
  * divergence on 2026-06-01; web UI catch-up tracked as task #53.
  */
-private fun buildPlaylistsRow(
+internal fun buildPlaylistsRow(
     owned: List<PlaylistRef>,
     status: SystemPlaylistsStatus,
     offline: Boolean,
+): List<PlaylistRowItem> {
+    if (!offline) return buildOnlineRow(owned, status)
+    val out = mutableListOf<PlaylistRowItem>(
+        PlaylistRowItem.OfflinePool(OfflinePoolKind.RECENTLY_PLAYED),
+        PlaylistRowItem.OfflinePool(OfflinePoolKind.LIKED),
+    )
+    val (available, greyed) = orderedRealPlaylists(owned).partition { !it.unavailableOffline }
+    (available + greyed).forEach { out += PlaylistRowItem.Real(it) }
+    return out
+}
+
+/** The online layout: fixed system slots (with placeholders), secondary, user. */
+private fun buildOnlineRow(
+    owned: List<PlaylistRef>,
+    status: SystemPlaylistsStatus,
 ): List<PlaylistRowItem> {
     val out = mutableListOf<PlaylistRowItem>()
-    if (offline) {
-        out += PlaylistRowItem.OfflinePool(OfflinePoolKind.RECENTLY_PLAYED)
-        out += PlaylistRowItem.OfflinePool(OfflinePoolKind.LIKED)
-    }
     out += owned.firstOrNull { it.systemVariant == "for_you" }
         ?.let { PlaylistRowItem.Real(it) }
         ?: PlaylistRowItem.Placeholder("For You", variantFor("for-you", status))
     out += owned.firstOrNull { it.systemVariant == "discover" }
         ?.let { PlaylistRowItem.Real(it) }
         ?: PlaylistRowItem.Placeholder("Discover", variantFor("discover", status))
-    val songsLike = owned.filter { it.systemVariant == "songs_like_artist" }.take(3)
+    val songsLike = owned.filter { it.systemVariant == "songs_like_artist" }.take(SONGS_LIKE_SLOTS)
     for (i in 0 until SONGS_LIKE_SLOTS) {
         out += songsLike.getOrNull(i)
             ?.let { PlaylistRowItem.Real(it) }
             ?: PlaylistRowItem.Placeholder("Songs like…", variantFor("songs-like", status))
     }
-    // Secondary system kinds in server-registry order. Only included
-    // when actually generated — these depend on library shape (Deep
-    // cuts needs deep albums, On this day needs prior history, etc.)
-    // so a missing one means "not enough data" rather than "still
-    // building".
     for (variant in SECONDARY_SYSTEM_VARIANTS) {
-        owned.firstOrNull { it.systemVariant == variant }
-            ?.let { out += PlaylistRowItem.Real(it) }
+        owned.firstOrNull { it.systemVariant == variant }?.let { out += PlaylistRowItem.Real(it) }
     }
     owned.filter { it.systemVariant == null }.forEach { out += PlaylistRowItem.Real(it) }
     return out
 }
 
+/**
+ * Curated real-playlist order (system primaries, then secondary, then user).
+ * Must mirror [buildOnlineRow]'s slot order — the offline row reuses this and
+ * only differs by dropping placeholders + partitioning available-first.
+ */
+private fun orderedRealPlaylists(owned: List<PlaylistRef>): List<PlaylistRef> {
+    val out = mutableListOf<PlaylistRef>()
+    owned.firstOrNull { it.systemVariant == "for_you" }?.let { out += it }
+    owned.firstOrNull { it.systemVariant == "discover" }?.let { out += it }
+    out += owned.filter { it.systemVariant == "songs_like_artist" }.take(SONGS_LIKE_SLOTS)
+    for (variant in SECONDARY_SYSTEM_VARIANTS) {
+        owned.firstOrNull { it.systemVariant == variant }?.let { out += it }
+    }
+    owned.filter { it.systemVariant == null }.forEach { out += it }
+    return out
+}
+
 private fun variantFor(slot: String, s: SystemPlaylistsStatus): String = when {
     s.inFlight -> "building"
     s.lastError != null -> "failed"

android/app/src/main/java/com/fabledsword/minstrel/library/data/LibraryRepository.kt

@@ -105,6 +105,22 @@ class LibraryRepository @Inject constructor(
     suspend fun fetchArtistTracks(id: String): List<TrackRef> =
         api.getArtistTracks(id).map { it.toDomain() }
 
+    /**
+     * Pulls related artists for the ArtistDetail "Similar artists"
+     * strip. Network-only — non-critical UI, callers swallow failures
+     * and render nothing rather than blocking the screen.
+     */
+    suspend fun fetchSimilarArtists(id: String): List<ArtistRef> =
+        api.getSimilarArtists(id).map { it.toDomain() }
+
+    /**
+     * Pulls the artist's top tracks for the ArtistDetail "Top tracks"
+     * panel. Network-only; tapping a row plays this exact list as a
+     * queue, so no persistence is needed.
+     */
+    suspend fun fetchArtistTopTracks(id: String): List<TrackRef> =
+        api.getArtistTopTracks(id).map { it.toDomain() }
+
     /**
      * Pulls the album detail (AlbumRef + tracks), persists both, and
      * returns the in-memory snapshot. Lets the AlbumDetail screen

android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailScreen.kt

@@ -1,3 +1,5 @@
+@file:Suppress("TooManyFunctions") // Compose screen + private helper composables
+
 package com.fabledsword.minstrel.library.ui
 
 import androidx.compose.animation.Crossfade
@@ -18,6 +20,7 @@ import androidx.compose.foundation.lazy.grid.GridCells
 import androidx.compose.foundation.lazy.grid.GridItemSpan
 import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
 import androidx.compose.foundation.lazy.grid.items
+import androidx.compose.foundation.lazy.items as lazyItems
 import androidx.compose.foundation.shape.CircleShape
 import androidx.compose.material3.Button
 import androidx.compose.material3.ExperimentalMaterial3Api
@@ -46,21 +49,27 @@ import com.composables.icons.lucide.Lucide
 import com.composables.icons.lucide.Play
 import com.composables.icons.lucide.User
 import com.fabledsword.minstrel.library.widgets.AlbumCard
-import com.fabledsword.minstrel.models.ArtistDetailRef
+import com.fabledsword.minstrel.library.widgets.ArtistCard
 import com.fabledsword.minstrel.models.ArtistRef
+import com.fabledsword.minstrel.models.TrackRef
 import com.fabledsword.minstrel.models.albumCoverPath
 import com.fabledsword.minstrel.nav.AlbumDetail
+import com.fabledsword.minstrel.nav.ArtistDetail
+import com.fabledsword.minstrel.shared.formatDuration
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.HorizontalScrollRow
 import com.fabledsword.minstrel.shared.widgets.LikeButton
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.ServerImage
 import com.fabledsword.minstrel.shared.widgets.SkeletonAlbumTile
+import com.fabledsword.minstrel.shared.widgets.TrackRow
 
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 fun ArtistDetailScreen(
     navController: NavHostController,
     viewModel: ArtistDetailViewModel = hiltViewModel(),
+    playerViewModel: com.fabledsword.minstrel.player.ui.PlayerViewModel = hiltViewModel(),
 ) {
     val state by viewModel.uiState.collectAsStateWithLifecycle()
     val snackbarHostState = remember { SnackbarHostState() }
@@ -102,23 +111,35 @@ fun ArtistDetailScreen(
                         title = "Couldn't load artist",
                         body = s.message,
                     )
-                    is ArtistDetailUiState.Success -> {
-                        val artistLiked by viewModel.artistLiked
-                            .collectAsStateWithLifecycle()
-                        ArtistBody(
-                            detail = s.detail,
-                            artistLiked = artistLiked,
-                            onPlay = viewModel::playArtist,
-                            onToggleLike = viewModel::toggleLikeArtist,
-                            onAlbumClick = { id -> navController.navigate(AlbumDetail(id)) },
-                        )
-                    }
+                    is ArtistDetailUiState.Success ->
+                        ArtistSuccessBody(s, viewModel, playerViewModel, navController)
                 }
             }
         }
     }
 }
 
+@Composable
+private fun ArtistSuccessBody(
+    state: ArtistDetailUiState.Success,
+    viewModel: ArtistDetailViewModel,
+    playerViewModel: com.fabledsword.minstrel.player.ui.PlayerViewModel,
+    navController: NavHostController,
+) {
+    val artistLiked by viewModel.artistLiked.collectAsStateWithLifecycle()
+    val playerState by playerViewModel.uiState.collectAsStateWithLifecycle()
+    ArtistBody(
+        state = state,
+        artistLiked = artistLiked,
+        playingTrackId = playerState.currentTrack?.id,
+        onPlay = viewModel::playArtist,
+        onToggleLike = viewModel::toggleLikeArtist,
+        onAlbumClick = { id -> navController.navigate(AlbumDetail(id)) },
+        onTopTrackClick = viewModel::playTopTracks,
+        onSimilarArtistClick = { id -> navController.navigate(ArtistDetail(id)) },
+    )
+}
+
 private fun titleFor(state: ArtistDetailUiState): String = when (state) {
     is ArtistDetailUiState.Success -> state.detail.artist.name
     is ArtistDetailUiState.Loading -> state.seed?.name ?: "Artist"
@@ -127,12 +148,16 @@ private fun titleFor(state: ArtistDetailUiState): String = when (state) {
 
 @Composable
 private fun ArtistBody(
-    detail: ArtistDetailRef,
+    state: ArtistDetailUiState.Success,
     artistLiked: Boolean,
+    playingTrackId: String?,
     onPlay: () -> Unit,
     onToggleLike: () -> Unit,
     onAlbumClick: (String) -> Unit,
+    onTopTrackClick: (Int) -> Unit,
+    onSimilarArtistClick: (String) -> Unit,
 ) {
+    val detail = state.detail
     LazyVerticalGrid(
         columns = GridCells.Adaptive(minSize = 176.dp),
         modifier = Modifier.fillMaxSize(),
@@ -149,6 +174,23 @@ private fun ArtistBody(
                 onToggleLike = onToggleLike,
             )
         }
+        if (state.topTracks.isNotEmpty()) {
+            item(span = { GridItemSpan(maxLineSpan) }) {
+                TopTracksPanel(
+                    tracks = state.topTracks,
+                    playingTrackId = playingTrackId,
+                    onTrackClick = onTopTrackClick,
+                )
+            }
+        }
+        if (state.similarArtists.isNotEmpty()) {
+            item(span = { GridItemSpan(maxLineSpan) }) {
+                SimilarArtistsStrip(
+                    artists = state.similarArtists,
+                    onArtistClick = onSimilarArtistClick,
+                )
+            }
+        }
         if (detail.albums.isEmpty()) {
             item(span = { GridItemSpan(maxLineSpan) }) {
                 EmptyAlbumsHint()
@@ -161,6 +203,67 @@ private fun ArtistBody(
     }
 }
 
+@Composable
+private fun TopTracksPanel(
+    tracks: List<TrackRef>,
+    playingTrackId: String?,
+    onTrackClick: (Int) -> Unit,
+) {
+    Column(modifier = Modifier.fillMaxWidth()) {
+        Text(
+            text = "Top tracks",
+            style = MaterialTheme.typography.titleLarge,
+            color = MaterialTheme.colorScheme.onBackground,
+            modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
+        )
+        tracks.forEachIndexed { index, track ->
+            TopTrackRow(
+                track = track,
+                nowPlaying = track.id == playingTrackId,
+                onClick = { onTrackClick(index) },
+            )
+        }
+    }
+}
+
+@Composable
+private fun TopTrackRow(
+    track: TrackRef,
+    nowPlaying: Boolean,
+    onClick: () -> Unit,
+) {
+    TrackRow(
+        title = track.title,
+        artist = track.artistName,
+        trackId = track.id,
+        onClick = onClick,
+        nowPlaying = nowPlaying,
+        trailing = {
+            Text(
+                text = formatDuration(track.durationSec, zero = "--:--"),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.padding(start = 12.dp),
+            )
+        },
+    )
+}
+
+@Composable
+private fun SimilarArtistsStrip(
+    artists: List<ArtistRef>,
+    onArtistClick: (String) -> Unit,
+) {
+    HorizontalScrollRow(title = "Similar artists") {
+        lazyItems(items = artists, key = { it.id }) { artist ->
+            ArtistCard(
+                artist = artist,
+                onClick = { onArtistClick(artist.id) },
+            )
+        }
+    }
+}
+
 @Composable
 private fun ArtistHeader(
     artist: ArtistRef,

android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailViewModel.kt

@@ -9,6 +9,7 @@ import com.fabledsword.minstrel.library.data.LibraryRepository
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.models.ArtistDetailRef
 import com.fabledsword.minstrel.models.ArtistRef
+import com.fabledsword.minstrel.models.TrackRef
 import com.fabledsword.minstrel.nav.ArtistDetail
 import com.fabledsword.minstrel.nav.DetailSeedCache
 import com.fabledsword.minstrel.player.PlayerController
@@ -23,13 +24,18 @@ import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.receiveAsFlow
 import kotlinx.coroutines.flow.stateIn
 import kotlinx.coroutines.launch
+import timber.log.Timber
 import javax.inject.Inject
 
 private const val SHARE_STOP_TIMEOUT_MS = 5_000L
 
 sealed interface ArtistDetailUiState {
     data class Loading(val seed: ArtistRef? = null) : ArtistDetailUiState
-    data class Success(val detail: ArtistDetailRef) : ArtistDetailUiState
+    data class Success(
+        val detail: ArtistDetailRef,
+        val similarArtists: List<ArtistRef> = emptyList(),
+        val topTracks: List<TrackRef> = emptyList(),
+    ) : ArtistDetailUiState
     data class Error(val message: String) : ArtistDetailUiState
 }
 
@@ -82,6 +88,7 @@ class ArtistDetailViewModel @Inject constructor(
         try {
             val detail = repository.refreshArtistDetail(artistId)
             internal.value = ArtistDetailUiState.Success(detail)
+            loadSecondarySections()
         } catch (
             @Suppress("TooGenericExceptionCaught") e: Throwable,
         ) {
@@ -89,6 +96,31 @@ class ArtistDetailViewModel @Inject constructor(
         }
     }
 
+    /**
+     * Pulls the non-critical "Similar artists" + "Top tracks" sections
+     * and folds them into the live Success state. Each failure is
+     * swallowed (logged only) — these sections render absent rather than
+     * blocking, so the core artist view never depends on them.
+     */
+    private suspend fun loadSecondarySections() {
+        val similar = sectionOrEmpty { repository.fetchSimilarArtists(artistId) }
+        val top = sectionOrEmpty { repository.fetchArtistTopTracks(artistId) }
+        val current = internal.value
+        if (current is ArtistDetailUiState.Success) {
+            internal.value = current.copy(similarArtists = similar, topTracks = top)
+        }
+    }
+
+    private inline fun <T> sectionOrEmpty(block: () -> List<T>): List<T> =
+        try {
+            block()
+        } catch (
+            @Suppress("TooGenericExceptionCaught") e: Throwable,
+        ) {
+            Timber.w(e, "Artist secondary section fetch failed for %s", artistId)
+            emptyList()
+        }
+
     /**
      * Pull every track across the artist's albums, shuffle, and start
      * playing. Mirrors Flutter's artist Play button — pressing Play on
@@ -118,4 +150,20 @@ class ArtistDetailViewModel @Inject constructor(
             }
         }
     }
+
+    /**
+     * Plays the loaded "Top tracks" list starting at [index] — the top
+     * tracks are themselves the playable queue (mirrors the web client's
+     * sectionTracks = top-tracks behaviour). No network round-trip; the
+     * list is already in the Success state.
+     */
+    fun playTopTracks(index: Int) {
+        val tracks = (internal.value as? ArtistDetailUiState.Success)?.topTracks.orEmpty()
+        if (tracks.isEmpty()) return
+        player.setQueue(
+            tracks = tracks,
+            initialIndex = index.coerceIn(0, tracks.lastIndex),
+            source = "artist-top:$artistId",
+        )
+    }
 }

android/app/src/main/java/com/fabledsword/minstrel/models/Playlist.kt

@@ -20,6 +20,8 @@ data class PlaylistRef(
     val trackCount: Int = 0,
     val coverUrl: String = "",
     val ownerUsername: String = "",
+    /** All member tracks resident in the audio cache — playable fully offline. */
+    val fullyCached: Boolean = false,
 ) {
     val isSystem: Boolean get() = systemVariant != null
 
@@ -30,6 +32,13 @@ data class PlaylistRef(
      * expose a refresh trigger; rebuilds are scheduler-driven).
      */
     val refreshable: Boolean get() = isSystem && systemVariant != "songs_like_artist"
+
+    /**
+     * Can't be relied on while offline — either it needs the live server to
+     * (re)generate (a refreshable system mix) or not all its tracks are cached.
+     * Callers combine this with the current offline state to grey the tile.
+     */
+    val unavailableOffline: Boolean get() = refreshable || !fullyCached
 }
 
 /**

android/app/src/main/java/com/fabledsword/minstrel/models/wire/EventsWire.kt

@@ -1,5 +1,9 @@
+@file:OptIn(ExperimentalSerializationApi::class)
+
 package com.fabledsword.minstrel.models.wire
 
+import kotlinx.serialization.EncodeDefault
+import kotlinx.serialization.ExperimentalSerializationApi
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
@@ -15,7 +19,11 @@ import kotlinx.serialization.Serializable
 
 @Serializable
 data class PlayStartedRequest(
-    val type: String = "play_started",
+    // Discriminator MUST stay on the wire. The app's Json has
+    // encodeDefaults=false, so without this a `type` left at its
+    // default is omitted entirely and the server 400s the event as
+    // "unknown event type" — silently dropping every native play.
+    @EncodeDefault(EncodeDefault.Mode.ALWAYS) val type: String = "play_started",
     @SerialName("track_id") val trackId: String,
     @SerialName("client_id") val clientId: String,
     val source: String? = null,
@@ -28,21 +36,21 @@ data class PlayStartedResponse(
 
 @Serializable
 data class PlayEndedRequest(
-    val type: String = "play_ended",
+    @EncodeDefault(EncodeDefault.Mode.ALWAYS) val type: String = "play_ended",
     @SerialName("play_event_id") val playEventId: String,
     @SerialName("duration_played_ms") val durationPlayedMs: Long,
 )
 
 @Serializable
 data class PlaySkippedRequest(
-    val type: String = "play_skipped",
+    @EncodeDefault(EncodeDefault.Mode.ALWAYS) val type: String = "play_skipped",
     @SerialName("play_event_id") val playEventId: String,
     @SerialName("position_ms") val positionMs: Long,
 )
 
 @Serializable
 data class PlayOfflineRequest(
-    val type: String = "play_offline",
+    @EncodeDefault(EncodeDefault.Mode.ALWAYS) val type: String = "play_offline",
     @SerialName("track_id") val trackId: String,
     @SerialName("client_id") val clientId: String,
     val at: String,

android/app/src/main/java/com/fabledsword/minstrel/models/wire/HomeIndexWire.kt

@@ -10,13 +10,17 @@ import kotlinx.serialization.Serializable
  * `internal/api/types.go HomeIndexPayload`).
  *
  * Section name implies entity type; no per-entry type tag is needed:
- *   - recentlyAddedAlbums → album
- *   - rediscoverAlbums    → album
- *   - rediscoverArtists   → artist
- *   - mostPlayedTracks    → track
- *   - lastPlayedArtists   → artist
+ *   - recentlyAddedAlbums  → album
+ *   - rediscoverAlbums     → album
+ *   - rediscoverArtists    → artist
+ *   - mostPlayedTracks     → track
+ *   - lastPlayedArtists    → artist
+ *   - youMightLikeAlbums   → album
+ *   - youMightLikeArtists  → artist
  *
- * All slices default to empty so missing keys don't throw on decode.
+ * All slices default to empty so missing keys don't throw on decode —
+ * which also keeps the client safe against older servers that don't
+ * emit the you-might-like sections yet.
  */
 @Serializable
 data class HomeIndexWire(
@@ -25,4 +29,6 @@ data class HomeIndexWire(
     @SerialName("rediscover_artists") val rediscoverArtists: List<String> = emptyList(),
     @SerialName("most_played_tracks") val mostPlayedTracks: List<String> = emptyList(),
     @SerialName("last_played_artists") val lastPlayedArtists: List<String> = emptyList(),
+    @SerialName("you_might_like_albums") val youMightLikeAlbums: List<String> = emptyList(),
+    @SerialName("you_might_like_artists") val youMightLikeArtists: List<String> = emptyList(),
 )

android/app/src/main/java/com/fabledsword/minstrel/player/MinstrelForwardingPlayer.kt

@@ -12,12 +12,15 @@ import androidx.media3.common.MediaItem
 import androidx.media3.common.Player
 import com.fabledsword.minstrel.player.output.ActiveUpnp
 import com.fabledsword.minstrel.player.output.ActiveUpnpHolder
+import com.fabledsword.minstrel.player.output.upnp.SoapFaultException
 import com.fabledsword.minstrel.player.output.upnp.TransportState
+import java.io.IOException
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.channels.Channel
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.isActive
@@ -39,9 +42,15 @@ import timber.log.Timber
  * wrapped ExoPlayer stays paused at the position it had when the
  * route was selected.
  *
- * Drop heuristic: 3 consecutive poll failures fire [onDrop]. The
- * factory wraps that callback into a SharedFlow consumed by the
- * NowPlaying surface as a snackbar.
+ * Drop heuristic: the 1 Hz poll loop is the *sole* arbiter of route
+ * liveness -- [RemotePlayerState.recordPollFailure]'s rolling threshold
+ * (DROP_THRESHOLD consecutive failures) fires [onDrop]. A failed transport
+ * command (play/pause/seek/next) does NOT drop on its own: a locked phone's
+ * WiFi power-save can stall a single command's socket I/O for a second or
+ * two while the renderer is perfectly reachable, so commands retry on
+ * transient IO failure and otherwise defer to the poll loop. The factory
+ * wraps the [onDrop] callback into a SharedFlow consumed by the NowPlaying
+ * surface as a snackbar.
  *
  * Queue mode: OutputPickerController loads the full queue into Sonos's
  * native queue via ClearQueue + AddURIToQueue, then points the
@@ -172,13 +181,14 @@ class MinstrelForwardingPlayer(
         if (active == null) {
             super.play()
         } else {
+            remoteState.setPlayIntent(true)
             scope.launch {
-                runCatching { active.avTransport.play() }
+                runCatching { retryTransport { active.avTransport.play() } }
                     .onSuccess {
                         remoteState.applyTransportPlaying()
                         notifyRemoteStateChanged()
                     }
-                    .onFailure { handleSoapFailure(active, it) }
+                    .onFailure { handleTransportFailure(active, it) }
             }
         }
     }
@@ -193,13 +203,14 @@ class MinstrelForwardingPlayer(
         if (active == null) {
             super.pause()
         } else {
+            remoteState.setPlayIntent(false)
             scope.launch {
-                runCatching { active.avTransport.pause() }
+                runCatching { retryTransport { active.avTransport.pause() } }
                     .onSuccess {
                         remoteState.applyTransportPaused()
                         notifyRemoteStateChanged()
                     }
-                    .onFailure { handleSoapFailure(active, it) }
+                    .onFailure { handleTransportFailure(active, it) }
             }
         }
     }
@@ -222,8 +233,8 @@ class MinstrelForwardingPlayer(
                 trackNumber = remoteState.trackNumber,
             )
             scope.launch {
-                runCatching { active.avTransport.seek(positionMs) }
-                    .onFailure { handleSoapFailure(active, it) }
+                runCatching { retryTransport { active.avTransport.seek(positionMs) } }
+                    .onFailure { handleTransportFailure(active, it) }
             }
         }
     }
@@ -253,11 +264,13 @@ class MinstrelForwardingPlayer(
         )
         scope.launch {
             runCatching {
-                active.avTransport.seekToTrack(mediaItemIndex + 1)
-                if (positionMs > 0L) {
-                    active.avTransport.seek(positionMs)
+                retryTransport {
+                    active.avTransport.seekToTrack(mediaItemIndex + 1)
+                    if (positionMs > 0L) {
+                        active.avTransport.seek(positionMs)
+                    }
                 }
-            }.onFailure { handleSoapFailure(active, it) }
+            }.onFailure { handleTransportFailure(active, it) }
         }
     }
 
@@ -280,8 +293,8 @@ class MinstrelForwardingPlayer(
             SystemClock.elapsedRealtime() + PENDING_TRANSPORT_SAFETY_TIMEOUT_MS,
         )
         scope.launch {
-            runCatching { active.avTransport.next() }
-                .onFailure { handleSoapFailure(active, it) }
+            runCatching { retryTransport { active.avTransport.next() } }
+                .onFailure { handleTransportFailure(active, it) }
         }
     }
 
@@ -303,8 +316,8 @@ class MinstrelForwardingPlayer(
             SystemClock.elapsedRealtime() + PENDING_TRANSPORT_SAFETY_TIMEOUT_MS,
         )
         scope.launch {
-            runCatching { active.avTransport.previous() }
-                .onFailure { handleSoapFailure(active, it) }
+            runCatching { retryTransport { active.avTransport.previous() } }
+                .onFailure { handleTransportFailure(active, it) }
         }
     }
 
@@ -385,11 +398,34 @@ class MinstrelForwardingPlayer(
         super.release()
     }
 
-    private fun handleSoapFailure(active: ActiveUpnp, t: Throwable) {
-        pollJob?.cancel()
-        Timber.w(t, "UPnP transport call failed on %s", active.routeName)
-        remoteState.applyError(t)
-        handler.post { onDrop(active.routeName) }
+    /**
+     * Run a transport SOAP block, retrying transport-level (IO) failures a
+     * few times with backoff. A locked phone's WiFi power-save can stall the
+     * first socket I/O for a second or two; a retry lets the command land once
+     * WiFi wakes instead of being abandoned. A [SoapFaultException] (the
+     * renderer answered and rejected the action) is NOT retried -- the device
+     * is alive and retrying won't change its verdict.
+     */
+    private suspend fun <T> retryTransport(block: suspend () -> T): T =
+        retryTransientIo(TRANSPORT_RETRY_ATTEMPTS, TRANSPORT_RETRY_BACKOFF_MS, block)
+
+    /**
+     * A transport SOAP command failed even after retries. Deliberately does
+     * NOT declare the route dropped: the 1 Hz poll loop is the single arbiter
+     * of liveness (DROP_THRESHOLD consecutive poll failures). A locked phone's
+     * WiFi power-save can fail one command while the renderer is perfectly
+     * reachable; dropping on a single command falsely kicked playback back to
+     * the phone. We log, leave the poll loop running, and nudge an immediate
+     * poll so the UI reconciles to Sonos's actual state -- if the renderer is
+     * truly gone, the poll loop trips the drop on its own.
+     */
+    private fun handleTransportFailure(active: ActiveUpnp, t: Throwable) {
+        if (t is SoapFaultException) {
+            Timber.w(t, "UPnP transport rejected by %s -- device alive, no drop", active.routeName)
+        } else {
+            Timber.w(t, "UPnP transport failed on %s -- poll loop arbitrates", active.routeName)
+        }
+        pollTrigger.trySend(Unit)
     }
 
     private fun onActiveChanged(active: ActiveUpnp?) {
@@ -513,5 +549,39 @@ class MinstrelForwardingPlayer(
         // when Sonos's reported Track matches the wrapped player; this only
         // kicks in if SOAP fails or Sonos drops the ack entirely.
         const val PENDING_TRANSPORT_SAFETY_TIMEOUT_MS = 5_000L
+        // Transport commands retry transient IO failures so a single WiFi
+        // power-save stall (locked phone) doesn't abandon the command. 3
+        // attempts x the SoapClient's 2s connect timeout + backoff bounds the
+        // worst case at ~7s; a still-failing command then defers to the poll.
+        const val TRANSPORT_RETRY_ATTEMPTS = 3
+        const val TRANSPORT_RETRY_BACKOFF_MS = 400L
+    }
+}
+
+/**
+ * Retry [block] on transient transport-level ([IOException]) failures, with
+ * [backoffMs] between attempts, up to [attempts] total. Anything that is not
+ * an [IOException] -- notably [SoapFaultException], where the renderer
+ * answered and rejected the action -- propagates immediately: the device is
+ * alive, so retrying won't change its verdict. Extracted from
+ * [MinstrelForwardingPlayer] so a locked phone's WiFi power-save stall doesn't
+ * abandon a single transport command (the bug that falsely reverted Sonos
+ * playback to local audio).
+ */
+internal suspend fun <T> retryTransientIo(
+    attempts: Int,
+    backoffMs: Long,
+    block: suspend () -> T,
+): T {
+    var attempt = 0
+    while (true) {
+        try {
+            return block()
+        } catch (io: IOException) {
+            attempt += 1
+            if (attempt >= attempts) throw io
+            Timber.w(io, "transient transport failure (attempt %d) -- retrying", attempt)
+            delay(backoffMs)
+        }
     }
 }

android/app/src/main/java/com/fabledsword/minstrel/player/OfflineGatedDataSource.kt

@@ -3,14 +3,14 @@ package com.fabledsword.minstrel.player
 import androidx.media3.datasource.DataSource
 import androidx.media3.datasource.DataSpec
 import androidx.media3.datasource.TransferListener
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.connectivity.ServerHealth
-import com.fabledsword.minstrel.connectivity.ServerHealthController
 import java.io.IOException
 import java.io.InterruptedIOException
 
 /**
  * DataSource wrapper that fails the network read immediately when
- * [ServerHealthController] reports a non-Healthy state. CacheDataSource only
+ * [NetworkStatusController] reports a gating state. CacheDataSource only
  * calls this upstream factory on cache misses, so playback of cached audio is
  * unaffected -- only "tap a non-cached track while offline" hits this branch
  * and gets a fast, meaningful error instead of a multi-second network timeout
@@ -22,10 +22,23 @@ import java.io.InterruptedIOException
  */
 class OfflineGatedDataSource(
     private val delegate: DataSource,
-    private val health: ServerHealthController,
+    private val health: NetworkStatusController,
 ) : DataSource {
 
     override fun open(dataSpec: DataSpec): Long {
+        gateOnHealth()
+        return try {
+            val opened = delegate.open(dataSpec)
+            health.reportSuccess() // bytes flowing from the server == reachable
+            opened
+        } catch (e: IOException) {
+            health.reportFailure() // real network read failed → arbitrate via /healthz
+            throw e
+        }
+    }
+
+    /** Fast-fail before touching the network when the server can't be reached. */
+    private fun gateOnHealth() {
         when (health.state.value) {
             ServerHealth.Offline -> throw OfflineException(
                 "Track not in the on-device cache and the device is offline.",
@@ -33,9 +46,9 @@ class OfflineGatedDataSource(
             ServerHealth.ServerDown -> throw OfflineException(
                 "Track not in the on-device cache and the Minstrel server is unreachable.",
             )
-            ServerHealth.Healthy -> Unit
+            // Unstable is non-gating: still try the network. Healthy too.
+            ServerHealth.Unstable, ServerHealth.Healthy -> Unit
         }
-        return delegate.open(dataSpec)
     }
 
     override fun close() = delegate.close()
@@ -49,7 +62,7 @@ class OfflineGatedDataSource(
 
 class OfflineGatedDataSourceFactory(
     private val upstream: DataSource.Factory,
-    private val health: ServerHealthController,
+    private val health: NetworkStatusController,
 ) : DataSource.Factory {
     override fun createDataSource(): DataSource =
         OfflineGatedDataSource(upstream.createDataSource(), health)

android/app/src/main/java/com/fabledsword/minstrel/player/PlayEventsReporter.kt

@@ -6,6 +6,7 @@ import androidx.lifecycle.ProcessLifecycleOwner
 import com.fabledsword.minstrel.api.endpoints.EventsApi
 import com.fabledsword.minstrel.auth.AuthStore
 import com.fabledsword.minstrel.cache.mutations.MutationQueue
+import com.fabledsword.minstrel.cache.mutations.PlayEndedPayload
 import com.fabledsword.minstrel.cache.mutations.PlayOfflinePayload
 import com.fabledsword.minstrel.di.ApplicationScope
 import com.fabledsword.minstrel.models.wire.PlayEndedRequest
@@ -64,11 +65,24 @@ class PlayEventsReporter @Inject constructor(
     private var curLastPositionMs: Long = 0
     private var curDurationMs: Long = 0
 
+    // Whether the currently-tracked play is actively playing (vs paused).
+    // onStop reads this: a backgrounded play that's still playing is left
+    // to the live path (the foreground service keeps us alive), while a
+    // paused one is durably closed so a kill can't orphan its open row.
+    private var curPlaying: Boolean = false
+
     // Server play_event_id when the live play_started succeeded;
     // null if start failed/offline — then the close is captured into
     // the offline mutation queue instead of a live ended/skipped.
     private var openPlayEventId: String? = null
 
+    // True from beginTrack until startLive's play_started resolves. When a
+    // close races an in-flight start (id still null), the server row is
+    // being created but we've lost its id — we must NOT also enqueue an
+    // offline play (that would duplicate); the server auto-closes the
+    // orphan on the next play_started instead.
+    private var startInFlight: Boolean = false
+
     private var prevTrackId: String? = null
 
     init {
@@ -95,7 +109,7 @@ class PlayEventsReporter @Inject constructor(
     ) {
         // Track-change → close the prior tracked play.
         if (trackId != prevTrackId && curTrackId != null) {
-            closeCurrent(viaOffline = false)
+            closeCurrent()
         }
 
         // Entered playing for a new track → begin tracking it.
@@ -110,6 +124,7 @@ class PlayEventsReporter @Inject constructor(
         if (curTrackId != null && trackId == curTrackId) {
             curLastPositionMs = positionMs
             if (durationMs > 0) curDurationMs = durationMs
+            curPlaying = playing
         }
 
         prevTrackId = trackId
@@ -121,12 +136,18 @@ class PlayEventsReporter @Inject constructor(
         curSource = source
         curLastPositionMs = 0
         curDurationMs = durationMs
+        curPlaying = true
         openPlayEventId = null
+        startInFlight = true
         startLive(trackId = trackId, source = source)
     }
 
     private fun startLive(trackId: String, source: String?) {
-        val cid = resolveClientId() ?: return
+        val cid = resolveClientId()
+        if (cid == null) {
+            startInFlight = false
+            return
+        }
         scope.launch {
             try {
                 val response = api.playStarted(
@@ -144,56 +165,72 @@ class PlayEventsReporter @Inject constructor(
             ) {
                 // Offline / flaky — openPlayEventId stays null; close
                 // path will enqueue the completed play for replay.
+            } finally {
+                startInFlight = false
             }
         }
     }
 
-    private fun closeCurrent(viaOffline: Boolean) {
+    /**
+     * Closes the tracked play. Routes by whether the server already has an
+     * open row, NOT by caller context — this is what keeps background /
+     * track-change / failure paths from each minting a second row:
+     *  - open server row (id) → close it by id; on failure enqueue a durable
+     *    close-by-id (never an offline play).
+     *  - start in flight (no id yet) → leave it; the server auto-closes the
+     *    orphan on the next play_started. Enqueuing offline here would
+     *    duplicate the in-flight row.
+     *  - no server row at all → record the whole play offline.
+     *
+     * Always uses the actual position played; the server's skip rule
+     * (50%/30s defaults) classifies was_skipped from it.
+     */
+    private fun closeCurrent() {
         val trackId = curTrackId
         val startedAt = curStartedAt
         if (trackId == null || startedAt == null) {
             resetCurrent()
             return
         }
-        // Always send the actual position played to; the server's
-        // skip rule (50%/30s defaults, configurable) classifies
-        // was_skipped from this. If the track ran to completion the
-        // last observed position is ~= duration, which gives ratio ~1
-        // and the server records a non-skip. The COMPLETION_TOLERANCE
-        // rounding the prior shape did is no longer needed — the
-        // server's threshold is the source of truth.
         val durationMs = curLastPositionMs
         val source = curSource
         val id = openPlayEventId
-
-        if (!viaOffline && id != null) {
-            scope.launch {
-                try {
-                    api.playEnded(
-                        PlayEndedRequest(
-                            playEventId = id,
-                            durationPlayedMs = durationMs,
-                        ),
-                    )
-                } catch (
-                    @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
-                ) {
-                    enqueueOffline(trackId, startedAt, source, durationMs)
-                }
-            }
-        } else {
-            enqueueOffline(trackId, startedAt, source, durationMs)
+        val inFlight = startInFlight
+        when {
+            id != null -> closeById(id, durationMs)
+            inFlight -> Unit
+            else -> enqueueOffline(trackId, startedAt, source, durationMs)
         }
         resetCurrent()
     }
 
+    private fun closeById(id: String, durationMs: Long) {
+        scope.launch {
+            try {
+                api.playEnded(
+                    PlayEndedRequest(playEventId = id, durationPlayedMs = durationMs),
+                )
+            } catch (
+                @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
+            ) {
+                // Durable close-by-id (idempotent server-side) — survives a
+                // process kill without orphaning the open row or duplicating.
+                mutationQueue.enqueuePlayEnded(
+                    PlayEndedPayload(playEventId = id, durationPlayedMs = durationMs),
+                )
+            }
+        }
+    }
+
     private fun resetCurrent() {
         curTrackId = null
         curStartedAt = null
         curSource = null
         curLastPositionMs = 0
         curDurationMs = 0
+        curPlaying = false
         openPlayEventId = null
+        startInFlight = false
     }
 
     private fun enqueueOffline(
@@ -232,8 +269,17 @@ class PlayEventsReporter @Inject constructor(
     // ── Lifecycle: durable-close on app background / detach ────────
 
     override fun onStop(owner: LifecycleOwner) {
-        if (curTrackId != null) {
-            closeCurrent(viaOffline = true)
+        // App backgrounded. If the tracked play is still PLAYING, leave it
+        // alone: the foreground media service keeps the process — and this
+        // app-scope uiState collector — alive, so the live state machine
+        // closes the play accurately on the next real track change. Closing
+        // here (the old always-offline behavior) raced the collector's
+        // re-begin and minted a duplicate, skip-misclassified row on every
+        // screen-lock. Only durably close a PAUSED play, where no further
+        // progress will happen and a process kill would otherwise orphan the
+        // open server row. See docs/superpowers/2026-06-11 contract audit.
+        if (curTrackId != null && !curPlaying) {
+            closeCurrent()
         }
     }
 }

android/app/src/main/java/com/fabledsword/minstrel/player/PlaybackErrorReporter.kt

@@ -1,5 +1,6 @@
 package com.fabledsword.minstrel.player
 
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.di.ApplicationScope
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.channels.Channel
@@ -40,6 +41,7 @@ private const val DEBOUNCE_MS = 2_000L
 class PlaybackErrorReporter @Inject constructor(
     private val playerController: PlayerController,
     private val repository: PlaybackErrorRepository,
+    private val networkStatus: NetworkStatusController,
     @ApplicationScope private val scope: CoroutineScope,
 ) {
     private val outChannel = Channel<String>(Channel.BUFFERED)
@@ -52,6 +54,10 @@ class PlaybackErrorReporter @Inject constructor(
             val buffer = mutableListOf<String>()
             var debounceJob: kotlinx.coroutines.Job? = null
             playerController.playbackErrorEvents.collect { event ->
+                // A track failing to play is ambiguous (dead server vs. one bad
+                // file) — let the controller arbitrate via /healthz. No-op when
+                // already Offline; cheap otherwise.
+                networkStatus.reportFailure()
                 // Fire-and-forget the server report — repository handles
                 // success/queue branching so callers don't see throws.
                 scope.launch { repository.report(event) }

android/app/src/main/java/com/fabledsword/minstrel/player/PlayerFactory.kt

@@ -55,7 +55,7 @@ class PlayerFactory @Inject constructor(
     private val cacheConfig: CacheConfig,
     private val activeUpnpHolder: ActiveUpnpHolder,
     private val remoteState: RemotePlayerState,
-    private val serverHealth: com.fabledsword.minstrel.connectivity.ServerHealthController,
+    private val serverHealth: com.fabledsword.minstrel.connectivity.NetworkStatusController,
 ) {
     private val cacheDir: File = File(context.cacheDir, "audio_cache").apply { mkdirs() }
 

android/app/src/main/java/com/fabledsword/minstrel/player/RemotePlayerState.kt

@@ -11,11 +11,13 @@ import javax.inject.Singleton
  * Updates flow in from:
  *  - 1Hz GetPositionInfo poll -> applyPositionInfo()
  *  - Transport SOAP calls landing 200 OK -> applyTransport{Playing,Paused,Stopped}()
- *  - Error paths -> applyError() (drop fallback) or recordPollFailure()
+ *  - Poll failures -> recordPollFailure()
  *
- * The poll-failure counter implements the rolling-3 drop heuristic: 3
+ * The poll-failure counter is the sole drop arbiter: [DROP_THRESHOLD]
  * consecutive poll failures = remote considered dropped (returns true
- * from recordPollFailure for the caller to surface). Success resets it.
+ * from recordPollFailure for the caller to surface). Any success resets it.
+ * Failed transport commands no longer drop the route -- they retry and
+ * otherwise defer to this counter (see MinstrelForwardingPlayer).
  */
 @Singleton
 class RemotePlayerState @Inject constructor() {
@@ -27,6 +29,13 @@ class RemotePlayerState @Inject constructor() {
     @Volatile var lastError: Throwable? = null; private set
     @Volatile var trackNumber: Int = 0; private set
 
+    // The operator's last explicit transport intent (play=true, pause=false),
+    // distinct from the observed remote isPlaying. handleRemoteDrop resumes
+    // local playback based on THIS, not isPlaying -- so a play() that fails
+    // its SOAP (stale/dead renderer) still resumes on the phone instead of
+    // swallowing the tap. Deliberately NOT cleared by applyError.
+    @Volatile var lastPlayIntent: Boolean = false; private set
+
     // Pending-transport deadline (SystemClock.elapsedRealtime() at which we
     // give up waiting). When > 0, a user transport action (next/prev/seekTo
     // idx) is in flight: ForwardingPlayer has already moved the wrapped
@@ -63,6 +72,8 @@ class RemotePlayerState @Inject constructor() {
         positionMs = 0L
     }
 
+    fun setPlayIntent(intended: Boolean) { lastPlayIntent = intended }
+
     fun applyError(t: Throwable) {
         isPlaying = false
         lastError = t
@@ -80,6 +91,7 @@ class RemotePlayerState @Inject constructor() {
         positionMs = 0L
         durationMs = 0L
         isPlaying = false
+        lastPlayIntent = false
         currentTrackUri = ""
         lastError = null
         consecutivePollFailures = 0

android/app/src/main/java/com/fabledsword/minstrel/player/output/IdleRevertAction.kt

@@ -0,0 +1,21 @@
+package com.fabledsword.minstrel.player.output
+
+/** Action the idle-revert collector should take on a player-state change. */
+internal enum class IdleRevertAction { ARM, CANCEL, IGNORE }
+
+/**
+ * Pure decision for the UPnP idle-revert timer. [armed] is whether the
+ * idle timer Job is currently running. We ARM only on the transition INTO
+ * "engaged + not playing" (so repeated paused emissions don't reset the
+ * countdown), CANCEL whenever playback resumes or UPnP disengages, and
+ * otherwise IGNORE.
+ */
+internal fun idleRevertAction(
+    upnpEngaged: Boolean,
+    isPlaying: Boolean,
+    armed: Boolean,
+): IdleRevertAction = when {
+    upnpEngaged && !isPlaying -> if (armed) IdleRevertAction.IGNORE else IdleRevertAction.ARM
+    armed -> IdleRevertAction.CANCEL
+    else -> IdleRevertAction.IGNORE
+}

android/app/src/main/java/com/fabledsword/minstrel/player/output/OutputPickerController.kt

@@ -19,6 +19,7 @@ import com.fabledsword.minstrel.player.output.upnp.UpnpDiscoveryController
 import com.fabledsword.minstrel.player.output.upnp.bareUdn
 import dagger.hilt.android.qualifiers.ApplicationContext
 import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharingStarted
@@ -147,6 +148,12 @@ class OutputPickerController @Inject constructor(
     // can run the longest-common-prefix / common-suffix diff.
     private var lastSyncedQueueIds: List<String>? = null
 
+    // Idle-revert timer. Armed when playback is paused/stopped on a UPnP
+    // route; fires revertToPhoneOnIdle after IDLE_REVERT_MS of continuous
+    // non-playing. Cancelled on resume, route change, or explicit disconnect.
+    // See idleRevertAction for the arm/cancel decision.
+    private var idleRevertJob: Job? = null
+
     init {
         // Two-arg addCallback registers with no discovery flag —
         // androidx.mediarouter 1.7.0's default passive behavior:
@@ -155,7 +162,8 @@ class OutputPickerController @Inject constructor(
         // CALLBACK_FLAG_PASSIVE_DISCOVERY constant; absent flag = passive.)
         mediaRouter.addCallback(selector, callback)
         // When MinstrelForwardingPlayer reports the active UPnP route has
-        // dropped (3+ consecutive poll failures or a transport SOAP exception),
+        // dropped (the poll loop's consecutive-failure threshold tripping --
+        // the sole drop arbiter; a failed transport command no longer drops),
         // clear the UPnP selection state and fall back to local ExoPlayer at
         // the last-known remote position. This mirrors selectSystem's disconnect
         // path but skips the Stop SOAP since the device is already unreachable.
@@ -163,6 +171,54 @@ class OutputPickerController @Inject constructor(
             playerFactory.dropEvents.collect { handleRemoteDrop() }
         }
         scope.launch { observeQueueChangesForSonosResync() }
+        scope.launch { observeIdleRevertWhileUpnp() }
+    }
+
+    /**
+     * Arm/cancel the idle-revert timer as playback state changes while a
+     * UPnP route is engaged. "Engaged" = active OR target set, so the brief
+     * selectUpnp/resync window (active momentarily null, target set) doesn't
+     * spuriously fire. The arm/cancel choice is the pure idleRevertAction.
+     */
+    private suspend fun observeIdleRevertWhileUpnp() {
+        playerController.uiState.collect { state ->
+            val engaged = activeUpnpHolder.active.value != null ||
+                activeUpnpHolder.target.value != null
+            val armed = idleRevertJob?.isActive == true
+            when (idleRevertAction(engaged, state.isPlaying, armed)) {
+                IdleRevertAction.ARM ->
+                    idleRevertJob = scope.launch {
+                        delay(IDLE_REVERT_MS)
+                        revertToPhoneOnIdle()
+                    }
+                IdleRevertAction.CANCEL -> {
+                    idleRevertJob?.cancel()
+                    idleRevertJob = null
+                }
+                IdleRevertAction.IGNORE -> Unit
+            }
+        }
+    }
+
+    /**
+     * Timer fired: the operator paused on a UPnP route and never resumed.
+     * Stop the renderer (best-effort -- it's reachable, unlike a drop),
+     * clear the UPnP overlay so routesState falls back to the phone, and
+     * seek local ExoPlayer to the last remote position. No play(): the
+     * operator was paused, so we revert routing silently. Guarded by the
+     * selectUpnpMutex so it can't race selectUpnp/resync.
+     */
+    private suspend fun revertToPhoneOnIdle() = selectUpnpMutex.withLock {
+        if (remoteState.isPlaying) return@withLock // resumed at the boundary
+        val active = activeUpnpHolder.active.value
+        val capturedPositionMs = remoteState.positionMs
+        runCatching { active?.avTransport?.stop() }
+            .onFailure { Timber.w(it, "UPnP Stop failed during idle revert") }
+        activeUpnpHolder.set(null)
+        activeUpnpHolder.setTarget(null)
+        selectedUpnpRouteIdInternal.value = null
+        idleRevertJob = null
+        playerController.seekTo(capturedPositionMs)
     }
 
     /**
@@ -365,16 +421,19 @@ class OutputPickerController @Inject constructor(
     }
 
     /**
-     * Called when the active UPnP route drops unexpectedly (poll-failure
-     * threshold or SOAP exception). Captures the last remote position +
-     * play state, clears UPnP selection, and resumes local ExoPlayer at
+     * Called when the active UPnP route drops unexpectedly (the poll loop's
+     * consecutive-failure threshold tripping). Captures the last remote
+     * position + play state, clears UPnP selection, and resumes local ExoPlayer at
      * the same point. Skips the Stop SOAP (device already unreachable).
      * The snackbar is handled independently by the NowPlaying surface
      * collecting the same [PlayerFactory.dropEvents] via PlayerController.
      */
     private fun handleRemoteDrop() {
         val capturedPositionMs = remoteState.positionMs
-        val wasPlayingRemote = remoteState.isPlaying
+        // Resume on the operator's last play-intent, not the observed remote
+        // state: after a pause, isPlaying is false, but a failed play() that
+        // triggered this drop means the operator DID ask to play -- honor it.
+        val wasPlayingRemote = remoteState.lastPlayIntent
         activeUpnpHolder.set(null)
         activeUpnpHolder.setTarget(null)
         selectedUpnpRouteIdInternal.value = null
@@ -497,6 +556,9 @@ class OutputPickerController @Inject constructor(
                     rendering = rendering,
                 ),
             )
+            // Selecting a route loads the queue and Plays on the renderer, so
+            // the standing intent is "play" -- a later drop should resume local.
+            remoteState.setPlayIntent(true)
         }.onFailure { e ->
             Timber.w(e, "UPnP select failed for route ${effectiveRoute.id}")
             activeUpnpHolder.set(null)
@@ -640,5 +702,10 @@ class OutputPickerController @Inject constructor(
     private companion object {
         const val EXTEND_ABORT_AFTER_FAILURES = 3
         const val EXTEND_THROTTLE_MS = 50L
+
+        // 5 minutes of continuous non-playing on a UPnP route before we
+        // revert to the phone speaker, so a stale Sonos selection can't make
+        // a later "tap play" do nothing.
+        const val IDLE_REVERT_MS = 5 * 60 * 1000L
     }
 }

android/app/src/main/java/com/fabledsword/minstrel/player/output/upnp/UpnpDiscoveryController.kt

@@ -17,6 +17,7 @@ import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
 import okhttp3.OkHttpClient
 import okhttp3.Request
 import timber.log.Timber
+import java.util.concurrent.TimeUnit
 import javax.inject.Inject
 import javax.inject.Singleton
 
@@ -45,6 +46,15 @@ class UpnpDiscoveryController @Inject constructor(
 ) {
     private val ssdp = SsdpDiscovery(context)
 
+    // Transport commands (play/pause/seek/next) and the 1 Hz poll go through
+    // this client. A dead renderer should fail fast so OutputPickerController's
+    // drop-recovery reverts to the phone in ~2 s instead of the shared client's
+    // 10 s connect timeout. Derived via newBuilder() so the connection pool +
+    // dispatcher stay shared with the app client.
+    private val controlHttp: OkHttpClient = okHttp.newBuilder()
+        .connectTimeout(CONTROL_CONNECT_TIMEOUT_SECONDS, TimeUnit.SECONDS)
+        .build()
+
     private val routesInternal = MutableStateFlow<List<UpnpRoute>>(emptyList())
     val routes: StateFlow<List<UpnpRoute>> = routesInternal.asStateFlow()
 
@@ -91,7 +101,7 @@ class UpnpDiscoveryController @Inject constructor(
     fun transportFor(routeId: String): AVTransportClient? {
         val route = routesInternal.value.firstOrNull { it.id == routeId } ?: return null
         return AVTransportClient(
-            loggingSoapClient(okHttp, route.name),
+            loggingSoapClient(controlHttp, route.name),
             route.avTransportControlUrl,
         )
     }
@@ -225,6 +235,11 @@ class UpnpDiscoveryController @Inject constructor(
         // devices append. Anchored to end-of-string so it never eats
         // a legitimate parenthetical inside a name.
         val IP_SUFFIX_REGEX = Regex("""\s*\(\d+\.\d+\.\d+\.\d+\)$""")
+
+        // Aggressive connect timeout for transport SOAP so a dead renderer
+        // trips the drop-recovery quickly. Conservative enough not to false-drop
+        // a slow-but-alive LAN; read timeout still inherits the shared client.
+        const val CONTROL_CONNECT_TIMEOUT_SECONDS = 2L
     }
 }
 

android/app/src/main/java/com/fabledsword/minstrel/playlists/data/PlaylistsRepository.kt

@@ -7,6 +7,7 @@ import retrofit2.HttpException
 import java.net.HttpURLConnection
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistTrackDao
+import com.fabledsword.minstrel.cache.db.dao.PlaylistCachedCount
 import com.fabledsword.minstrel.cache.db.entities.CachedPlaylistEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedPlaylistTrackEntity
 import com.fabledsword.minstrel.cache.mutations.MutationQueue
@@ -18,6 +19,7 @@ import com.fabledsword.minstrel.models.wire.PlaylistTrackWire
 import com.fabledsword.minstrel.models.wire.PlaylistWire
 import com.fabledsword.minstrel.shared.resolveServerUrl
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.map
 import retrofit2.Retrofit
 import retrofit2.create
@@ -51,9 +53,16 @@ class PlaylistsRepository @Inject constructor(
 
     // ── Reads (Flow, cache-first; the cache is the source of truth) ──
 
-    /** Owned + public; UI splits by isSystem / userId comparison. */
+    /**
+     * Owned + public; UI splits by isSystem / userId comparison. Joined with
+     * per-playlist cache counts so [PlaylistRef.fullyCached] drives the offline
+     * greying without each consumer re-querying the cache index.
+     */
     fun observeAll(): Flow<List<PlaylistRef>> =
-        playlistDao.observeAll().map { rows -> rows.map { it.toDomain() } }
+        combine(
+            playlistDao.observeAll(),
+            playlistDao.observeCachedCounts(),
+        ) { rows, counts -> mergePlaylistsWithCache(rows, counts) }
 
     /** User-owned playlists only (systemVariant IS NULL). */
     fun observeUserPlaylists(): Flow<List<PlaylistRef>> =
@@ -233,6 +242,23 @@ fun List<PlaylistTrackRef>.toPlayableTrackRefs(): List<TrackRef> =
 
 // ── Mappers (internal — keep Room + wire types out of the UI layer) ──
 
+/**
+ * Maps cached playlist rows to domain refs, stamping [PlaylistRef.fullyCached]
+ * from the cache-index counts. A playlist is fully cached when it has tracks
+ * and every member track is resident (`cachedCount >= trackCount`). Pulled out
+ * of the Flow so the predicate is unit-testable without a Room database.
+ */
+internal fun mergePlaylistsWithCache(
+    rows: List<CachedPlaylistEntity>,
+    counts: List<PlaylistCachedCount>,
+): List<PlaylistRef> {
+    val cachedById = counts.associate { it.playlistId to it.cachedCount }
+    return rows.map { row ->
+        val cached = cachedById[row.id] ?: 0
+        row.toDomain().copy(fullyCached = row.trackCount > 0 && cached >= row.trackCount)
+    }
+}
+
 private fun CachedPlaylistEntity.toDomain(): PlaylistRef =
     PlaylistRef(
         id = id,

android/app/src/main/java/com/fabledsword/minstrel/playlists/ui/PlaylistsListScreen.kt

@@ -27,7 +27,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.NavHostController
-import com.fabledsword.minstrel.connectivity.ConnectivityObserver
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.PlaylistRef
 import com.fabledsword.minstrel.nav.PlaylistDetail
@@ -66,7 +67,7 @@ class PlaylistsListViewModel @Inject constructor(
     private val repository: PlaylistsRepository,
     private val player: PlayerController,
     private val eventsStream: EventsStream,
-    connectivity: ConnectivityObserver,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val poolMessages = Channel<String>(Channel.BUFFERED)
@@ -74,9 +75,9 @@ class PlaylistsListViewModel @Inject constructor(
     /** Transient snackbar messages from playlist tile play taps. */
     val transientMessages: Flow<String> = poolMessages.receiveAsFlow()
 
-    /** True when the device has no usable internet -- gates refreshable system tiles. */
-    val offline: StateFlow<Boolean> = connectivity.online
-        .map { !it }
+    /** Cache-only: no link OR server unreachable (Unstable stays calm). Greys tiles. */
+    val offline: StateFlow<Boolean> = networkStatus.state
+        .map { it == ServerHealth.Offline || it == ServerHealth.ServerDown }
         .stateIn(
             scope = viewModelScope,
             started = SharingStarted.WhileSubscribed(SHARE_STOP_TIMEOUT_MS),
@@ -191,14 +192,15 @@ private fun PlaylistsGrid(
                 SectionHeader("System playlists")
             }
             items(items = systemPlaylists, key = { it.id }) { playlist ->
+                // Greyed offline when it needs the live server or isn't fully
+                // cached — dimmed but still tappable into the detail.
+                val greyed = offline && playlist.unavailableOffline
                 PlaylistCard(
                     playlist = playlist,
                     onClick = { onPlaylistClick(playlist.id) },
                     onPlay = { onPlay(playlist) },
-                    // Refreshable system tiles need server endpoints (systemShuffle);
-                    // disable when offline. Empty mixes show a snackbar after tap.
-                    playEnabled = playlist.trackCount > 0 &&
-                        !(offline && playlist.refreshable),
+                    playEnabled = playlist.trackCount > 0 && !greyed,
+                    greyed = greyed,
                 )
             }
         }
@@ -207,11 +209,13 @@ private fun PlaylistsGrid(
                 SectionHeader("Your playlists")
             }
             items(items = userPlaylists, key = { it.id }) { playlist ->
+                val greyed = offline && playlist.unavailableOffline
                 PlaylistCard(
                     playlist = playlist,
                     onClick = { onPlaylistClick(playlist.id) },
                     onPlay = { onPlay(playlist) },
-                    playEnabled = playlist.trackCount > 0,
+                    playEnabled = playlist.trackCount > 0 && !greyed,
+                    greyed = greyed,
                 )
             }
         }

android/app/src/main/java/com/fabledsword/minstrel/playlists/widgets/PlaylistCard.kt

@@ -15,6 +15,7 @@ import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.alpha
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
@@ -40,6 +41,10 @@ import com.fabledsword.minstrel.theme.FabledSwordFlatTokens
  * [playEnabled] disables the overlay (50% alpha + ignore taps) — Home
  * uses it for system playlists in offline mode (their server-side
  * shuffle endpoint is unreachable) and for empty playlists.
+ *
+ * [greyed] dims the whole tile (it can't be reliably played offline) while
+ * keeping it tappable — the detail screen is the escape hatch for shuffling
+ * whatever subset is cached. Greyed always disables the play overlay too.
  */
 @Composable
 fun PlaylistCard(
@@ -48,11 +53,13 @@ fun PlaylistCard(
     modifier: Modifier = Modifier,
     onPlay: (suspend () -> Unit)? = null,
     playEnabled: Boolean = true,
+    greyed: Boolean = false,
 ) {
     val seedCache = LocalDetailSeedCache.current
     Surface(
         modifier = modifier
             .width(176.dp)
+            .alpha(if (greyed) GREYED_ALPHA else 1f) // dimmed, still clickable
             .clickable {
                 seedCache.stashPlaylist(playlist)
                 onClick()
@@ -63,7 +70,7 @@ fun PlaylistCard(
             PlaylistCardCover(
                 playlist = playlist,
                 onPlay = onPlay,
-                playEnabled = playEnabled,
+                playEnabled = playEnabled && !greyed,
             )
             Spacer(Modifier.height(8.dp))
             Text(
@@ -148,6 +155,7 @@ private fun VariantPill(label: String, modifier: Modifier = Modifier) {
 }
 
 private const val PILL_BG_ALPHA = 0.85f
+private const val GREYED_ALPHA = 0.45f
 
 private fun subtitleFor(playlist: PlaylistRef): String = when {
     playlist.trackCount > 0 -> "${playlist.trackCount} tracks"

android/app/src/main/java/com/fabledsword/minstrel/requests/ui/RequestsViewModel.kt

@@ -5,11 +5,13 @@ import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.RequestRef
+import com.fabledsword.minstrel.models.RequestStatus
 import com.fabledsword.minstrel.requests.data.CancelOutcome
 import com.fabledsword.minstrel.requests.data.RequestsRepository
 import com.fabledsword.minstrel.shared.UiState
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
@@ -20,6 +22,10 @@ import javax.inject.Inject
 
 private val RELEVANT_EVENT_KINDS = setOf("request.status_changed")
 
+// Cadence for in-flight request polling — matches the web client (#369):
+// fast enough to feel live, slow enough not to hammer the server.
+private const val POLL_INTERVAL_MS = 12_000L
+
 @HiltViewModel
 class RequestsViewModel @Inject constructor(
     private val repository: RequestsRepository,
@@ -31,11 +37,14 @@ class RequestsViewModel @Inject constructor(
 
     init {
         refresh()
+        // SSE push: reconciler completions arrive here; reload silently so the
+        // row updates in place rather than flashing the loading spinner.
         viewModelScope.launch {
             eventsStream.events
                 .filter { it.kind in RELEVANT_EVENT_KINDS }
-                .collect { refresh() }
+                .collect { silentReload() }
         }
+        viewModelScope.launch { pollWhileInFlight() }
     }
 
     fun refresh(): Job = viewModelScope.launch {
@@ -54,6 +63,43 @@ class RequestsViewModel @Inject constructor(
         }
     }
 
+    /**
+     * Auto-poll while any request is mid-ingest (status APPROVED), matching the
+     * web client (#369). Reloads silently every [POLL_INTERVAL_MS] and pauses
+     * when nothing is in-flight — complements the SSE push so progress stays
+     * live even if the event stream drops.
+     */
+    private suspend fun pollWhileInFlight() {
+        while (true) {
+            if (hasInFlightRequest()) {
+                silentReload()
+            }
+            delay(POLL_INTERVAL_MS)
+        }
+    }
+
+    private fun hasInFlightRequest(): Boolean {
+        val state = internal.value
+        return state is UiState.Success &&
+            state.data.any { it.status == RequestStatus.APPROVED }
+    }
+
+    /**
+     * Reload the list in place without flipping to Loading — used by the poll
+     * loop and the SSE collector so visible rows update without a spinner
+     * flash. A transient failure keeps the current view; the next reload wins.
+     */
+    private suspend fun silentReload() {
+        try {
+            val rows = repository.listMine()
+            internal.value = if (rows.isEmpty()) UiState.Empty else UiState.Success(rows)
+        } catch (
+            @Suppress("TooGenericExceptionCaught", "SwallowedException") e: Throwable,
+        ) {
+            // Keep the current view; the next poll / SSE / pull reconciles.
+        }
+    }
+
     /**
      * Optimistically removes [id] from the success list so the row
      * disappears immediately; on server-side success the row is

android/app/src/main/java/com/fabledsword/minstrel/search/data/SearchRepository.kt

@@ -4,8 +4,8 @@ import com.fabledsword.minstrel.api.endpoints.SearchApi
 import com.fabledsword.minstrel.cache.db.dao.CachedAlbumDao
 import com.fabledsword.minstrel.cache.db.dao.CachedArtistDao
 import com.fabledsword.minstrel.cache.db.dao.CachedTrackDao
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.connectivity.ServerHealth
-import com.fabledsword.minstrel.connectivity.ServerHealthController
 import com.fabledsword.minstrel.library.data.toDomain
 import com.fabledsword.minstrel.models.SearchResponseRef
 import retrofit2.Retrofit
@@ -16,8 +16,8 @@ import javax.inject.Singleton
 private const val LOCAL_SEARCH_LIMIT = 20
 
 /**
- * Cache-first when offline. When [ServerHealthController] is Healthy the
- * repository hits `/api/search` and returns the server's three-facet
+ * Cache-first when offline. When [NetworkStatusController] reports Healthy or
+ * Unstable the repository hits `/api/search` and returns the server's three-facet
  * paged response. When health is Offline or ServerDown it falls back to
  * Room LIKE queries against `cached_*` so the user can still find
  * something to play from what's already on the device; the outcome's
@@ -27,7 +27,7 @@ private const val LOCAL_SEARCH_LIMIT = 20
 @Singleton
 class SearchRepository @Inject constructor(
     retrofit: Retrofit,
-    private val serverHealth: ServerHealthController,
+    private val serverHealth: NetworkStatusController,
     private val trackDao: CachedTrackDao,
     private val albumDao: CachedAlbumDao,
     private val artistDao: CachedArtistDao,
@@ -35,7 +35,8 @@ class SearchRepository @Inject constructor(
     private val api: SearchApi = retrofit.create()
 
     suspend fun search(query: String): SearchOutcome = when (serverHealth.state.value) {
-        ServerHealth.Healthy -> SearchOutcome(remoteSearch(query), localOnly = false)
+        ServerHealth.Healthy, ServerHealth.Unstable ->
+            SearchOutcome(remoteSearch(query), localOnly = false)
         ServerHealth.Offline, ServerHealth.ServerDown ->
             SearchOutcome(localSearch(query), localOnly = true)
     }

android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/PullRefreshNetworkViewModel.kt

@@ -0,0 +1,21 @@
+package com.fabledsword.minstrel.shared.widgets
+
+import androidx.lifecycle.SavedStateHandle
+import androidx.lifecycle.ViewModel
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import dagger.hilt.android.lifecycle.HiltViewModel
+import javax.inject.Inject
+
+/**
+ * Routes a deliberate pull-to-refresh into a /healthz recheck so the connection
+ * banner clears within seconds rather than waiting for the next poll — even on
+ * cache-only screens whose own refresh never touches the network. Backs
+ * [PullToRefreshScaffold].
+ */
+@HiltViewModel
+class PullRefreshNetworkViewModel @Inject constructor(
+    private val networkStatus: NetworkStatusController,
+    @Suppress("UnusedPrivateProperty") savedStateHandle: SavedStateHandle,
+) : ViewModel() {
+    fun recheck() = networkStatus.recheck()
+}

android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/PullToRefreshScaffold.kt

@@ -10,12 +10,15 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
+import androidx.hilt.navigation.compose.hiltViewModel
 import kotlinx.coroutines.launch
 
 /**
  * Wraps [content] in a Material3 PullToRefreshBox so the user can
  * swipe-down to trigger [onRefresh]. The wrapper manages the
- * `isRefreshing` indicator while [onRefresh] is in flight.
+ * `isRefreshing` indicator while [onRefresh] is in flight. Every pull also
+ * fires a /healthz recheck (via [PullRefreshNetworkViewModel]) so a stale
+ * connection banner clears promptly on a deliberate user refresh.
  *
  * [onRefresh] is suspend: pass `{ viewModel.refresh().join() }` so the
  * indicator hides exactly when the underlying coroutine completes,
@@ -32,6 +35,7 @@ import kotlinx.coroutines.launch
 fun PullToRefreshScaffold(
     onRefresh: suspend () -> Unit,
     modifier: Modifier = Modifier,
+    netVm: PullRefreshNetworkViewModel = hiltViewModel(),
     content: @Composable () -> Unit,
 ) {
     var isRefreshing by remember { mutableStateOf(false) }
@@ -42,6 +46,7 @@ fun PullToRefreshScaffold(
             scope.launch {
                 isRefreshing = true
                 try {
+                    netVm.recheck() // deliberate pull → re-probe the server now
                     onRefresh()
                 } finally {
                     isRefreshing = false

android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/TrackRow.kt

@@ -61,8 +61,11 @@ fun TrackRow(
     trailing: @Composable RowScope.() -> Unit = {},
 ) {
     val context = LocalContext.current
-    val offlineUnavailable = LocalServerHealth.current != ServerHealth.Healthy &&
-        trackId !in LocalCachedTrackIds.current
+    val health = LocalServerHealth.current
+    // Unstable is non-gating — only a real gating state dims uncached rows.
+    val offlineUnavailable =
+        (health == ServerHealth.Offline || health == ServerHealth.ServerDown) &&
+            trackId !in LocalCachedTrackIds.current
     val titleColor = if (nowPlaying) {
         MaterialTheme.colorScheme.primary
     } else {

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

@@ -7,8 +7,8 @@ import retrofit2.http.GET
 /**
  * Retrofit interface for `GET /healthz` — unauthenticated health probe
  * returning the server's running version + the minimum client version
- * it'll talk to. Used by [com.fabledsword.minstrel.update.data.VersionCheckController]
- * to surface the VersionTooOld banner.
+ * it'll talk to. Polled by [com.fabledsword.minstrel.connectivity.NetworkStatusController]
+ * for both reachability and the VersionTooOld banner.
  */
 interface HealthzApi {
     @GET("healthz")

android/app/src/main/java/com/fabledsword/minstrel/update/data/VersionCheckController.kt

@@ -1,112 +0,0 @@
-package com.fabledsword.minstrel.update.data
-
-import com.fabledsword.minstrel.BuildConfig
-import com.fabledsword.minstrel.di.ApplicationScope
-import com.fabledsword.minstrel.update.api.HealthzApi
-import kotlinx.coroutines.CoroutineScope
-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 javax.inject.Inject
-import javax.inject.Singleton
-
-private const val POLL_INTERVAL_MS = 5 * 60 * 1000L
-
-// Hysteresis on the reachable signal. Flipping internalReachable to false on
-// the very first /healthz failure produced two false positives:
-//   1. App startup — AuthStore.baseUrl loads from Room asynchronously, so the
-//      first runOnce() can fire against AuthStore.DEFAULT_BASE_URL
-//      ("http://localhost:8080") before the real server URL has hydrated.
-//   2. Deployments whose reverse proxy routes only /api/* to the Go server —
-//      /healthz never reaches the handler, so the user sees a permanent
-//      "Server unreachable" banner even though all real /api/* calls succeed.
-// Requiring 3 consecutive failures (~15 min at the 5-min poll cadence) ensures
-// the banner only fires on sustained, real unreachability — and a single
-// success at any point resets the counter so transient hiccups self-clear.
-private const val REACHABILITY_FAILURE_THRESHOLD = 3
-
-/**
- * Result of the most recent /healthz version-compatibility check.
- * `Skipped` means the server didn't include `min_client_version`
- * (partial deploy or older server) and the UI should not gate.
- */
-enum class VersionResult { OK, TOO_OLD, SKIPPED }
-
-/**
- * Polls /healthz periodically and exposes the current
- * [VersionResult] for the shell's VersionTooOld banner. Soft-fails
- * on network errors — keeps the last-known result rather than
- * showing a misleading "too old" on a connectivity blip.
- *
- * Constructed at app launch via the construct-the-singleton trick
- * in [com.fabledsword.minstrel.MinstrelApplication].
- */
-@Singleton
-class VersionCheckController @Inject constructor(
-    @ApplicationScope private val scope: CoroutineScope,
-    retrofit: Retrofit,
-) {
-    private val api: HealthzApi = retrofit.create(HealthzApi::class.java)
-
-    private val internal = MutableStateFlow(VersionResult.SKIPPED)
-    val result: StateFlow<VersionResult> = internal.asStateFlow()
-
-    // Whether the most recent /healthz poll reached the server. Separate from
-    // VersionResult because "unreachable" and "version mismatch" drive
-    // different UX (offline banner vs version-too-old banner). Optimistic
-    // initial value -- the first poll fires within seconds of app launch and
-    // we don't want a "server down" flash before we've actually tried.
-    // Consumed by ServerHealthController to compose with ConnectivityObserver
-    // for the tri-state offline / server-down / healthy signal.
-    private val internalReachable = MutableStateFlow(true)
-    val reachable: StateFlow<Boolean> = internalReachable.asStateFlow()
-
-    private var consecutiveFailures = 0
-
-    init {
-        scope.launch {
-            while (true) {
-                runOnce()
-                delay(POLL_INTERVAL_MS)
-            }
-        }
-    }
-
-    /** One-shot recheck, bypassing the poll cadence. Used by the banner's "Check now" button. */
-    fun recheck() {
-        scope.launch { runOnce() }
-    }
-
-    private suspend fun runOnce() {
-        val outcome = runCatching { api.check() }
-        val response = outcome.getOrNull()
-        if (response == null) {
-            consecutiveFailures++
-            if (consecutiveFailures >= REACHABILITY_FAILURE_THRESHOLD &&
-                internalReachable.value
-            ) {
-                Timber.w(
-                    "/healthz unreachable for %d consecutive polls — flipping reachable=false",
-                    consecutiveFailures,
-                )
-                internalReachable.value = false
-            }
-            return
-        }
-        if (!internalReachable.value) {
-            Timber.i("/healthz recovered after %d failures", consecutiveFailures)
-        }
-        consecutiveFailures = 0
-        internalReachable.value = true
-        val min = response.minClientVersion
-        internal.value = when {
-            min.isEmpty() -> VersionResult.SKIPPED
-            isVersionNewer(min, BuildConfig.VERSION_NAME) -> VersionResult.TOO_OLD
-            else -> VersionResult.OK
-        }
-    }
-}

android/app/src/main/java/com/fabledsword/minstrel/update/data/VersionResult.kt

@@ -0,0 +1,8 @@
+package com.fabledsword.minstrel.update.data
+
+/**
+ * Result of the most recent /healthz version-compatibility check.
+ * `SKIPPED` means the server didn't include `min_client_version`
+ * (partial deploy or older server) and the UI should not gate.
+ */
+enum class VersionResult { OK, TOO_OLD, SKIPPED }

android/app/src/main/java/com/fabledsword/minstrel/update/ui/VersionTooOldViewModel.kt

@@ -2,21 +2,21 @@ package com.fabledsword.minstrel.update.ui
 
 import androidx.lifecycle.SavedStateHandle
 import androidx.lifecycle.ViewModel
-import com.fabledsword.minstrel.update.data.VersionCheckController
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.update.data.VersionResult
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.flow.StateFlow
 import javax.inject.Inject
 
 /**
- * Tiny VM that exposes the [VersionCheckController]'s current
+ * Tiny VM that exposes the [NetworkStatusController]'s current
  * [VersionResult] plus its recheck trigger for the banner button.
  */
 @HiltViewModel
 class VersionTooOldViewModel @Inject constructor(
-    private val controller: VersionCheckController,
+    private val controller: NetworkStatusController,
     @Suppress("UnusedPrivateProperty") savedStateHandle: SavedStateHandle,
 ) : ViewModel() {
-    val result: StateFlow<VersionResult> = controller.result
+    val result: StateFlow<VersionResult> = controller.versionResult
     fun recheck() = controller.recheck()
 }

android/app/src/test/java/com/fabledsword/minstrel/connectivity/ReachabilityMachineTest.kt

@@ -0,0 +1,116 @@
+package com.fabledsword.minstrel.connectivity
+
+import org.junit.jupiter.api.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class ReachabilityMachineTest {
+
+    private fun machine() = ReachabilityMachine()
+
+    @Test
+    fun `starts healthy`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        assertEquals(ServerHealth.Healthy, m.health())
+    }
+
+    @Test
+    fun `no link is offline regardless of probes`() {
+        val m = machine()
+        m.onLinkChange(up = false)
+        m.onProbeFailure(nowMs = 1)
+        assertEquals(ServerHealth.Offline, m.health())
+    }
+
+    @Test
+    fun `single probe failure is unstable not down`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        m.onProbeFailure(nowMs = 1_000)
+        assertEquals(ServerHealth.Unstable, m.health())
+    }
+
+    @Test
+    fun `probe success from unstable recovers to healthy`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        m.onProbeFailure(nowMs = 1_000)
+        m.onSuccess()
+        assertEquals(ServerHealth.Healthy, m.health())
+    }
+
+    @Test
+    fun `op success from unstable recovers to healthy`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        m.onProbeFailure(nowMs = 1_000)
+        m.onSuccess() // a successful stream read / API 2xx is self-proving
+        assertEquals(ServerHealth.Healthy, m.health())
+    }
+
+    @Test
+    fun `two op failures plus a failed probe escalate immediately`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        m.onOpFailure(nowMs = 1_000)
+        m.onOpFailure(nowMs = 1_500) // corroboration reached
+        m.onProbeFailure(nowMs = 2_000) // probe agrees → fast ServerDown
+        assertEquals(ServerHealth.ServerDown, m.health())
+    }
+
+    @Test
+    fun `op failures with a successful probe stay healthy (track-specific)`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        m.onOpFailure(nowMs = 1_000)
+        m.onOpFailure(nowMs = 1_500)
+        m.onSuccess() // arbiter says server is fine
+        assertEquals(ServerHealth.Healthy, m.health())
+    }
+
+    @Test
+    fun `stale op failures do not corroborate`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        m.onOpFailure(nowMs = 0)
+        m.onOpFailure(nowMs = 1_000)
+        // both op failures are now older than the corroboration window:
+        m.onProbeFailure(nowMs = 1_000 + CORROBORATION_WINDOW_MS + 1)
+        assertEquals(ServerHealth.Unstable, m.health()) // not enough fresh corroboration
+    }
+
+    @Test
+    fun `sustained failure backstop escalates after the window`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        m.onProbeFailure(nowMs = 1_000) // unstable, streak starts
+        m.onProbeFailure(nowMs = 1_000 + ESCALATE_AFTER_MS) // sustained ≥ backstop
+        assertEquals(ServerHealth.ServerDown, m.health())
+    }
+
+    @Test
+    fun `link restored keeps last-known down until a fresh result`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        m.onProbeFailure(nowMs = 1_000)
+        m.onProbeFailure(nowMs = 1_000 + ESCALATE_AFTER_MS) // ServerDown
+        m.onLinkChange(up = false)
+        assertEquals(ServerHealth.Offline, m.health())
+        m.onLinkChange(up = true)
+        // link back but no fresh probe result yet — last known reachability was down:
+        assertEquals(ServerHealth.ServerDown, m.health())
+        m.onSuccess()
+        assertEquals(ServerHealth.Healthy, m.health())
+    }
+
+    @Test
+    fun `unstable does not gate — it is not offline or serverdown`() {
+        val m = machine()
+        m.onLinkChange(up = true)
+        m.onProbeFailure(nowMs = 1_000)
+        val health = m.health()
+        assertTrue(health != ServerHealth.Offline && health != ServerHealth.ServerDown)
+        assertEquals(ServerHealth.Unstable, health)
+    }
+}

android/app/src/test/java/com/fabledsword/minstrel/home/ui/BuildPlaylistsRowTest.kt

@@ -0,0 +1,59 @@
+package com.fabledsword.minstrel.home.ui
+
+import com.fabledsword.minstrel.models.PlaylistRef
+import com.fabledsword.minstrel.models.SystemPlaylistsStatus
+import org.junit.jupiter.api.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class BuildPlaylistsRowTest {
+
+    private fun user(id: String, cached: Boolean) =
+        PlaylistRef(id = id, userId = "u", name = id, trackCount = 1, fullyCached = cached)
+
+    @Test
+    fun `offline row leads with pools then available before greyed`() {
+        val owned = listOf(user("partial", cached = false), user("full", cached = true))
+        val row = buildPlaylistsRow(owned, SystemPlaylistsStatus(), offline = true)
+
+        assertTrue(row[0] is PlaylistRowItem.OfflinePool)
+        assertTrue(row[1] is PlaylistRowItem.OfflinePool)
+        // Fully-cached "full" comes before the greyed "partial".
+        val reals = row.filterIsInstance<PlaylistRowItem.Real>().map { it.playlist.id }
+        assertEquals(listOf("full", "partial"), reals)
+    }
+
+    @Test
+    fun `offline greys a refreshable system playlist even when fully cached`() {
+        val forYou = PlaylistRef(
+            id = "fy",
+            userId = "u",
+            name = "For You",
+            systemVariant = "for_you",
+            trackCount = 1,
+            fullyCached = true,
+        )
+        val row = buildPlaylistsRow(
+            listOf(forYou, user("u1", cached = true)),
+            SystemPlaylistsStatus(),
+            offline = true,
+        )
+        // The fully-cached user playlist is available; the refreshable system
+        // mix needs the server, so it greys out and sorts after.
+        val reals = row.filterIsInstance<PlaylistRowItem.Real>().map { it.playlist.id }
+        assertEquals(listOf("u1", "fy"), reals)
+    }
+
+    @Test
+    fun `offline row drops building-pending placeholders`() {
+        val row = buildPlaylistsRow(emptyList(), SystemPlaylistsStatus(), offline = true)
+        assertTrue(row.none { it is PlaylistRowItem.Placeholder })
+    }
+
+    @Test
+    fun `online row has no offline pools and keeps system-slot placeholders`() {
+        val row = buildPlaylistsRow(emptyList(), SystemPlaylistsStatus(), offline = false)
+        assertTrue(row.none { it is PlaylistRowItem.OfflinePool })
+        assertTrue(row.any { it is PlaylistRowItem.Placeholder })
+    }
+}

android/app/src/test/java/com/fabledsword/minstrel/player/RemotePlayerStateTest.kt

@@ -69,6 +69,32 @@ class RemotePlayerStateTest {
         assertFalse(state.recordPollFailure())
     }
 
+    @Test
+    fun `play intent survives a SOAP error so a failed play can resume locally`() {
+        val state = RemotePlayerState()
+        state.setPlayIntent(true)
+        state.applyError(RuntimeException("connect timeout"))
+        // isPlaying is cleared by the error, but the operator's intent persists.
+        assertFalse(state.isPlaying)
+        assertTrue(state.lastPlayIntent)
+    }
+
+    @Test
+    fun `pausing clears play intent`() {
+        val state = RemotePlayerState()
+        state.setPlayIntent(true)
+        state.setPlayIntent(false)
+        assertFalse(state.lastPlayIntent)
+    }
+
+    @Test
+    fun `reset clears play intent`() {
+        val state = RemotePlayerState()
+        state.setPlayIntent(true)
+        state.reset()
+        assertFalse(state.lastPlayIntent)
+    }
+
     private companion object {
         const val DROP_THRESHOLD = 30
     }

android/app/src/test/java/com/fabledsword/minstrel/player/RetryTransientIoTest.kt

@@ -0,0 +1,65 @@
+package com.fabledsword.minstrel.player
+
+import com.fabledsword.minstrel.player.output.upnp.SoapFaultException
+import kotlinx.coroutines.test.runTest
+import org.junit.jupiter.api.Test
+import java.io.IOException
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+
+/**
+ * Locks in the transport-command retry semantics behind the locked-phone
+ * Sonos drop fix: a transient IO stall (WiFi power-save) must be retried, a
+ * SOAP fault from a responding renderer must NOT be retried, and an
+ * exhausted retry must rethrow rather than loop forever. Without this, a
+ * single failed command falsely reverted Sonos playback to the phone.
+ */
+class RetryTransientIoTest {
+
+    @Test
+    fun `returns immediately on first success`() = runTest {
+        var calls = 0
+        val result = retryTransientIo(attempts = 3, backoffMs = 0L) {
+            calls += 1
+            "ok"
+        }
+        assertEquals("ok", result)
+        assertEquals(1, calls)
+    }
+
+    @Test
+    fun `retries transient IO failure then succeeds`() = runTest {
+        var calls = 0
+        val result = retryTransientIo(attempts = 3, backoffMs = 0L) {
+            calls += 1
+            if (calls < 2) throw IOException("connect timeout")
+            "ok"
+        }
+        assertEquals("ok", result)
+        assertEquals(2, calls)
+    }
+
+    @Test
+    fun `rethrows IO failure after exhausting attempts`() = runTest {
+        var calls = 0
+        assertFailsWith<IOException> {
+            retryTransientIo(attempts = 3, backoffMs = 0L) {
+                calls += 1
+                throw IOException("still asleep")
+            }
+        }
+        assertEquals(3, calls)
+    }
+
+    @Test
+    fun `does not retry a SOAP fault from a responding renderer`() = runTest {
+        var calls = 0
+        assertFailsWith<SoapFaultException> {
+            retryTransientIo(attempts = 3, backoffMs = 0L) {
+                calls += 1
+                throw SoapFaultException("718", "Invalid InstanceID")
+            }
+        }
+        assertEquals(1, calls)
+    }
+}

android/app/src/test/java/com/fabledsword/minstrel/player/output/IdleRevertDecisionTest.kt

@@ -0,0 +1,55 @@
+package com.fabledsword.minstrel.player.output
+
+import org.junit.jupiter.api.Test
+import kotlin.test.assertEquals
+
+class IdleRevertDecisionTest {
+
+    @Test
+    fun `engaged and paused and not armed arms the timer`() {
+        assertEquals(
+            IdleRevertAction.ARM,
+            idleRevertAction(upnpEngaged = true, isPlaying = false, armed = false),
+        )
+    }
+
+    @Test
+    fun `engaged and paused and already armed is ignored`() {
+        assertEquals(
+            IdleRevertAction.IGNORE,
+            idleRevertAction(upnpEngaged = true, isPlaying = false, armed = true),
+        )
+    }
+
+    @Test
+    fun `resuming playback cancels an armed timer`() {
+        assertEquals(
+            IdleRevertAction.CANCEL,
+            idleRevertAction(upnpEngaged = true, isPlaying = true, armed = true),
+        )
+    }
+
+    @Test
+    fun `playing with no timer armed is ignored`() {
+        assertEquals(
+            IdleRevertAction.IGNORE,
+            idleRevertAction(upnpEngaged = true, isPlaying = true, armed = false),
+        )
+    }
+
+    @Test
+    fun `disengaging UPnP cancels an armed timer`() {
+        assertEquals(
+            IdleRevertAction.CANCEL,
+            idleRevertAction(upnpEngaged = false, isPlaying = false, armed = true),
+        )
+    }
+
+    @Test
+    fun `disengaged with no timer armed is ignored`() {
+        assertEquals(
+            IdleRevertAction.IGNORE,
+            idleRevertAction(upnpEngaged = false, isPlaying = true, armed = false),
+        )
+    }
+}

android/app/src/test/java/com/fabledsword/minstrel/playlists/data/PlaylistsRepositoryCacheMergeTest.kt

@@ -0,0 +1,64 @@
+package com.fabledsword.minstrel.playlists.data
+
+import com.fabledsword.minstrel.cache.db.dao.PlaylistCachedCount
+import com.fabledsword.minstrel.cache.db.entities.CachedPlaylistEntity
+import org.junit.jupiter.api.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+class PlaylistsRepositoryCacheMergeTest {
+
+    private fun playlist(id: String, trackCount: Int) =
+        CachedPlaylistEntity(id = id, userId = "u", name = id, trackCount = trackCount)
+
+    @Test
+    fun `fully cached when every member track is resident`() {
+        val out = mergePlaylistsWithCache(
+            rows = listOf(playlist("p", trackCount = 3)),
+            counts = listOf(PlaylistCachedCount("p", cachedCount = 3)),
+        )
+        assertTrue(out.single().fullyCached)
+    }
+
+    @Test
+    fun `not fully cached when only some tracks are resident`() {
+        val out = mergePlaylistsWithCache(
+            rows = listOf(playlist("p", trackCount = 3)),
+            counts = listOf(PlaylistCachedCount("p", cachedCount = 2)),
+        )
+        assertFalse(out.single().fullyCached)
+    }
+
+    @Test
+    fun `not fully cached when no tracks are resident (missing count row)`() {
+        val out = mergePlaylistsWithCache(
+            rows = listOf(playlist("p", trackCount = 3)),
+            counts = emptyList(),
+        )
+        assertFalse(out.single().fullyCached)
+    }
+
+    @Test
+    fun `empty playlist is never fully cached`() {
+        val out = mergePlaylistsWithCache(
+            rows = listOf(playlist("p", trackCount = 0)),
+            counts = listOf(PlaylistCachedCount("p", cachedCount = 0)),
+        )
+        assertFalse(out.single().fullyCached)
+    }
+
+    @Test
+    fun `each playlist gets its own cache verdict`() {
+        val out = mergePlaylistsWithCache(
+            rows = listOf(playlist("full", 2), playlist("partial", 2)),
+            counts = listOf(
+                PlaylistCachedCount("full", cachedCount = 2),
+                PlaylistCachedCount("partial", cachedCount = 1),
+            ),
+        )
+        val byId = out.associateBy { it.id }
+        assertEquals(true, byId.getValue("full").fullyCached)
+        assertEquals(false, byId.getValue("partial").fullyCached)
+    }
+}

cmd/minstrel/main.go

@@ -5,12 +5,15 @@ import (
 	"errors"
 	"flag"
 	"fmt"
+	"log/slog"
 	"net/http"
 	"os"
 	"os/signal"
 	"syscall"
 	"time"
 
+	"github.com/jackc/pgx/v5/pgxpool"
+
 	"git.fabledsword.com/bvandeusen/minstrel/internal/config"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/coverart"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db"
@@ -53,6 +56,35 @@ func main() {
 	}
 }
 
+// safetyNetScanInterval backstops the fsnotify watcher with a low-frequency
+// full delta walk, catching anything the watcher missed (inotify watch-limit
+// exhaustion, dropped events). Fixed — there is no operator configuration.
+const safetyNetScanInterval = 12 * time.Hour
+
+// runSafetyNetScans ticks a delta RunScan at safetyNetScanInterval until ctx
+// is cancelled, deferring to TryStartScan's in-flight guard so it never
+// collides with a manual, startup, or watcher-driven scan.
+func runSafetyNetScans(ctx context.Context, pool *pgxpool.Pool, scanner *library.Scanner,
+	enricher *coverart.Enricher, logger *slog.Logger, scanCfg library.RunScanConfig,
+) {
+	ticker := time.NewTicker(safetyNetScanInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			started, existing, err := library.TryStartScan(ctx, pool, scanner, enricher, logger, scanCfg)
+			if err != nil {
+				logger.Error("safety-net scan: try start failed", "err", err)
+			} else if !started && existing != nil {
+				logger.Info("safety-net scan skipped — prior still in flight",
+					"in_flight_id", existing.ID)
+			}
+		}
+	}
+}
+
 func run() error {
 	configPath := flag.String("config", os.Getenv("MINSTREL_CONFIG"), "path to YAML config file")
 	flag.Parse()
@@ -237,12 +269,24 @@ func run() error {
 		ArtistEnrichCap: -1,
 		DataDir:         cfg.Storage.DataDir,
 	}
-	scheduler := library.NewScheduler(pool, logger.With("component", "scheduler"),
-		scanner, coverEnricher, scanCfg)
-	scheduler.Start(ctx)
+	// Filesystem watcher: near-instant pickup of new/changed files via
+	// fsnotify, scanning just the affected paths + enriching their albums
+	// inline. Replaces the removed configurable scan scheduler.
+	watcher := library.NewWatcher(scanner, coverEnricher,
+		logger.With("component", "watcher"), cfg.Library.ScanPaths)
+	go func() {
+		if werr := watcher.Run(ctx); werr != nil {
+			logger.Warn("library watcher exited", "err", werr)
+		}
+	}()
+	// Safety-net delta walk backstops the watcher (inotify limits / dropped
+	// events) at a fixed low frequency. No operator config.
+	go runSafetyNetScans(ctx, pool, scanner, coverEnricher,
+		logger.With("component", "scan_safetynet"), scanCfg)
+
 	srv := server.New(logger, pool, scanner, subsonic.Config{
 		AllowPlaintextPassword: cfg.Subsonic.AllowPlaintextPassword,
-	}, cfg.Events, cfg.Recommendation, cfg.Storage.DataDir, cfg.Branding, coverEnricher, coverSettings, scanner, scanCfg, scheduler)
+	}, cfg.Events, cfg.Recommendation, cfg.Storage.DataDir, cfg.Branding, coverEnricher, coverSettings, scanner, scanCfg)
 	srv.Bus = bus
 	srv.PlaylistScheduler = playlistScheduler
 	srv.StreamSecret = cfg.StreamSecret

go.mod

@@ -4,6 +4,7 @@ go 1.25.0
 
 require (
 	github.com/dhowden/tag v0.0.0-20240417053706-3d75831295e8
+	github.com/fsnotify/fsnotify v1.10.1
 	github.com/go-chi/chi/v5 v5.2.5
 	github.com/go-co-op/gocron/v2 v2.21.2
 	github.com/golang-migrate/migrate/v4 v4.19.1
@@ -25,5 +26,6 @@ require (
 	github.com/robfig/cron/v3 v3.0.1 // indirect
 	github.com/rogpeppe/go-internal v1.14.1 // indirect
 	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
 	golang.org/x/text v0.37.0 // indirect
 )

go.sum

@@ -23,6 +23,8 @@ github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4
 github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
 github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
 github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
+github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
 github.com/go-chi/chi/v5 v5.2.5 h1:Eg4myHZBjyvJmAFjFvWgrqDTXFyOzjj7YIm3L3mu6Ug=
 github.com/go-chi/chi/v5 v5.2.5/go.mod h1:X7Gx4mteadT3eDOMTsXzmI4/rwUpOwBHLpAfupzFJP0=
 github.com/go-co-op/gocron/v2 v2.21.2 h1:bD8/YwkojYHgXFr3iEulL148KBdTbKVxUZzFKpXcdbY=

internal/api/admin_scan_schedule.go

@@ -1,155 +0,0 @@
-package api
-
-import (
-	"encoding/json"
-	"errors"
-	"fmt"
-	"net/http"
-	"time"
-
-	"github.com/jackc/pgx/v5"
-
-	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
-	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
-	"git.fabledsword.com/bvandeusen/minstrel/internal/library"
-)
-
-type scanScheduleResp struct {
-	Mode            string  `json:"mode"`
-	IntervalHours   *int    `json:"interval_hours"`
-	TimeOfDay       *string `json:"time_of_day"`
-	WeeklyDay       *int    `json:"weekly_day"`
-	NextScheduledAt *string `json:"next_scheduled_at"`
-}
-
-type scanScheduleReq struct {
-	Mode          string  `json:"mode"`
-	IntervalHours *int    `json:"interval_hours"`
-	TimeOfDay     *string `json:"time_of_day"`
-	WeeklyDay     *int    `json:"weekly_day"`
-}
-
-func (h *handlers) handleGetScanSchedule(w http.ResponseWriter, r *http.Request) {
-	q := dbq.New(h.pool)
-	row, err := q.GetScanSchedule(r.Context())
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			h.logger.Error("admin: scan_schedule singleton row missing")
-			writeErr(w, apierror.InternalMsg("schedule row missing", errors.New("schedule row missing")))
-			return
-		}
-		writeErrWithLog(w, h.logger, "admin: get scan schedule", apierror.InternalMsg("lookup failed", err))
-		return
-	}
-
-	writeJSON(w, http.StatusOK, scanScheduleRespFromRow(row, h.scheduler.NextFire()))
-}
-
-func (h *handlers) handlePatchScanSchedule(w http.ResponseWriter, r *http.Request) {
-	var req scanScheduleReq
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-		writeErr(w, apierror.BadRequest("bad_body", "invalid JSON"))
-		return
-	}
-
-	if err := validateScheduleReq(&req); err != nil {
-		writeErr(w, apierror.BadRequest("validation", err.Error()))
-		return
-	}
-
-	q := dbq.New(h.pool)
-	if err := q.UpdateScanSchedule(r.Context(), dbq.UpdateScanScheduleParams{
-		Mode:          req.Mode,
-		IntervalHours: pgInt32Ptr(req.IntervalHours),
-		TimeOfDay:     req.TimeOfDay,
-		WeeklyDay:     pgInt32Ptr(req.WeeklyDay),
-	}); err != nil {
-		writeErrWithLog(w, h.logger, "admin: update scan schedule", apierror.InternalMsg("update failed", err))
-		return
-	}
-
-	h.scheduler.Refresh()
-
-	row, err := q.GetScanSchedule(r.Context())
-	if err != nil {
-		writeErrWithLog(w, h.logger, "admin: re-read scan schedule", apierror.InternalMsg("re-read failed", err))
-		return
-	}
-	cfg := library.ScheduleConfig{Mode: row.Mode}
-	if row.IntervalHours != nil {
-		cfg.IntervalHours = int(*row.IntervalHours)
-	}
-	if row.TimeOfDay != nil {
-		cfg.TimeOfDay = *row.TimeOfDay
-	}
-	if row.WeeklyDay != nil {
-		cfg.WeeklyDay = int(*row.WeeklyDay)
-	}
-	next := cfg.NextFire(time.Now())
-
-	writeJSON(w, http.StatusOK, scanScheduleRespFromRow(row, next))
-}
-
-func validateScheduleReq(req *scanScheduleReq) error {
-	switch req.Mode {
-	case "off":
-		req.IntervalHours = nil
-		req.TimeOfDay = nil
-		req.WeeklyDay = nil
-		return nil
-	case "interval":
-		if req.IntervalHours == nil || *req.IntervalHours <= 0 {
-			return fmt.Errorf("interval_hours required and > 0 when mode=interval")
-		}
-		req.TimeOfDay = nil
-		req.WeeklyDay = nil
-		return nil
-	case "daily":
-		if req.TimeOfDay == nil || *req.TimeOfDay == "" {
-			return fmt.Errorf("time_of_day required when mode=daily")
-		}
-		req.IntervalHours = nil
-		req.WeeklyDay = nil
-		return nil
-	case "weekly":
-		if req.TimeOfDay == nil || *req.TimeOfDay == "" {
-			return fmt.Errorf("time_of_day required when mode=weekly")
-		}
-		if req.WeeklyDay == nil || *req.WeeklyDay < 1 || *req.WeeklyDay > 7 {
-			return fmt.Errorf("weekly_day required and in [1, 7] when mode=weekly")
-		}
-		req.IntervalHours = nil
-		return nil
-	default:
-		return fmt.Errorf("invalid mode %q (want off / interval / daily / weekly)", req.Mode)
-	}
-}
-
-func scanScheduleRespFromRow(row dbq.GetScanScheduleRow, nextFire time.Time) scanScheduleResp {
-	resp := scanScheduleResp{Mode: row.Mode}
-	if row.IntervalHours != nil {
-		v := int(*row.IntervalHours)
-		resp.IntervalHours = &v
-	}
-	if row.TimeOfDay != nil {
-		v := *row.TimeOfDay
-		resp.TimeOfDay = &v
-	}
-	if row.WeeklyDay != nil {
-		v := int(*row.WeeklyDay)
-		resp.WeeklyDay = &v
-	}
-	if !nextFire.IsZero() {
-		s := nextFire.UTC().Format(time.RFC3339)
-		resp.NextScheduledAt = &s
-	}
-	return resp
-}
-
-func pgInt32Ptr(src *int) *int32 {
-	if src == nil {
-		return nil
-	}
-	v := int32(*src)
-	return &v
-}

internal/api/admin_scan_schedule_test.go

@@ -1,181 +0,0 @@
-package api
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"testing"
-	"time"
-
-	"github.com/go-chi/chi/v5"
-
-	"git.fabledsword.com/bvandeusen/minstrel/internal/auth"
-	"git.fabledsword.com/bvandeusen/minstrel/internal/library"
-)
-
-func newAdminScheduleRouter(h *handlers) chi.Router {
-	r := chi.NewRouter()
-	r.Route("/api/admin", func(admin chi.Router) {
-		admin.Use(auth.RequireAdmin())
-		admin.Get("/scan/schedule", h.handleGetScanSchedule)
-		admin.Patch("/scan/schedule", h.handlePatchScanSchedule)
-	})
-	return r
-}
-
-func TestAdminScanSchedule_Get_DefaultIsOff(t *testing.T) {
-	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
-		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
-	}
-	h, pool := testHandlers(t)
-	s := library.NewScheduler(pool, h.logger, nil, nil, library.RunScanConfig{})
-	h.scheduler = s
-	admin := seedUser(t, pool, "schedget", "pw", true)
-
-	req := httptest.NewRequest(http.MethodGet, "/api/admin/scan/schedule", nil)
-	req = withUser(req, admin)
-	rec := httptest.NewRecorder()
-	newAdminScheduleRouter(h).ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
-	}
-	var resp scanScheduleResp
-	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
-		t.Fatalf("decode: %v", err)
-	}
-	if resp.Mode != "off" {
-		t.Errorf("Mode = %q, want off", resp.Mode)
-	}
-	if resp.NextScheduledAt != nil {
-		t.Errorf("NextScheduledAt = %v, want nil for mode=off", resp.NextScheduledAt)
-	}
-}
-
-func TestAdminScanSchedule_Patch_DailyMode(t *testing.T) {
-	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
-		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
-	}
-	h, pool := testHandlers(t)
-	s := library.NewScheduler(pool, h.logger, nil, nil, library.RunScanConfig{})
-	h.scheduler = s
-	admin := seedUser(t, pool, "schedpatch", "pw", true)
-
-	body := `{"mode":"daily","time_of_day":"03:00"}`
-	req := httptest.NewRequest(http.MethodPatch, "/api/admin/scan/schedule",
-		bytes.NewReader([]byte(body)))
-	req.Header.Set("Content-Type", "application/json")
-	req = withUser(req, admin)
-	rec := httptest.NewRecorder()
-	newAdminScheduleRouter(h).ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
-	}
-	var resp scanScheduleResp
-	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
-		t.Fatalf("decode: %v", err)
-	}
-	if resp.Mode != "daily" {
-		t.Errorf("Mode = %q, want daily", resp.Mode)
-	}
-	if resp.TimeOfDay == nil || *resp.TimeOfDay != "03:00" {
-		t.Errorf("TimeOfDay = %v, want '03:00'", resp.TimeOfDay)
-	}
-	if resp.NextScheduledAt == nil {
-		t.Errorf("NextScheduledAt = nil, want a future ISO timestamp")
-	} else {
-		next, err := time.Parse(time.RFC3339, *resp.NextScheduledAt)
-		if err != nil {
-			t.Errorf("NextScheduledAt parse: %v", err)
-		} else if local := next.Local(); local.Hour() != 3 || local.Minute() != 0 {
-			// Handler computes next-fire from time.Now() in the host zone, so
-			// the local-time hour is what's stable across CI runners regardless
-			// of TZ; the wire timestamp is UTC but parses back to the same
-			// instant either way.
-			t.Errorf("NextScheduledAt local time = %v, want 03:00 in host zone", local)
-		}
-	}
-}
-
-func TestAdminScanSchedule_Patch_WeeklyMissingDay_400(t *testing.T) {
-	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
-		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
-	}
-	h, pool := testHandlers(t)
-	s := library.NewScheduler(pool, h.logger, nil, nil, library.RunScanConfig{})
-	h.scheduler = s
-	admin := seedUser(t, pool, "schedweekly", "pw", true)
-
-	body := `{"mode":"weekly","time_of_day":"03:00"}`
-	req := httptest.NewRequest(http.MethodPatch, "/api/admin/scan/schedule",
-		bytes.NewReader([]byte(body)))
-	req.Header.Set("Content-Type", "application/json")
-	req = withUser(req, admin)
-	rec := httptest.NewRecorder()
-	newAdminScheduleRouter(h).ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusBadRequest {
-		t.Errorf("status = %d, want 400; body=%s", rec.Code, rec.Body.String())
-	}
-}
-
-func TestAdminScanSchedule_Patch_OffNormalizes(t *testing.T) {
-	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
-		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
-	}
-	h, pool := testHandlers(t)
-	s := library.NewScheduler(pool, h.logger, nil, nil, library.RunScanConfig{})
-	h.scheduler = s
-	admin := seedUser(t, pool, "schedoff", "pw", true)
-
-	if _, err := pool.Exec(context.Background(),
-		`UPDATE scan_schedule SET mode='daily', time_of_day='03:00' WHERE id=true`,
-	); err != nil {
-		t.Fatalf("seed: %v", err)
-	}
-
-	body := `{"mode":"off","time_of_day":"03:00"}`
-	req := httptest.NewRequest(http.MethodPatch, "/api/admin/scan/schedule",
-		bytes.NewReader([]byte(body)))
-	req.Header.Set("Content-Type", "application/json")
-	req = withUser(req, admin)
-	rec := httptest.NewRecorder()
-	newAdminScheduleRouter(h).ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
-	}
-
-	var timeOfDay *string
-	if err := pool.QueryRow(context.Background(),
-		`SELECT time_of_day FROM scan_schedule WHERE id=true`,
-	).Scan(&timeOfDay); err != nil {
-		t.Fatalf("verify: %v", err)
-	}
-	if timeOfDay != nil {
-		t.Errorf("time_of_day = %v, want nil after mode=off normalize", timeOfDay)
-	}
-}
-
-func TestAdminScanSchedule_NonAdmin_403(t *testing.T) {
-	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
-		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
-	}
-	h, pool := testHandlers(t)
-	s := library.NewScheduler(pool, h.logger, nil, nil, library.RunScanConfig{})
-	h.scheduler = s
-	user := seedUser(t, pool, "schednonadmin", "pw", false)
-
-	req := httptest.NewRequest(http.MethodGet, "/api/admin/scan/schedule", nil)
-	req = withUser(req, user)
-	rec := httptest.NewRecorder()
-	newAdminScheduleRouter(h).ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusForbidden {
-		t.Errorf("status = %d, want 403", rec.Code)
-	}
-}

internal/api/api.go

@@ -28,7 +28,7 @@ import (
 // Mount attaches /api/* handlers to r. Public endpoints (login) are outside
 // RequireUser; everything else is gated by the middleware. The events writer
 // is shared with the Subsonic mount so /rest/scrobble feeds the same store.
-func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, scheduler *library.Scheduler, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler, streamSecret []byte) {
+func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playevents.Writer, recCfg config.RecommendationConfig, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, scanner *library.Scanner, scanCfg library.RunScanConfig, dataDir string, sender mailer.Sender, bus *eventbus.Bus, playlistScheduler *playlists.Scheduler, streamSecret []byte) {
 	rng := rand.New(rand.NewSource(rand.Int63()))
 	h := &handlers{
 		pool: pool, logger: logger, events: events, recCfg: recCfg,
@@ -42,7 +42,6 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		coverSettings:     coverSettings,
 		scanner:           scanner,
 		scanCfg:           scanCfg,
-		scheduler:         scheduler,
 		dataDir:           dataDir,
 		mailer:            sender,
 		eventbus:          bus,
@@ -87,6 +86,8 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 			authed.Get("/artists", h.handleListArtists)
 			authed.Get("/artists/{id}", h.handleGetArtist)
 			authed.Get("/artists/{id}/tracks", h.handleGetArtistTracks)
+			authed.Get("/artists/{id}/similar", h.handleGetSimilarArtists)
+			authed.Get("/artists/{id}/top-tracks", h.handleGetArtistTopTracks)
 			authed.Get("/albums/{id}", h.handleGetAlbum)
 			authed.Get("/albums/{id}/cover", h.handleGetCover)
 			authed.Get("/library/shuffle", h.handleLibraryShuffle)
@@ -167,8 +168,6 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 
 				admin.Get("/scan/status", h.handleGetScanStatus)
 				admin.Post("/scan/run", h.handleTriggerScan)
-				admin.Get("/scan/schedule", h.handleGetScanSchedule)
-				admin.Patch("/scan/schedule", h.handlePatchScanSchedule)
 
 				admin.Get("/library/coverage", h.handleGetLibraryCoverage)
 
@@ -222,7 +221,6 @@ type handlers struct {
 	coverSettings     *coverart.SettingsService
 	scanner           *library.Scanner
 	scanCfg           library.RunScanConfig
-	scheduler         *library.Scheduler
 	dataDir           string
 	mailer            mailer.Sender
 	eventbus          *eventbus.Bus

internal/api/home.go

@@ -30,6 +30,8 @@ func (h *handlers) handleGetHome(w http.ResponseWriter, r *http.Request) {
 		RediscoverArtists:   make([]ArtistRef, 0, len(data.RediscoverArtists)),
 		MostPlayedTracks:    make([]TrackRef, 0, len(data.MostPlayedTracks)),
 		LastPlayedArtists:   make([]ArtistRef, 0, len(data.LastPlayedArtists)),
+		YouMightLikeAlbums:  make([]AlbumRef, 0, len(data.YouMightLikeAlbums)),
+		YouMightLikeArtists: make([]ArtistRef, 0, len(data.YouMightLikeArtists)),
 	}
 	for _, row := range data.RecentlyAddedAlbums {
 		out.RecentlyAddedAlbums = append(out.RecentlyAddedAlbums, albumRefFrom(row.Album, row.ArtistName, 0, 0))
@@ -46,6 +48,12 @@ func (h *handlers) handleGetHome(w http.ResponseWriter, r *http.Request) {
 	for _, row := range data.LastPlayedArtists {
 		out.LastPlayedArtists = append(out.LastPlayedArtists, artistRefFromCovered(row.Artist, int(row.AlbumCount), row.CoverAlbumID))
 	}
+	for _, row := range data.YouMightLikeAlbums {
+		out.YouMightLikeAlbums = append(out.YouMightLikeAlbums, albumRefFrom(row.Album, row.ArtistName, 0, 0))
+	}
+	for _, row := range data.YouMightLikeArtists {
+		out.YouMightLikeArtists = append(out.YouMightLikeArtists, artistRefFromCovered(row.Artist, int(row.AlbumCount), row.CoverAlbumID))
+	}
 	writeJSON(w, http.StatusOK, out)
 }
 
@@ -78,6 +86,8 @@ func (h *handlers) handleGetHomeIndex(w http.ResponseWriter, r *http.Request) {
 		RediscoverArtists:   make([]string, 0, len(data.RediscoverArtists)),
 		MostPlayedTracks:    make([]string, 0, len(data.MostPlayedTracks)),
 		LastPlayedArtists:   make([]string, 0, len(data.LastPlayedArtists)),
+		YouMightLikeAlbums:  make([]string, 0, len(data.YouMightLikeAlbums)),
+		YouMightLikeArtists: make([]string, 0, len(data.YouMightLikeArtists)),
 	}
 	for _, row := range data.RecentlyAddedAlbums {
 		out.RecentlyAddedAlbums = append(out.RecentlyAddedAlbums, uuidToString(row.Album.ID))
@@ -94,6 +104,12 @@ func (h *handlers) handleGetHomeIndex(w http.ResponseWriter, r *http.Request) {
 	for _, row := range data.LastPlayedArtists {
 		out.LastPlayedArtists = append(out.LastPlayedArtists, uuidToString(row.Artist.ID))
 	}
+	for _, row := range data.YouMightLikeAlbums {
+		out.YouMightLikeAlbums = append(out.YouMightLikeAlbums, uuidToString(row.Album.ID))
+	}
+	for _, row := range data.YouMightLikeArtists {
+		out.YouMightLikeArtists = append(out.YouMightLikeArtists, uuidToString(row.Artist.ID))
+	}
 	writeJSON(w, http.StatusOK, out)
 }
 

internal/api/library.go

@@ -159,6 +159,85 @@ func (h *handlers) handleGetArtistTracks(w http.ResponseWriter, r *http.Request)
 	writeJSON(w, http.StatusOK, out)
 }
 
+// similarArtistsDefaultLimit caps the artist-detail "similar artists" strip;
+// artistTopTracksDefaultLimit caps the per-user "top tracks" panel.
+const (
+	similarArtistsDefaultLimit  = 12
+	artistTopTracksDefaultLimit = 5
+)
+
+// handleGetSimilarArtists implements GET /api/artists/{id}/similar. Returns
+// in-library artists similar to {id} (ranked by similarity score) as a flat
+// ArtistRef list with cover + album count. Empty when the similarity ingest
+// has no matches yet; 404 when the artist doesn't exist.
+func (h *handlers) handleGetSimilarArtists(w http.ResponseWriter, r *http.Request) {
+	id, ok := requireURLUUID(w, r, "id")
+	if !ok {
+		return
+	}
+	q := dbq.New(h.pool)
+	if _, err := q.GetArtistByID(r.Context(), id); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			writeErr(w, apierror.NotFound("artist"))
+			return
+		}
+		h.logger.Error("api: get artist for similar", "err", err)
+		writeErr(w, apierror.InternalMsg("lookup failed", err))
+		return
+	}
+	rows, err := q.ListSimilarArtistsForArtist(r.Context(), dbq.ListSimilarArtistsForArtistParams{
+		SeedArtistID: id, ResultLimit: similarArtistsDefaultLimit,
+	})
+	if err != nil {
+		h.logger.Error("api: list similar artists", "err", err)
+		writeErr(w, apierror.InternalMsg("lookup failed", err))
+		return
+	}
+	out := make([]ArtistRef, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, artistRefFromCovered(row.Artist, int(row.AlbumCount), row.CoverAlbumID))
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+// handleGetArtistTopTracks implements GET /api/artists/{id}/top-tracks. Returns
+// the current user's most-played tracks for {id} (skips excluded, quarantine
+// filtered). Empty when the user hasn't played this artist; 404 when the
+// artist doesn't exist.
+func (h *handlers) handleGetArtistTopTracks(w http.ResponseWriter, r *http.Request) {
+	id, ok := requireURLUUID(w, r, "id")
+	if !ok {
+		return
+	}
+	user, ok := requireUser(w, r)
+	if !ok {
+		return
+	}
+	q := dbq.New(h.pool)
+	if _, err := q.GetArtistByID(r.Context(), id); err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			writeErr(w, apierror.NotFound("artist"))
+			return
+		}
+		h.logger.Error("api: get artist for top tracks", "err", err)
+		writeErr(w, apierror.InternalMsg("lookup failed", err))
+		return
+	}
+	rows, err := q.ListMostPlayedTracksForArtist(r.Context(), dbq.ListMostPlayedTracksForArtistParams{
+		ArtistID: id, UserID: user.ID, ResultLimit: artistTopTracksDefaultLimit,
+	})
+	if err != nil {
+		h.logger.Error("api: list artist top tracks", "err", err)
+		writeErr(w, apierror.InternalMsg("lookup failed", err))
+		return
+	}
+	out := make([]TrackRef, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, trackRefFrom(row.Track, row.AlbumTitle, row.ArtistName))
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
 // handleLibraryShuffle implements GET /api/library/shuffle?limit=N —
 // the online source for the client's always-present "Shuffle all"
 // (#427 S4). N random tracks across the whole library, per-user

internal/api/library_test.go

@@ -465,7 +465,7 @@ func TestRoutesRegisteredInMount(t *testing.T) {
 	r := chi.NewRouter()
 	w := playevents.NewWriter(h.pool, slog.New(slog.NewTextHandler(io.Discard, nil)),
 		30*time.Minute, 0.5, 30000)
-	Mount(r, h.pool, h.logger, w, config.RecommendationConfig{RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1}, h.lidarrCfg, h.lidarrRequests, h.lidarrQuarantine, h.tracks, h.playlists, h.coverart, h.coverSettings, h.scanner, h.scanCfg, nil, h.dataDir, nil, eventbus.New(), nil, nil)
+	Mount(r, h.pool, h.logger, w, config.RecommendationConfig{RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1}, h.lidarrCfg, h.lidarrRequests, h.lidarrQuarantine, h.tracks, h.playlists, h.coverart, h.coverSettings, h.scanner, h.scanCfg, h.dataDir, nil, eventbus.New(), nil, nil)
 
 	paths := []string{
 		"/api/artists",

internal/api/radio.go

@@ -108,6 +108,7 @@ func (h *handlers) handleRadio(w http.ResponseWriter, r *http.Request) {
 		JitterMagnitude:  h.recCfg.JitterMagnitude,
 		ContextWeight:    h.recCfg.ContextWeight,
 		SimilarityWeight: h.recCfg.SimilarityWeight,
+		TasteWeight:      h.recCfg.TasteWeight,
 	}
 	picks := recommendation.Shuffle(candidates, weights, time.Now().UTC(), h.rng, limit-1)
 

internal/api/types.go

@@ -116,6 +116,11 @@ type HomePayload struct {
 	RediscoverArtists   []ArtistRef `json:"rediscover_artists"`
 	MostPlayedTracks    []TrackRef  `json:"most_played_tracks"`
 	LastPlayedArtists   []ArtistRef `json:"last_played_artists"`
+	// You-might-like: in-library albums/artists predicted from the user's
+	// listening that they don't actively spin. Built daily; gated on a
+	// minimum listening history so a thin profile gets empty rows.
+	YouMightLikeAlbums  []AlbumRef  `json:"you_might_like_albums"`
+	YouMightLikeArtists []ArtistRef `json:"you_might_like_artists"`
 }
 
 // HomeIndexPayload is the response body of GET /api/home/index — the
@@ -134,6 +139,8 @@ type HomeIndexPayload struct {
 	RediscoverArtists   []string `json:"rediscover_artists"`
 	MostPlayedTracks    []string `json:"most_played_tracks"`
 	LastPlayedArtists   []string `json:"last_played_artists"`
+	YouMightLikeAlbums  []string `json:"you_might_like_albums"`
+	YouMightLikeArtists []string `json:"you_might_like_artists"`
 }
 
 // HistoryEvent is one play in a user's listening history. Used by

internal/config/config.go

@@ -98,6 +98,7 @@ type RecommendationConfig struct {
 	JitterMagnitude     float64 `yaml:"jitter_magnitude"`
 	ContextWeight       float64 `yaml:"context_weight"`
 	SimilarityWeight    float64 `yaml:"similarity_weight"`
+	TasteWeight         float64 `yaml:"taste_weight"`
 	RecentlyPlayedHours int     `yaml:"recently_played_hours"`
 	RadioSize           int     `yaml:"radio_size"`
 	RadioSizeMax        int     `yaml:"radio_size_max"`
@@ -119,13 +120,16 @@ func Default() Config {
 			SkipMaxDurationPlayedMs: 30000,
 		},
 		Recommendation: RecommendationConfig{
-			BaseWeight:          1.0,
-			LikeBoost:           2.0,
-			RecencyWeight:       1.0,
-			SkipPenalty:         1.0,
-			JitterMagnitude:     0.1,
-			ContextWeight:       2.0,
-			SimilarityWeight:    2.0,
+			BaseWeight:       1.0,
+			LikeBoost:        2.0,
+			RecencyWeight:    1.0,
+			SkipPenalty:      1.0,
+			JitterMagnitude:  0.1,
+			ContextWeight:    2.0,
+			SimilarityWeight: 2.0,
+			// Radio is seed-directed (the user picked a direction), so taste
+			// is a lighter nudge here than in the daily mixes (1.5).
+			TasteWeight:         1.0,
 			RecentlyPlayedHours: 1,
 			RadioSize:           50,
 			RadioSizeMax:        200,

internal/db/dbq/models.go

@@ -439,15 +439,6 @@ type ScanRun struct {
 	ArtistArtEnrich []byte
 }
 
-type ScanSchedule struct {
-	ID            bool
-	Mode          string
-	IntervalHours *int32
-	TimeOfDay     *string
-	WeeklyDay     *int32
-	UpdatedAt     pgtype.Timestamptz
-}
-
 type ScrobbleQueue struct {
 	ID            pgtype.UUID
 	UserID        pgtype.UUID
@@ -506,6 +497,20 @@ type SystemPlaylistRun struct {
 	LastError   *string
 }
 
+type TasteProfileArtist struct {
+	UserID    pgtype.UUID
+	ArtistID  pgtype.UUID
+	Weight    float64
+	UpdatedAt pgtype.Timestamptz
+}
+
+type TasteProfileTag struct {
+	UserID    pgtype.UUID
+	Tag       string
+	Weight    float64
+	UpdatedAt pgtype.Timestamptz
+}
+
 type Track struct {
 	ID          pgtype.UUID
 	Title       string
@@ -558,3 +563,17 @@ type UserInvite struct {
 	RedeemedAt pgtype.Timestamptz
 	RedeemedBy pgtype.UUID
 }
+
+type YouMightLikeAlbum struct {
+	UserID  pgtype.UUID
+	AlbumID pgtype.UUID
+	Rank    int32
+	BuiltAt pgtype.Timestamptz
+}
+
+type YouMightLikeArtist struct {
+	UserID   pgtype.UUID
+	ArtistID pgtype.UUID
+	Rank     int32
+	BuiltAt  pgtype.Timestamptz
+}

internal/db/dbq/recommendation.sql.go

@@ -97,6 +97,83 @@ func (q *Queries) ListLastPlayedArtistsForUser(ctx context.Context, arg ListLast
 	return items, nil
 }
 
+const listMostPlayedTracksForArtist = `-- name: ListMostPlayedTracksForArtist :many
+WITH plays AS (
+    SELECT track_id, count(*) AS cnt
+    FROM play_events
+    WHERE user_id = $2 AND was_skipped = false
+    GROUP BY track_id
+)
+SELECT t.id, t.title, t.album_id, t.artist_id, t.track_number, t.disc_number, t.duration_ms, t.file_path, t.file_size, t.file_format, t.bitrate, t.mbid, t.genre, t.added_at, t.updated_at,
+       albums.title AS album_title,
+       artists.name AS artist_name
+FROM plays p
+JOIN tracks t   ON t.id = p.track_id
+JOIN albums     ON albums.id  = t.album_id
+JOIN artists    ON artists.id = t.artist_id
+WHERE t.artist_id = $1
+  AND NOT EXISTS (
+      SELECT 1 FROM lidarr_quarantine q
+      WHERE q.user_id = $2 AND q.track_id = t.id
+  )
+ORDER BY p.cnt DESC, t.id
+LIMIT $3
+`
+
+type ListMostPlayedTracksForArtistParams struct {
+	ArtistID    pgtype.UUID
+	UserID      pgtype.UUID
+	ResultLimit int32
+}
+
+type ListMostPlayedTracksForArtistRow struct {
+	Track      Track
+	AlbumTitle string
+	ArtistName string
+}
+
+// Top tracks for one artist by this user's completed-play count (skips
+// excluded, quarantine filtered). Same projection as
+// ListMostPlayedTracksForUser plus an artist_id filter, so the handler
+// reuses trackRefFrom(row.Track, row.AlbumTitle, row.ArtistName).
+func (q *Queries) ListMostPlayedTracksForArtist(ctx context.Context, arg ListMostPlayedTracksForArtistParams) ([]ListMostPlayedTracksForArtistRow, error) {
+	rows, err := q.db.Query(ctx, listMostPlayedTracksForArtist, arg.ArtistID, arg.UserID, arg.ResultLimit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListMostPlayedTracksForArtistRow
+	for rows.Next() {
+		var i ListMostPlayedTracksForArtistRow
+		if err := rows.Scan(
+			&i.Track.ID,
+			&i.Track.Title,
+			&i.Track.AlbumID,
+			&i.Track.ArtistID,
+			&i.Track.TrackNumber,
+			&i.Track.DiscNumber,
+			&i.Track.DurationMs,
+			&i.Track.FilePath,
+			&i.Track.FileSize,
+			&i.Track.FileFormat,
+			&i.Track.Bitrate,
+			&i.Track.Mbid,
+			&i.Track.Genre,
+			&i.Track.AddedAt,
+			&i.Track.UpdatedAt,
+			&i.AlbumTitle,
+			&i.ArtistName,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const listMostPlayedTracksForUser = `-- name: ListMostPlayedTracksForUser :many
 WITH plays AS (
     SELECT track_id, count(*) AS cnt

internal/db/dbq/scan_schedule.sql.go

@@ -1,71 +0,0 @@
-// Code generated by sqlc. DO NOT EDIT.
-// versions:
-//   sqlc v1.31.1
-// source: scan_schedule.sql
-
-package dbq
-
-import (
-	"context"
-
-	"github.com/jackc/pgx/v5/pgtype"
-)
-
-const getScanSchedule = `-- name: GetScanSchedule :one
-SELECT mode, interval_hours, time_of_day, weekly_day, updated_at
-  FROM scan_schedule WHERE id = true
-`
-
-type GetScanScheduleRow struct {
-	Mode          string
-	IntervalHours *int32
-	TimeOfDay     *string
-	WeeklyDay     *int32
-	UpdatedAt     pgtype.Timestamptz
-}
-
-// M7 recurring-scans: returns the singleton schedule row. Used by the
-// scheduler goroutine on boot and config-refresh, and by the admin GET
-// handler.
-func (q *Queries) GetScanSchedule(ctx context.Context) (GetScanScheduleRow, error) {
-	row := q.db.QueryRow(ctx, getScanSchedule)
-	var i GetScanScheduleRow
-	err := row.Scan(
-		&i.Mode,
-		&i.IntervalHours,
-		&i.TimeOfDay,
-		&i.WeeklyDay,
-		&i.UpdatedAt,
-	)
-	return i, err
-}
-
-const updateScanSchedule = `-- name: UpdateScanSchedule :exec
-UPDATE scan_schedule
-   SET mode           = $1,
-       interval_hours = $2,
-       time_of_day    = $3,
-       weekly_day     = $4,
-       updated_at     = now()
- WHERE id = true
-`
-
-type UpdateScanScheduleParams struct {
-	Mode          string
-	IntervalHours *int32
-	TimeOfDay     *string
-	WeeklyDay     *int32
-}
-
-// Admin PATCH replaces the whole row; CHECK constraints enforce validity.
-// The application normalizes mode='off' to NULL the per-mode fields
-// before calling this.
-func (q *Queries) UpdateScanSchedule(ctx context.Context, arg UpdateScanScheduleParams) error {
-	_, err := q.db.Exec(ctx, updateScanSchedule,
-		arg.Mode,
-		arg.IntervalHours,
-		arg.TimeOfDay,
-		arg.WeeklyDay,
-	)
-	return err
-}

internal/db/dbq/similarity.sql.go

@@ -154,6 +154,77 @@ func (q *Queries) ListPlayedTracksNeedingSimilarity(ctx context.Context, limit i
 	return items, nil
 }
 
+const listSimilarArtistsForArtist = `-- name: ListSimilarArtistsForArtist :many
+SELECT artists.id, artists.name, artists.sort_name, artists.mbid, artists.created_at, artists.updated_at, artists.artist_thumb_path, artists.artist_fanart_path, artists.artist_art_source, artists.artist_art_sources_version,
+       cov.id AS cover_album_id,
+       cnt.album_count::bigint AS album_count
+FROM (
+    SELECT artist_b_id, max(score) AS sim_score
+    FROM artist_similarity
+    WHERE artist_a_id = $1
+    GROUP BY artist_b_id
+) s
+JOIN artists ON artists.id = s.artist_b_id
+LEFT JOIN LATERAL (
+    SELECT id FROM albums
+    WHERE artist_id = artists.id AND cover_art_path IS NOT NULL
+    ORDER BY created_at DESC LIMIT 1
+) cov ON true
+LEFT JOIN LATERAL (
+    SELECT count(*) AS album_count
+    FROM albums WHERE artist_id = artists.id
+) cnt ON true
+ORDER BY s.sim_score DESC, artists.sort_name
+LIMIT $2
+`
+
+type ListSimilarArtistsForArtistParams struct {
+	SeedArtistID pgtype.UUID
+	ResultLimit  int32
+}
+
+type ListSimilarArtistsForArtistRow struct {
+	Artist       Artist
+	CoverAlbumID pgtype.UUID
+	AlbumCount   int64
+}
+
+// In-library artists similar to a seed artist, ranked by best similarity
+// score across sources (deduped per candidate). cover_album_id + album_count
+// mirror ListArtistsAlphaWithCovers so the strip renders identical cards.
+func (q *Queries) ListSimilarArtistsForArtist(ctx context.Context, arg ListSimilarArtistsForArtistParams) ([]ListSimilarArtistsForArtistRow, error) {
+	rows, err := q.db.Query(ctx, listSimilarArtistsForArtist, arg.SeedArtistID, arg.ResultLimit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListSimilarArtistsForArtistRow
+	for rows.Next() {
+		var i ListSimilarArtistsForArtistRow
+		if err := rows.Scan(
+			&i.Artist.ID,
+			&i.Artist.Name,
+			&i.Artist.SortName,
+			&i.Artist.Mbid,
+			&i.Artist.CreatedAt,
+			&i.Artist.UpdatedAt,
+			&i.Artist.ArtistThumbPath,
+			&i.Artist.ArtistFanartPath,
+			&i.Artist.ArtistArtSource,
+			&i.Artist.ArtistArtSourcesVersion,
+			&i.CoverAlbumID,
+			&i.AlbumCount,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const upsertArtistSimilarity = `-- name: UpsertArtistSimilarity :exec
 INSERT INTO artist_similarity (artist_a_id, artist_b_id, score, source, fetched_at)
 VALUES ($1, $2, $3, 'listenbrainz', now())

internal/db/dbq/taste_profile.sql.go

@@ -0,0 +1,262 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: taste_profile.sql
+
+package dbq
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const deleteTasteProfileArtistsForUser = `-- name: DeleteTasteProfileArtistsForUser :exec
+DELETE FROM taste_profile_artists WHERE user_id = $1
+`
+
+func (q *Queries) DeleteTasteProfileArtistsForUser(ctx context.Context, userID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteTasteProfileArtistsForUser, userID)
+	return err
+}
+
+const deleteTasteProfileTagsForUser = `-- name: DeleteTasteProfileTagsForUser :exec
+DELETE FROM taste_profile_tags WHERE user_id = $1
+`
+
+func (q *Queries) DeleteTasteProfileTagsForUser(ctx context.Context, userID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteTasteProfileTagsForUser, userID)
+	return err
+}
+
+const insertTasteProfileArtist = `-- name: InsertTasteProfileArtist :exec
+INSERT INTO taste_profile_artists (user_id, artist_id, weight)
+VALUES ($1, $2, $3)
+`
+
+type InsertTasteProfileArtistParams struct {
+	UserID   pgtype.UUID
+	ArtistID pgtype.UUID
+	Weight   float64
+}
+
+func (q *Queries) InsertTasteProfileArtist(ctx context.Context, arg InsertTasteProfileArtistParams) error {
+	_, err := q.db.Exec(ctx, insertTasteProfileArtist, arg.UserID, arg.ArtistID, arg.Weight)
+	return err
+}
+
+const insertTasteProfileTag = `-- name: InsertTasteProfileTag :exec
+INSERT INTO taste_profile_tags (user_id, tag, weight)
+VALUES ($1, $2, $3)
+`
+
+type InsertTasteProfileTagParams struct {
+	UserID pgtype.UUID
+	Tag    string
+	Weight float64
+}
+
+func (q *Queries) InsertTasteProfileTag(ctx context.Context, arg InsertTasteProfileTagParams) error {
+	_, err := q.db.Exec(ctx, insertTasteProfileTag, arg.UserID, arg.Tag, arg.Weight)
+	return err
+}
+
+const listLikedArtistIDsForUser = `-- name: ListLikedArtistIDsForUser :many
+SELECT artist_id FROM general_likes_artists WHERE user_id = $1
+`
+
+// Artists the user has explicitly liked; feeds the artist-like bonus.
+func (q *Queries) ListLikedArtistIDsForUser(ctx context.Context, userID pgtype.UUID) ([]pgtype.UUID, error) {
+	rows, err := q.db.Query(ctx, listLikedArtistIDsForUser, userID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []pgtype.UUID
+	for rows.Next() {
+		var artist_id pgtype.UUID
+		if err := rows.Scan(&artist_id); err != nil {
+			return nil, err
+		}
+		items = append(items, artist_id)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listLikedTrackTasteInputsForUser = `-- name: ListLikedTrackTasteInputsForUser :many
+SELECT t.artist_id, t.genre
+FROM general_likes gl
+JOIN tracks t ON t.id = gl.track_id
+WHERE gl.user_id = $1
+`
+
+type ListLikedTrackTasteInputsForUserRow struct {
+	ArtistID pgtype.UUID
+	Genre    *string
+}
+
+// (artist_id, genre) for each track the user has explicitly liked. Feeds the
+// track-like bonus into the liked track's artist and tags.
+func (q *Queries) ListLikedTrackTasteInputsForUser(ctx context.Context, userID pgtype.UUID) ([]ListLikedTrackTasteInputsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listLikedTrackTasteInputsForUser, userID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListLikedTrackTasteInputsForUserRow
+	for rows.Next() {
+		var i ListLikedTrackTasteInputsForUserRow
+		if err := rows.Scan(&i.ArtistID, &i.Genre); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listPlayEngagementInputsForUser = `-- name: ListPlayEngagementInputsForUser :many
+
+SELECT
+    t.artist_id,
+    t.genre,
+    LEAST(GREATEST(
+        COALESCE(pe.completion_ratio,
+                 pe.duration_played_ms::float8 / NULLIF(t.duration_ms, 0),
+                 0), 0), 1)::float8 AS completion,
+    (EXTRACT(epoch FROM now() - pe.started_at) / 86400.0)::float8 AS age_days
+FROM play_events pe
+JOIN tracks t ON t.id = pe.track_id
+WHERE pe.user_id = $1
+  AND pe.started_at > now() - ($2::float8 * INTERVAL '1 day')
+  AND NOT EXISTS (
+      SELECT 1 FROM lidarr_quarantine q
+      WHERE q.user_id = $1 AND q.track_id = t.id
+  )
+`
+
+type ListPlayEngagementInputsForUserParams struct {
+	UserID  pgtype.UUID
+	Column2 float64
+}
+
+type ListPlayEngagementInputsForUserRow struct {
+	ArtistID   pgtype.UUID
+	Genre      *string
+	Completion float64
+	AgeDays    float64
+}
+
+// Taste profile (#796 phase 1). The daily build computes signed artist/tag
+// weights in Go (graded engagement + decay + like bonus) and atomic-replaces
+// them here. Read queries serve "top taste" lookups (used in phase 2).
+// One row per play in the decay-relevant window. completion is the play's
+// completion ratio (precomputed column when present, else duration_played /
+// track duration, clamped to [0,1]); age_days drives the time-decay. Genre
+// is split into tags in Go. Quarantined tracks are excluded.
+func (q *Queries) ListPlayEngagementInputsForUser(ctx context.Context, arg ListPlayEngagementInputsForUserParams) ([]ListPlayEngagementInputsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listPlayEngagementInputsForUser, arg.UserID, arg.Column2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListPlayEngagementInputsForUserRow
+	for rows.Next() {
+		var i ListPlayEngagementInputsForUserRow
+		if err := rows.Scan(
+			&i.ArtistID,
+			&i.Genre,
+			&i.Completion,
+			&i.AgeDays,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listTasteProfileArtistsForUser = `-- name: ListTasteProfileArtistsForUser :many
+SELECT artist_id, weight
+FROM taste_profile_artists
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2
+`
+
+type ListTasteProfileArtistsForUserParams struct {
+	UserID pgtype.UUID
+	Limit  int32
+}
+
+type ListTasteProfileArtistsForUserRow struct {
+	ArtistID pgtype.UUID
+	Weight   float64
+}
+
+// Top-weighted taste artists (phase-2 consumption + tests).
+func (q *Queries) ListTasteProfileArtistsForUser(ctx context.Context, arg ListTasteProfileArtistsForUserParams) ([]ListTasteProfileArtistsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listTasteProfileArtistsForUser, arg.UserID, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTasteProfileArtistsForUserRow
+	for rows.Next() {
+		var i ListTasteProfileArtistsForUserRow
+		if err := rows.Scan(&i.ArtistID, &i.Weight); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listTasteProfileTagsForUser = `-- name: ListTasteProfileTagsForUser :many
+SELECT tag, weight
+FROM taste_profile_tags
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2
+`
+
+type ListTasteProfileTagsForUserParams struct {
+	UserID pgtype.UUID
+	Limit  int32
+}
+
+type ListTasteProfileTagsForUserRow struct {
+	Tag    string
+	Weight float64
+}
+
+func (q *Queries) ListTasteProfileTagsForUser(ctx context.Context, arg ListTasteProfileTagsForUserParams) ([]ListTasteProfileTagsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listTasteProfileTagsForUser, arg.UserID, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTasteProfileTagsForUserRow
+	for rows.Next() {
+		var i ListTasteProfileTagsForUserRow
+		if err := rows.Scan(&i.Tag, &i.Weight); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}

internal/db/dbq/you_might_like.sql.go

@@ -0,0 +1,217 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: you_might_like.sql
+
+package dbq
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const countListeningSignalForUser = `-- name: CountListeningSignalForUser :one
+
+SELECT
+    count(DISTINCT pe.track_id)::bigint AS distinct_tracks,
+    count(DISTINCT t.artist_id)::bigint AS distinct_artists
+FROM play_events pe
+JOIN tracks t ON t.id = pe.track_id
+WHERE pe.user_id = $1 AND pe.was_skipped = false
+`
+
+type CountListeningSignalForUserRow struct {
+	DistinctTracks  int64
+	DistinctArtists int64
+}
+
+// "You might like" Home rows (#790). The daily build computes ranked
+// album/artist IDs in Go (similarity roll-up + cold-start gate) and
+// atomic-replaces them here; /api/home reads them back hydrated.
+// Cold-start gate. Returns the breadth of the user's real listening:
+// distinct unskipped tracks played and distinct artists played. The
+// build skips You-might-like entirely below a threshold (a thin history
+// yields near-random roll-ups). was_skipped=false so a user spamming
+// next can't inflate the signal.
+func (q *Queries) CountListeningSignalForUser(ctx context.Context, userID pgtype.UUID) (CountListeningSignalForUserRow, error) {
+	row := q.db.QueryRow(ctx, countListeningSignalForUser, userID)
+	var i CountListeningSignalForUserRow
+	err := row.Scan(&i.DistinctTracks, &i.DistinctArtists)
+	return i, err
+}
+
+const deleteYouMightLikeAlbumsForUser = `-- name: DeleteYouMightLikeAlbumsForUser :exec
+DELETE FROM you_might_like_albums WHERE user_id = $1
+`
+
+func (q *Queries) DeleteYouMightLikeAlbumsForUser(ctx context.Context, userID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteYouMightLikeAlbumsForUser, userID)
+	return err
+}
+
+const deleteYouMightLikeArtistsForUser = `-- name: DeleteYouMightLikeArtistsForUser :exec
+DELETE FROM you_might_like_artists WHERE user_id = $1
+`
+
+func (q *Queries) DeleteYouMightLikeArtistsForUser(ctx context.Context, userID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteYouMightLikeArtistsForUser, userID)
+	return err
+}
+
+const insertYouMightLikeAlbum = `-- name: InsertYouMightLikeAlbum :exec
+INSERT INTO you_might_like_albums (user_id, album_id, rank)
+VALUES ($1, $2, $3)
+`
+
+type InsertYouMightLikeAlbumParams struct {
+	UserID  pgtype.UUID
+	AlbumID pgtype.UUID
+	Rank    int32
+}
+
+func (q *Queries) InsertYouMightLikeAlbum(ctx context.Context, arg InsertYouMightLikeAlbumParams) error {
+	_, err := q.db.Exec(ctx, insertYouMightLikeAlbum, arg.UserID, arg.AlbumID, arg.Rank)
+	return err
+}
+
+const insertYouMightLikeArtist = `-- name: InsertYouMightLikeArtist :exec
+INSERT INTO you_might_like_artists (user_id, artist_id, rank)
+VALUES ($1, $2, $3)
+`
+
+type InsertYouMightLikeArtistParams struct {
+	UserID   pgtype.UUID
+	ArtistID pgtype.UUID
+	Rank     int32
+}
+
+func (q *Queries) InsertYouMightLikeArtist(ctx context.Context, arg InsertYouMightLikeArtistParams) error {
+	_, err := q.db.Exec(ctx, insertYouMightLikeArtist, arg.UserID, arg.ArtistID, arg.Rank)
+	return err
+}
+
+const listYouMightLikeAlbumsForUser = `-- name: ListYouMightLikeAlbumsForUser :many
+SELECT albums.id, albums.title, albums.sort_title, albums.artist_id, albums.release_date, albums.mbid, albums.cover_art_path, albums.created_at, albums.updated_at, albums.cover_art_source, albums.cover_art_sources_version, artists.name AS artist_name
+FROM you_might_like_albums yml
+JOIN albums  ON albums.id  = yml.album_id
+JOIN artists ON artists.id = albums.artist_id
+WHERE yml.user_id = $1
+ORDER BY yml.rank
+LIMIT $2
+`
+
+type ListYouMightLikeAlbumsForUserParams struct {
+	UserID pgtype.UUID
+	Limit  int32
+}
+
+type ListYouMightLikeAlbumsForUserRow struct {
+	Album      Album
+	ArtistName string
+}
+
+// Read path. Same projection as ListRediscoverAlbumsForUser so the API
+// layer reuses albumRefFrom(row.Album, row.ArtistName, …). Ordered by
+// the rank persisted at build time. Final cross-section dedup (vs Most
+// Played / Rediscover) and the output cap land in the Go layer
+// (internal/recommendation/home.go).
+func (q *Queries) ListYouMightLikeAlbumsForUser(ctx context.Context, arg ListYouMightLikeAlbumsForUserParams) ([]ListYouMightLikeAlbumsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listYouMightLikeAlbumsForUser, arg.UserID, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListYouMightLikeAlbumsForUserRow
+	for rows.Next() {
+		var i ListYouMightLikeAlbumsForUserRow
+		if err := rows.Scan(
+			&i.Album.ID,
+			&i.Album.Title,
+			&i.Album.SortTitle,
+			&i.Album.ArtistID,
+			&i.Album.ReleaseDate,
+			&i.Album.Mbid,
+			&i.Album.CoverArtPath,
+			&i.Album.CreatedAt,
+			&i.Album.UpdatedAt,
+			&i.Album.CoverArtSource,
+			&i.Album.CoverArtSourcesVersion,
+			&i.ArtistName,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listYouMightLikeArtistsForUser = `-- name: ListYouMightLikeArtistsForUser :many
+SELECT artists.id, artists.name, artists.sort_name, artists.mbid, artists.created_at, artists.updated_at, artists.artist_thumb_path, artists.artist_fanart_path, artists.artist_art_source, artists.artist_art_sources_version,
+       cov.id AS cover_album_id,
+       cnt.album_count::bigint AS album_count
+FROM you_might_like_artists yml
+JOIN artists ON artists.id = yml.artist_id
+LEFT JOIN LATERAL (
+    SELECT id FROM albums
+    WHERE artist_id = artists.id AND cover_art_path IS NOT NULL
+    ORDER BY created_at DESC LIMIT 1
+) cov ON true
+LEFT JOIN LATERAL (
+    SELECT count(*) AS album_count
+    FROM albums WHERE artist_id = artists.id
+) cnt ON true
+WHERE yml.user_id = $1
+ORDER BY yml.rank
+LIMIT $2
+`
+
+type ListYouMightLikeArtistsForUserParams struct {
+	UserID pgtype.UUID
+	Limit  int32
+}
+
+type ListYouMightLikeArtistsForUserRow struct {
+	Artist       Artist
+	CoverAlbumID pgtype.UUID
+	AlbumCount   int64
+}
+
+// Read path. Same projection as ListRediscoverArtistsForUser (embeds the
+// artist + a representative cover_album_id + album_count) so the API
+// layer reuses artistRefFromCovered. Ordered by persisted rank.
+func (q *Queries) ListYouMightLikeArtistsForUser(ctx context.Context, arg ListYouMightLikeArtistsForUserParams) ([]ListYouMightLikeArtistsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listYouMightLikeArtistsForUser, arg.UserID, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListYouMightLikeArtistsForUserRow
+	for rows.Next() {
+		var i ListYouMightLikeArtistsForUserRow
+		if err := rows.Scan(
+			&i.Artist.ID,
+			&i.Artist.Name,
+			&i.Artist.SortName,
+			&i.Artist.Mbid,
+			&i.Artist.CreatedAt,
+			&i.Artist.UpdatedAt,
+			&i.Artist.ArtistThumbPath,
+			&i.Artist.ArtistFanartPath,
+			&i.Artist.ArtistArtSource,
+			&i.Artist.ArtistArtSourcesVersion,
+			&i.CoverAlbumID,
+			&i.AlbumCount,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}

internal/db/migrations/0033_drop_scan_schedule.down.sql

@@ -0,0 +1,21 @@
+-- Recreate the scan_schedule singleton (mirror of 0019) so the drop is
+-- reversible. The application no longer reads or writes this table.
+CREATE TABLE scan_schedule (
+    id             boolean PRIMARY KEY DEFAULT true,
+    mode           text NOT NULL DEFAULT 'off',
+    interval_hours int,
+    time_of_day    text,
+    weekly_day     int,
+    updated_at     timestamptz NOT NULL DEFAULT now(),
+    CONSTRAINT scan_schedule_singleton CHECK (id = true),
+    CONSTRAINT scan_schedule_mode_check
+        CHECK (mode IN ('off', 'interval', 'daily', 'weekly')),
+    CONSTRAINT scan_schedule_interval_check
+        CHECK (mode != 'interval' OR (interval_hours IS NOT NULL AND interval_hours > 0)),
+    CONSTRAINT scan_schedule_daily_check
+        CHECK (mode != 'daily' OR time_of_day IS NOT NULL),
+    CONSTRAINT scan_schedule_weekly_check
+        CHECK (mode != 'weekly' OR (time_of_day IS NOT NULL AND weekly_day IS NOT NULL AND weekly_day BETWEEN 1 AND 7))
+);
+
+INSERT INTO scan_schedule (id) VALUES (true);

internal/db/migrations/0033_drop_scan_schedule.up.sql

@@ -0,0 +1,4 @@
+-- Retire the configurable scan scheduler. New-file pickup is now handled by
+-- the fsnotify watcher + a hardcoded safety-net delta walk (cmd/minstrel),
+-- so the operator-configurable schedule (and its admin UI) is gone.
+DROP TABLE IF EXISTS scan_schedule;

internal/db/migrations/0034_you_might_like.down.sql

@@ -0,0 +1,3 @@
+-- Reverse 0034_you_might_like.up.sql.
+DROP TABLE IF EXISTS you_might_like_artists;
+DROP TABLE IF EXISTS you_might_like_albums;

internal/db/migrations/0034_you_might_like.up.sql

@@ -0,0 +1,36 @@
+-- 0034_you_might_like.up.sql — "You might like" Home rows (#790).
+--
+-- Per-user ranked lists of IN-LIBRARY albums/artists the listener
+-- doesn't actively spin but is predicted to enjoy, derived from the
+-- same similarity + like-weighted candidate engine that powers For-You
+-- (rolled up from track scores to album/artist). Built in the daily
+-- 3am BuildSystemPlaylists pass and atomic-replaced, exactly like the
+-- system playlists; read back by /api/home.
+--
+-- Two thin tables (id + rank) rather than denormalized snapshots: the
+-- Home read path hydrates album/artist refs through the existing
+-- albums/artists joins, so a later metadata edit is reflected without
+-- a rebuild. CASCADE on user/album/artist deletes keeps them clean.
+
+CREATE TABLE you_might_like_albums (
+    user_id   uuid        NOT NULL REFERENCES users(id)  ON DELETE CASCADE,
+    album_id  uuid        NOT NULL REFERENCES albums(id) ON DELETE CASCADE,
+    rank      integer     NOT NULL,
+    built_at  timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, album_id)
+);
+
+-- Read path orders by rank within a user; the index serves it directly.
+CREATE INDEX you_might_like_albums_user_rank_idx
+    ON you_might_like_albums (user_id, rank);
+
+CREATE TABLE you_might_like_artists (
+    user_id    uuid        NOT NULL REFERENCES users(id)   ON DELETE CASCADE,
+    artist_id  uuid        NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
+    rank       integer     NOT NULL,
+    built_at   timestamptz NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, artist_id)
+);
+
+CREATE INDEX you_might_like_artists_user_rank_idx
+    ON you_might_like_artists (user_id, rank);

internal/db/migrations/0035_taste_profile.down.sql

@@ -0,0 +1,3 @@
+-- Reverse 0035_taste_profile.up.sql.
+DROP TABLE IF EXISTS taste_profile_tags;
+DROP TABLE IF EXISTS taste_profile_artists;

internal/db/migrations/0035_taste_profile.up.sql

@@ -0,0 +1,33 @@
+-- 0035_taste_profile.up.sql — per-user taste profile (#796 phase 1).
+--
+-- A persistent, decaying model of each user's taste, rebuilt daily from
+-- graded play engagement (completion + skip position) plus explicit
+-- likes. Two facet tables: weighted artists and weighted genre tags.
+-- Weight is a signed float — positive = drawn to, negative = (passively)
+-- avoided; magnitude reflects decayed engagement. Phase 1 only BUILDS
+-- these; consumption (candidate sourcing + scoring) lands in phase 2.
+--
+-- CASCADE on user/artist deletes keeps them clean. Indexed by
+-- (user_id, weight DESC) to serve "top taste artists/tags" reads cheaply.
+
+CREATE TABLE taste_profile_artists (
+    user_id    uuid             NOT NULL REFERENCES users(id)   ON DELETE CASCADE,
+    artist_id  uuid             NOT NULL REFERENCES artists(id) ON DELETE CASCADE,
+    weight     double precision NOT NULL,
+    updated_at timestamptz      NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, artist_id)
+);
+
+CREATE INDEX taste_profile_artists_user_weight_idx
+    ON taste_profile_artists (user_id, weight DESC);
+
+CREATE TABLE taste_profile_tags (
+    user_id    uuid             NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    tag        text             NOT NULL,
+    weight     double precision NOT NULL,
+    updated_at timestamptz      NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, tag)
+);
+
+CREATE INDEX taste_profile_tags_user_weight_idx
+    ON taste_profile_tags (user_id, weight DESC);

internal/db/queries/recommendation.sql

@@ -231,6 +231,32 @@ WHERE NOT EXISTS (
 ORDER BY p.cnt DESC, t.id
 LIMIT $2;
 
+-- name: ListMostPlayedTracksForArtist :many
+-- Top tracks for one artist by this user's completed-play count (skips
+-- excluded, quarantine filtered). Same projection as
+-- ListMostPlayedTracksForUser plus an artist_id filter, so the handler
+-- reuses trackRefFrom(row.Track, row.AlbumTitle, row.ArtistName).
+WITH plays AS (
+    SELECT track_id, count(*) AS cnt
+    FROM play_events
+    WHERE user_id = sqlc.arg(user_id) AND was_skipped = false
+    GROUP BY track_id
+)
+SELECT sqlc.embed(t),
+       albums.title AS album_title,
+       artists.name AS artist_name
+FROM plays p
+JOIN tracks t   ON t.id = p.track_id
+JOIN albums     ON albums.id  = t.album_id
+JOIN artists    ON artists.id = t.artist_id
+WHERE t.artist_id = sqlc.arg(artist_id)
+  AND NOT EXISTS (
+      SELECT 1 FROM lidarr_quarantine q
+      WHERE q.user_id = sqlc.arg(user_id) AND q.track_id = t.id
+  )
+ORDER BY p.cnt DESC, t.id
+LIMIT sqlc.arg(result_limit);
+
 -- name: ListLastPlayedArtistsForUser :many
 -- M6a: artists ranked by max(play_events.started_at) for the user, with
 -- a derived cover_album_id via a representative-album lateral join (most

internal/db/queries/scan_schedule.sql

@@ -1,18 +0,0 @@
--- name: GetScanSchedule :one
--- M7 recurring-scans: returns the singleton schedule row. Used by the
--- scheduler goroutine on boot and config-refresh, and by the admin GET
--- handler.
-SELECT mode, interval_hours, time_of_day, weekly_day, updated_at
-  FROM scan_schedule WHERE id = true;
-
--- name: UpdateScanSchedule :exec
--- Admin PATCH replaces the whole row; CHECK constraints enforce validity.
--- The application normalizes mode='off' to NULL the per-mode fields
--- before calling this.
-UPDATE scan_schedule
-   SET mode           = $1,
-       interval_hours = $2,
-       time_of_day    = $3,
-       weekly_day     = $4,
-       updated_at     = now()
- WHERE id = true;

internal/db/queries/similarity.sql

@@ -60,3 +60,29 @@ ON CONFLICT (seed_artist_id, candidate_mbid, source) DO UPDATE SET
     candidate_name = EXCLUDED.candidate_name,
     score          = EXCLUDED.score,
     fetched_at     = now();
+
+-- name: ListSimilarArtistsForArtist :many
+-- In-library artists similar to a seed artist, ranked by best similarity
+-- score across sources (deduped per candidate). cover_album_id + album_count
+-- mirror ListArtistsAlphaWithCovers so the strip renders identical cards.
+SELECT sqlc.embed(artists),
+       cov.id AS cover_album_id,
+       cnt.album_count::bigint AS album_count
+FROM (
+    SELECT artist_b_id, max(score) AS sim_score
+    FROM artist_similarity
+    WHERE artist_a_id = sqlc.arg(seed_artist_id)
+    GROUP BY artist_b_id
+) s
+JOIN artists ON artists.id = s.artist_b_id
+LEFT JOIN LATERAL (
+    SELECT id FROM albums
+    WHERE artist_id = artists.id AND cover_art_path IS NOT NULL
+    ORDER BY created_at DESC LIMIT 1
+) cov ON true
+LEFT JOIN LATERAL (
+    SELECT count(*) AS album_count
+    FROM albums WHERE artist_id = artists.id
+) cnt ON true
+ORDER BY s.sim_score DESC, artists.sort_name
+LIMIT sqlc.arg(result_limit);

internal/db/queries/taste_profile.sql

@@ -0,0 +1,66 @@
+-- Taste profile (#796 phase 1). The daily build computes signed artist/tag
+-- weights in Go (graded engagement + decay + like bonus) and atomic-replaces
+-- them here. Read queries serve "top taste" lookups (used in phase 2).
+
+-- name: ListPlayEngagementInputsForUser :many
+-- One row per play in the decay-relevant window. completion is the play's
+-- completion ratio (precomputed column when present, else duration_played /
+-- track duration, clamped to [0,1]); age_days drives the time-decay. Genre
+-- is split into tags in Go. Quarantined tracks are excluded.
+SELECT
+    t.artist_id,
+    t.genre,
+    LEAST(GREATEST(
+        COALESCE(pe.completion_ratio,
+                 pe.duration_played_ms::float8 / NULLIF(t.duration_ms, 0),
+                 0), 0), 1)::float8 AS completion,
+    (EXTRACT(epoch FROM now() - pe.started_at) / 86400.0)::float8 AS age_days
+FROM play_events pe
+JOIN tracks t ON t.id = pe.track_id
+WHERE pe.user_id = $1
+  AND pe.started_at > now() - ($2::float8 * INTERVAL '1 day')
+  AND NOT EXISTS (
+      SELECT 1 FROM lidarr_quarantine q
+      WHERE q.user_id = $1 AND q.track_id = t.id
+  );
+
+-- name: ListLikedTrackTasteInputsForUser :many
+-- (artist_id, genre) for each track the user has explicitly liked. Feeds the
+-- track-like bonus into the liked track's artist and tags.
+SELECT t.artist_id, t.genre
+FROM general_likes gl
+JOIN tracks t ON t.id = gl.track_id
+WHERE gl.user_id = $1;
+
+-- name: ListLikedArtistIDsForUser :many
+-- Artists the user has explicitly liked; feeds the artist-like bonus.
+SELECT artist_id FROM general_likes_artists WHERE user_id = $1;
+
+-- name: DeleteTasteProfileArtistsForUser :exec
+DELETE FROM taste_profile_artists WHERE user_id = $1;
+
+-- name: InsertTasteProfileArtist :exec
+INSERT INTO taste_profile_artists (user_id, artist_id, weight)
+VALUES ($1, $2, $3);
+
+-- name: DeleteTasteProfileTagsForUser :exec
+DELETE FROM taste_profile_tags WHERE user_id = $1;
+
+-- name: InsertTasteProfileTag :exec
+INSERT INTO taste_profile_tags (user_id, tag, weight)
+VALUES ($1, $2, $3);
+
+-- name: ListTasteProfileArtistsForUser :many
+-- Top-weighted taste artists (phase-2 consumption + tests).
+SELECT artist_id, weight
+FROM taste_profile_artists
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2;
+
+-- name: ListTasteProfileTagsForUser :many
+SELECT tag, weight
+FROM taste_profile_tags
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2;

internal/db/queries/you_might_like.sql

@@ -0,0 +1,66 @@
+-- "You might like" Home rows (#790). The daily build computes ranked
+-- album/artist IDs in Go (similarity roll-up + cold-start gate) and
+-- atomic-replaces them here; /api/home reads them back hydrated.
+
+-- name: CountListeningSignalForUser :one
+-- Cold-start gate. Returns the breadth of the user's real listening:
+-- distinct unskipped tracks played and distinct artists played. The
+-- build skips You-might-like entirely below a threshold (a thin history
+-- yields near-random roll-ups). was_skipped=false so a user spamming
+-- next can't inflate the signal.
+SELECT
+    count(DISTINCT pe.track_id)::bigint AS distinct_tracks,
+    count(DISTINCT t.artist_id)::bigint AS distinct_artists
+FROM play_events pe
+JOIN tracks t ON t.id = pe.track_id
+WHERE pe.user_id = $1 AND pe.was_skipped = false;
+
+-- name: DeleteYouMightLikeAlbumsForUser :exec
+DELETE FROM you_might_like_albums WHERE user_id = $1;
+
+-- name: InsertYouMightLikeAlbum :exec
+INSERT INTO you_might_like_albums (user_id, album_id, rank)
+VALUES ($1, $2, $3);
+
+-- name: DeleteYouMightLikeArtistsForUser :exec
+DELETE FROM you_might_like_artists WHERE user_id = $1;
+
+-- name: InsertYouMightLikeArtist :exec
+INSERT INTO you_might_like_artists (user_id, artist_id, rank)
+VALUES ($1, $2, $3);
+
+-- name: ListYouMightLikeAlbumsForUser :many
+-- Read path. Same projection as ListRediscoverAlbumsForUser so the API
+-- layer reuses albumRefFrom(row.Album, row.ArtistName, …). Ordered by
+-- the rank persisted at build time. Final cross-section dedup (vs Most
+-- Played / Rediscover) and the output cap land in the Go layer
+-- (internal/recommendation/home.go).
+SELECT sqlc.embed(albums), artists.name AS artist_name
+FROM you_might_like_albums yml
+JOIN albums  ON albums.id  = yml.album_id
+JOIN artists ON artists.id = albums.artist_id
+WHERE yml.user_id = $1
+ORDER BY yml.rank
+LIMIT $2;
+
+-- name: ListYouMightLikeArtistsForUser :many
+-- Read path. Same projection as ListRediscoverArtistsForUser (embeds the
+-- artist + a representative cover_album_id + album_count) so the API
+-- layer reuses artistRefFromCovered. Ordered by persisted rank.
+SELECT sqlc.embed(artists),
+       cov.id AS cover_album_id,
+       cnt.album_count::bigint AS album_count
+FROM you_might_like_artists yml
+JOIN artists ON artists.id = yml.artist_id
+LEFT JOIN LATERAL (
+    SELECT id FROM albums
+    WHERE artist_id = artists.id AND cover_art_path IS NOT NULL
+    ORDER BY created_at DESC LIMIT 1
+) cov ON true
+LEFT JOIN LATERAL (
+    SELECT count(*) AS album_count
+    FROM albums WHERE artist_id = artists.id
+) cnt ON true
+WHERE yml.user_id = $1
+ORDER BY yml.rank
+LIMIT $2;

internal/library/scanner.go

@@ -87,7 +87,7 @@ func (s *Scanner) Scan(ctx context.Context, progressCb func(Stats)) (Stats, erro
 			if !audioExtensions[strings.ToLower(filepath.Ext(path))] {
 				return nil
 			}
-			if err := s.scanFile(ctx, q, path, &stats); err != nil {
+			if _, _, err := s.scanFile(ctx, q, path, &stats); err != nil {
 				s.logger.Warn("library scan file error", "path", path, "err", err)
 				stats.Errored++
 			}
@@ -114,19 +114,24 @@ func (s *Scanner) Scan(ctx context.Context, progressCb func(Stats)) (Stats, erro
 	return stats, nil
 }
 
-func (s *Scanner) scanFile(ctx context.Context, q *dbq.Queries, path string, stats *Stats) error {
+// scanFile upserts a single audio file. Returns the album ID the track
+// belongs to and whether the file was added/updated (false = skipped as
+// unchanged), so watcher-driven callers can enrich just the changed albums.
+func (s *Scanner) scanFile(
+	ctx context.Context, q *dbq.Queries, path string, stats *Stats,
+) (pgtype.UUID, bool, error) {
 	stats.Scanned++
 
 	info, err := os.Stat(path)
 	if err != nil {
-		return fmt.Errorf("stat: %w", err)
+		return pgtype.UUID{}, false, fmt.Errorf("stat: %w", err)
 	}
 	mtime := info.ModTime()
 
 	existing, err := q.GetTrackByPath(ctx, path)
 	knownTrack := err == nil
 	if err != nil && !errors.Is(err, pgx.ErrNoRows) {
-		return fmt.Errorf("lookup: %w", err)
+		return pgtype.UUID{}, false, fmt.Errorf("lookup: %w", err)
 	}
 	// Incremental skip: only when the file hasn't changed AND we already have
 	// a real duration. The second clause lets older scans that recorded
@@ -135,18 +140,18 @@ func (s *Scanner) scanFile(ctx context.Context, q *dbq.Queries, path string, sta
 	// scans short-circuit as before.
 	if knownTrack && !existing.UpdatedAt.Time.Before(mtime) && existing.DurationMs > 0 {
 		stats.Skipped++
-		return nil
+		return pgtype.UUID{}, false, nil
 	}
 
 	f, err := os.Open(path)
 	if err != nil {
-		return fmt.Errorf("open: %w", err)
+		return pgtype.UUID{}, false, fmt.Errorf("open: %w", err)
 	}
 	defer func() { _ = f.Close() }()
 
 	meta, err := tag.ReadFrom(f)
 	if err != nil {
-		return fmt.Errorf("tag read: %w", err)
+		return pgtype.UUID{}, false, fmt.Errorf("tag read: %w", err)
 	}
 	albumMBID, artistMBID := extractMBIDs(meta)
 	recordingMBID := extractRecordingMBID(meta)
@@ -166,11 +171,11 @@ func (s *Scanner) scanFile(ctx context.Context, q *dbq.Queries, path string, sta
 
 	artist, err := s.resolveArtist(ctx, q, artistName, artistMBID)
 	if err != nil {
-		return fmt.Errorf("artist: %w", err)
+		return pgtype.UUID{}, false, fmt.Errorf("artist: %w", err)
 	}
 	album, err := s.resolveAlbum(ctx, q, artist.ID, albumTitle, meta.Year(), albumMBID)
 	if err != nil {
-		return fmt.Errorf("album: %w", err)
+		return pgtype.UUID{}, false, fmt.Errorf("album: %w", err)
 	}
 
 	trackNum, _ := meta.Track()
@@ -213,7 +218,7 @@ func (s *Scanner) scanFile(ctx context.Context, q *dbq.Queries, path string, sta
 
 	track, err := q.UpsertTrack(ctx, params)
 	if err != nil {
-		return fmt.Errorf("upsert track: %w", err)
+		return pgtype.UUID{}, false, fmt.Errorf("upsert track: %w", err)
 	}
 	if err := syncpkg.LogChange(ctx, s.pool, syncpkg.EntityTrack,
 		syncpkg.FormatUUID(track.ID), syncpkg.OpUpsert); err != nil {
@@ -227,7 +232,47 @@ func (s *Scanner) scanFile(ctx context.Context, q *dbq.Queries, path string, sta
 	} else {
 		stats.Added++
 	}
-	return nil
+	return album.ID, true, nil
+}
+
+// ScanFiles processes a specific set of audio file paths (watcher-driven),
+// applying the same upsert + delta-skip logic as a full Scan. Non-audio or
+// unreadable paths are skipped (logged), never fatal. Returns the distinct
+// album IDs whose tracks were added or updated, so the caller can enrich
+// just those albums inline rather than waiting for a batch pass.
+func (s *Scanner) ScanFiles(ctx context.Context, paths []string) ([]pgtype.UUID, error) {
+	q := dbq.New(s.pool)
+	seen := make(map[[16]byte]struct{})
+	changed := make([]pgtype.UUID, 0)
+	var stats Stats
+	for _, path := range paths {
+		if ctx.Err() != nil {
+			return changed, ctx.Err()
+		}
+		if !audioExtensions[strings.ToLower(filepath.Ext(path))] {
+			continue
+		}
+		albumID, didChange, err := s.scanFile(ctx, q, path, &stats)
+		if err != nil {
+			s.logger.Warn("library watch: scan file error", "path", path, "err", err)
+			continue
+		}
+		if didChange && albumID.Valid {
+			if _, ok := seen[albumID.Bytes]; !ok {
+				seen[albumID.Bytes] = struct{}{}
+				changed = append(changed, albumID)
+			}
+		}
+	}
+	if stats.Added > 0 || stats.Updated > 0 {
+		s.logger.Info("library watch: scan batch",
+			"added", stats.Added,
+			"updated", stats.Updated,
+			"skipped", stats.Skipped,
+			"errored", stats.Errored,
+		)
+	}
+	return changed, nil
 }
 
 func (s *Scanner) resolveArtist(ctx context.Context, q *dbq.Queries, name, mbid string) (dbq.Artist, error) {

internal/library/scanner_test.go

@@ -121,6 +121,45 @@ func TestScanner_Integration(t *testing.T) {
 	if stats2.Added != 0 || stats2.Updated != 0 || stats2.Skipped != 4 {
 		t.Errorf("incremental scan stats = %+v, want Skipped=4", stats2)
 	}
+
+	// ScanFiles (watcher-driven targeted scan): a newly-added file is picked
+	// up by path without walking the whole tree, and its album ID is returned
+	// so the watcher can enrich just that album. A non-audio path in the batch
+	// is silently ignored.
+	newFile := filepath.Join(root, "artistX/albumA/03.mp3")
+	writeTestMP3(t, newFile, map[string]string{
+		"TIT2": "Track Three", "TPE1": "Artist X", "TALB": "Album A", "TRCK": "3", "TYER": "2020",
+	})
+	notAudio := filepath.Join(root, "artistX/albumA/cover.txt")
+	if err := os.WriteFile(notAudio, []byte("nope"), 0o644); err != nil {
+		t.Fatalf("write non-audio: %v", err)
+	}
+	changed, err := scanner.ScanFiles(ctx, []string{newFile, notAudio})
+	if err != nil {
+		t.Fatalf("ScanFiles: %v", err)
+	}
+	if len(changed) != 1 || !changed[0].Valid {
+		t.Fatalf("ScanFiles changed albums = %+v, want exactly 1 valid", changed)
+	}
+
+	// The targeted scan upserts only the named file; the rest of the library
+	// is untouched (no full walk).
+	if _, err := q.GetTrackByPath(ctx, newFile); err != nil {
+		t.Fatalf("GetTrackByPath after ScanFiles: %v", err)
+	}
+
+	// Re-running ScanFiles on the now-unchanged file (duration probed) skips it,
+	// so no album is reported as changed.
+	if _, err := pool.Exec(ctx, "UPDATE tracks SET duration_ms = 1000 WHERE duration_ms = 0"); err != nil {
+		t.Fatalf("seed durations (2): %v", err)
+	}
+	changed2, err := scanner.ScanFiles(ctx, []string{newFile})
+	if err != nil {
+		t.Fatalf("ScanFiles (rescan): %v", err)
+	}
+	if len(changed2) != 0 {
+		t.Errorf("ScanFiles on unchanged file changed = %+v, want none", changed2)
+	}
 }
 
 // writeTestMP3 emits a file with only an ID3v2.3 tag payload plus a few

internal/library/scheduler.go

@@ -1,238 +0,0 @@
-package library
-
-import (
-	"context"
-	"log/slog"
-	"sync"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-
-	"git.fabledsword.com/bvandeusen/minstrel/internal/coverart"
-	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
-)
-
-// ScheduleConfig represents the operator's recurring scan schedule.
-// Loaded from the scan_schedule singleton row on boot and on Refresh.
-type ScheduleConfig struct {
-	Mode          string // "off" | "interval" | "daily" | "weekly"
-	IntervalHours int
-	TimeOfDay     string // "HH:MM" (24h)
-	WeeklyDay     int    // 1..7 (Mon..Sun, ISO 8601)
-}
-
-// NextFire returns the next time the scan should fire given a reference
-// "now". Returns zero time when mode == "off" or config is invalid.
-//
-// DST semantics: "daily 02:30" on a spring-forward day will fire at the
-// computed time using the local zone's rules (Go time.Date silently
-// normalizes a non-existent local time). Single-operator scale; documented
-// as known and acceptable.
-func (c ScheduleConfig) NextFire(now time.Time) time.Time {
-	switch c.Mode {
-	case "off":
-		return time.Time{}
-	case "interval":
-		if c.IntervalHours <= 0 {
-			return time.Time{}
-		}
-		return now.Add(time.Duration(c.IntervalHours) * time.Hour)
-	case "daily":
-		h, m, ok := parseHHMM(c.TimeOfDay)
-		if !ok {
-			return time.Time{}
-		}
-		next := time.Date(now.Year(), now.Month(), now.Day(), h, m, 0, 0, now.Location())
-		if !next.After(now) {
-			next = next.AddDate(0, 0, 1)
-		}
-		return next
-	case "weekly":
-		h, m, ok := parseHHMM(c.TimeOfDay)
-		if !ok || c.WeeklyDay < 1 || c.WeeklyDay > 7 {
-			return time.Time{}
-		}
-		// Map ISO weekday (1=Mon..7=Sun) to Go's time.Weekday (0=Sun..6=Sat).
-		targetGoDow := c.WeeklyDay % 7
-		nowGoDow := int(now.Weekday())
-		daysAhead := (targetGoDow - nowGoDow + 7) % 7
-		next := time.Date(now.Year(), now.Month(), now.Day(), h, m, 0, 0, now.Location())
-		next = next.AddDate(0, 0, daysAhead)
-		if !next.After(now) {
-			next = next.AddDate(0, 0, 7)
-		}
-		return next
-	}
-	return time.Time{}
-}
-
-func parseHHMM(s string) (h, m int, ok bool) {
-	if len(s) != 5 || s[2] != ':' {
-		return 0, 0, false
-	}
-	for i, c := range s {
-		if i == 2 {
-			continue
-		}
-		if c < '0' || c > '9' {
-			return 0, 0, false
-		}
-	}
-	h = int(s[0]-'0')*10 + int(s[1]-'0')
-	m = int(s[3]-'0')*10 + int(s[4]-'0')
-	if h < 0 || h > 23 || m < 0 || m > 59 {
-		return 0, 0, false
-	}
-	return h, m, true
-}
-
-// Scheduler runs in a goroutine and triggers RunScan on the operator's
-// configured cadence via library.TryStartScan (which handles in-flight
-// conflicts and stale-row reaping).
-type Scheduler struct {
-	pool     *pgxpool.Pool
-	logger   *slog.Logger
-	scanner  *Scanner
-	enricher *coverart.Enricher
-	scanCfg  RunScanConfig
-
-	mu       sync.RWMutex
-	cfg      ScheduleConfig
-	nextFire time.Time
-
-	refresh chan struct{}
-	stop    chan struct{}
-}
-
-func NewScheduler(pool *pgxpool.Pool, logger *slog.Logger,
-	scanner *Scanner, enricher *coverart.Enricher,
-	scanCfg RunScanConfig,
-) *Scheduler {
-	return &Scheduler{
-		pool: pool, logger: logger,
-		scanner: scanner, enricher: enricher, scanCfg: scanCfg,
-		refresh: make(chan struct{}, 1),
-		stop:    make(chan struct{}),
-	}
-}
-
-// Start launches the scheduler's loop goroutine. The loop runs until
-// the passed ctx is cancelled or Stop is called.
-func (s *Scheduler) Start(ctx context.Context) {
-	go s.loop(ctx)
-}
-
-// Stop signals the loop to exit. Not idempotent — call only once
-// (typically at server shutdown).
-func (s *Scheduler) Stop() { close(s.stop) }
-
-// Refresh signals the loop to reload config and recompute next-fire.
-// Non-blocking: additional Refresh calls coalesce on the buffered channel.
-func (s *Scheduler) Refresh() {
-	select {
-	case s.refresh <- struct{}{}:
-	default:
-	}
-}
-
-// NextFire returns the cached next-fire time. Zero when mode=off.
-func (s *Scheduler) NextFire() time.Time {
-	s.mu.RLock()
-	defer s.mu.RUnlock()
-	return s.nextFire
-}
-
-func (s *Scheduler) setState(cfg ScheduleConfig, next time.Time) {
-	s.mu.Lock()
-	s.cfg = cfg
-	s.nextFire = next
-	s.mu.Unlock()
-}
-
-func (s *Scheduler) loadConfig(ctx context.Context) (ScheduleConfig, error) {
-	q := dbq.New(s.pool)
-	row, err := q.GetScanSchedule(ctx)
-	if err != nil {
-		return ScheduleConfig{}, err
-	}
-	cfg := ScheduleConfig{Mode: row.Mode}
-	if row.IntervalHours != nil {
-		cfg.IntervalHours = int(*row.IntervalHours)
-	}
-	if row.TimeOfDay != nil {
-		cfg.TimeOfDay = *row.TimeOfDay
-	}
-	if row.WeeklyDay != nil {
-		cfg.WeeklyDay = int(*row.WeeklyDay)
-	}
-	return cfg, nil
-}
-
-func (s *Scheduler) loop(ctx context.Context) {
-	for {
-		cfg, err := s.loadConfig(ctx)
-		if err != nil {
-			s.logger.Error("scheduler: load config failed", "err", err)
-			retry := time.NewTimer(1 * time.Minute)
-			select {
-			case <-retry.C:
-			case <-s.refresh:
-				retry.Stop()
-			case <-s.stop:
-				retry.Stop()
-				return
-			case <-ctx.Done():
-				retry.Stop()
-				return
-			}
-			continue
-		}
-
-		next := cfg.NextFire(time.Now())
-		s.setState(cfg, next)
-
-		if next.IsZero() {
-			s.logger.Info("scheduler: mode=off, waiting for config change")
-			select {
-			case <-s.refresh:
-				continue
-			case <-s.stop:
-				return
-			case <-ctx.Done():
-				return
-			}
-		}
-
-		wait := time.Until(next)
-		s.logger.Info("scheduler: next scan scheduled", "at", next, "in", wait)
-		timer := time.NewTimer(wait)
-		select {
-		case <-timer.C:
-			s.tryFire(ctx)
-		case <-s.refresh:
-			timer.Stop()
-		case <-s.stop:
-			timer.Stop()
-			return
-		case <-ctx.Done():
-			timer.Stop()
-			return
-		}
-	}
-}
-
-func (s *Scheduler) tryFire(ctx context.Context) {
-	started, existing, err := TryStartScan(
-		ctx, s.pool, s.scanner, s.enricher,
-		s.logger.With("source", "scheduler"), s.scanCfg,
-	)
-	if err != nil {
-		s.logger.Error("scheduler: try start failed", "err", err)
-		return
-	}
-	if !started && existing != nil {
-		s.logger.Info("scheduler: scan skipped — prior still in flight",
-			"in_flight_id", existing.ID,
-			"in_flight_started_at", existing.StartedAt.Time)
-	}
-}

internal/library/scheduler_test.go

@@ -1,129 +0,0 @@
-package library
-
-import (
-	"testing"
-	"time"
-)
-
-func TestNextFire_Off(t *testing.T) {
-	c := ScheduleConfig{Mode: "off"}
-	if got := c.NextFire(time.Now()); !got.IsZero() {
-		t.Errorf("NextFire = %v, want zero time", got)
-	}
-}
-
-func TestNextFire_Interval(t *testing.T) {
-	c := ScheduleConfig{Mode: "interval", IntervalHours: 6}
-	now := time.Date(2026, 5, 6, 14, 0, 0, 0, time.UTC)
-	want := time.Date(2026, 5, 6, 20, 0, 0, 0, time.UTC)
-	if got := c.NextFire(now); !got.Equal(want) {
-		t.Errorf("NextFire = %v, want %v", got, want)
-	}
-}
-
-func TestNextFire_Daily_Tomorrow(t *testing.T) {
-	c := ScheduleConfig{Mode: "daily", TimeOfDay: "03:00"}
-	now := time.Date(2026, 5, 6, 14, 0, 0, 0, time.UTC)
-	want := time.Date(2026, 5, 7, 3, 0, 0, 0, time.UTC)
-	if got := c.NextFire(now); !got.Equal(want) {
-		t.Errorf("NextFire = %v, want %v", got, want)
-	}
-}
-
-func TestNextFire_Daily_Today(t *testing.T) {
-	c := ScheduleConfig{Mode: "daily", TimeOfDay: "03:00"}
-	now := time.Date(2026, 5, 6, 2, 0, 0, 0, time.UTC)
-	want := time.Date(2026, 5, 6, 3, 0, 0, 0, time.UTC)
-	if got := c.NextFire(now); !got.Equal(want) {
-		t.Errorf("NextFire = %v, want %v", got, want)
-	}
-}
-
-func TestNextFire_Weekly_UpcomingDay(t *testing.T) {
-	// Tuesday 2pm, schedule = Sunday (ISO 7) 03:00 → upcoming Sunday at 03:00.
-	c := ScheduleConfig{Mode: "weekly", WeeklyDay: 7, TimeOfDay: "03:00"}
-	now := time.Date(2026, 5, 5, 14, 0, 0, 0, time.UTC)  // 2026-05-05 = Tuesday
-	want := time.Date(2026, 5, 10, 3, 0, 0, 0, time.UTC) // 2026-05-10 = Sunday
-	if got := c.NextFire(now); !got.Equal(want) {
-		t.Errorf("NextFire = %v, want %v", got, want)
-	}
-}
-
-func TestNextFire_Weekly_TodayBeforeTime(t *testing.T) {
-	c := ScheduleConfig{Mode: "weekly", WeeklyDay: 2, TimeOfDay: "03:00"} // ISO 2 = Tuesday
-	now := time.Date(2026, 5, 5, 2, 0, 0, 0, time.UTC)
-	want := time.Date(2026, 5, 5, 3, 0, 0, 0, time.UTC)
-	if got := c.NextFire(now); !got.Equal(want) {
-		t.Errorf("NextFire = %v, want %v", got, want)
-	}
-}
-
-func TestNextFire_Weekly_TodayAfterTime(t *testing.T) {
-	c := ScheduleConfig{Mode: "weekly", WeeklyDay: 2, TimeOfDay: "03:00"}
-	now := time.Date(2026, 5, 5, 14, 0, 0, 0, time.UTC)
-	want := time.Date(2026, 5, 12, 3, 0, 0, 0, time.UTC)
-	if got := c.NextFire(now); !got.Equal(want) {
-		t.Errorf("NextFire = %v, want %v", got, want)
-	}
-}
-
-func TestNextFire_InvalidConfigs(t *testing.T) {
-	cases := []ScheduleConfig{
-		{Mode: "interval", IntervalHours: 0},
-		{Mode: "interval", IntervalHours: -1},
-		{Mode: "daily", TimeOfDay: "bad"},
-		{Mode: "daily", TimeOfDay: "25:00"},
-		{Mode: "weekly", TimeOfDay: "03:00", WeeklyDay: 0},
-		{Mode: "weekly", TimeOfDay: "03:00", WeeklyDay: 8},
-		{Mode: "unknown"},
-	}
-	now := time.Now()
-	for _, c := range cases {
-		if got := c.NextFire(now); !got.IsZero() {
-			t.Errorf("NextFire(%+v) = %v, want zero", c, got)
-		}
-	}
-}
-
-func TestParseHHMM(t *testing.T) {
-	cases := []struct {
-		in     string
-		h, m   int
-		wantOK bool
-	}{
-		{"03:00", 3, 0, true},
-		{"23:59", 23, 59, true},
-		{"00:00", 0, 0, true},
-		{"24:00", 0, 0, false},
-		{"23:60", 0, 0, false},
-		{"3:00", 0, 0, false},
-		{"03-00", 0, 0, false},
-		{"ab:cd", 0, 0, false},
-	}
-	for _, c := range cases {
-		h, m, ok := parseHHMM(c.in)
-		if ok != c.wantOK || (ok && (h != c.h || m != c.m)) {
-			t.Errorf("parseHHMM(%q) = (%d, %d, %v), want (%d, %d, %v)",
-				c.in, h, m, ok, c.h, c.m, c.wantOK)
-		}
-	}
-}
-
-func TestScheduler_Refresh_NonBlocking(t *testing.T) {
-	s := &Scheduler{
-		refresh: make(chan struct{}, 1),
-		stop:    make(chan struct{}),
-	}
-	s.Refresh()
-	done := make(chan struct{})
-	go func() {
-		s.Refresh()
-		s.Refresh()
-		close(done)
-	}()
-	select {
-	case <-done:
-	case <-time.After(100 * time.Millisecond):
-		t.Errorf("Refresh blocked when channel was full")
-	}
-}

internal/library/watcher.go

@@ -0,0 +1,249 @@
+package library
+
+import (
+	"context"
+	"io/fs"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/fsnotify/fsnotify"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/coverart"
+)
+
+// watcherDebounce is the quiet period after the last filesystem event before
+// the watcher processes the pending batch. Copying an album emits a burst of
+// write events; waiting for quiet coalesces the whole album into one scan.
+const watcherDebounce = 3 * time.Second
+
+// watchAction is the pure decision for a single filesystem event.
+type watchAction int
+
+const (
+	watchIgnore      watchAction = iota // not a relevant change
+	watchEnqueueFile                    // an audio file was created/written
+	watchScanDir                        // a directory appeared; scan it recursively
+)
+
+// classifyEvent decides what to do with a filesystem event, separated from I/O
+// so it is unit-testable. Only Create/Write matter (removals are not pruned
+// here -- see the watcher's design non-goals). A newly-created directory is
+// scanned recursively because fsnotify does not emit events for files that
+// already existed inside a directory that was moved/copied in wholesale.
+func classifyEvent(op fsnotify.Op, isDir, isAudio bool) watchAction {
+	if op&(fsnotify.Create|fsnotify.Write) == 0 {
+		return watchIgnore
+	}
+	if isDir {
+		if op&fsnotify.Create != 0 {
+			return watchScanDir
+		}
+		return watchIgnore
+	}
+	if isAudio {
+		return watchEnqueueFile
+	}
+	return watchIgnore
+}
+
+// Watcher delivers near-instant library updates by watching the scan roots
+// with fsnotify and scanning just the changed files (plus inline cover-art
+// enrichment for the affected albums), instead of waiting for a full scan.
+// It is recursive: a watch is added per directory, and new directories get a
+// watch as they appear. inotify watch-limit exhaustion on huge libraries is
+// logged, not fatal -- the periodic safety-net scan covers anything missed.
+type Watcher struct {
+	scanner  *Scanner
+	enricher *coverart.Enricher
+	logger   *slog.Logger
+	roots    []string
+	debounce time.Duration
+}
+
+func NewWatcher(
+	scanner *Scanner, enricher *coverart.Enricher, logger *slog.Logger, roots []string,
+) *Watcher {
+	return &Watcher{
+		scanner:  scanner,
+		enricher: enricher,
+		logger:   logger,
+		roots:    roots,
+		debounce: watcherDebounce,
+	}
+}
+
+// Run blocks until ctx is cancelled. Returns a non-nil error only when the
+// fsnotify watcher cannot be created at all; per-path watch failures and
+// fsnotify errors are logged and tolerated.
+func (w *Watcher) Run(ctx context.Context) error {
+	if len(w.roots) == 0 {
+		w.logger.Info("library watcher: no scan paths configured, watcher disabled")
+		return nil
+	}
+	fsw, err := fsnotify.NewWatcher()
+	if err != nil {
+		w.logger.Error("library watcher: create failed", "err", err)
+		return err
+	}
+	defer func() { _ = fsw.Close() }()
+
+	for _, root := range w.roots {
+		w.addRecursive(fsw, root)
+	}
+	w.logger.Info("library watcher: started", "roots", len(w.roots))
+
+	batches := make(chan []string, batchQueueDepth)
+	go w.processLoop(ctx, batches)
+	w.eventLoop(ctx, fsw, batches)
+	return nil
+}
+
+// eventLoop reads fsnotify events, coalesces them via a debounce timer, and
+// hands drained batches to the process loop. Returns on ctx cancellation.
+func (w *Watcher) eventLoop(ctx context.Context, fsw *fsnotify.Watcher, batches chan<- []string) {
+	pending := make(map[string]struct{})
+	timer := time.NewTimer(w.debounce)
+	timer.Stop()
+	var timerC <-chan time.Time
+	for {
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			w.logger.Info("library watcher: stopped")
+			return
+		case event, ok := <-fsw.Events:
+			if !ok {
+				return
+			}
+			if w.handleEvent(fsw, event, pending) {
+				timer.Reset(w.debounce)
+				timerC = timer.C
+			}
+		case err, ok := <-fsw.Errors:
+			if ok {
+				w.logger.Warn("library watcher: fsnotify error", "err", err)
+			}
+		case <-timerC:
+			timerC = nil
+			paths := drainPending(pending)
+			if len(paths) == 0 {
+				continue
+			}
+			select {
+			case batches <- paths:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}
+}
+
+// handleEvent applies one event to the pending set and reports whether the
+// debounce timer should be (re)armed.
+func (w *Watcher) handleEvent(
+	fsw *fsnotify.Watcher, event fsnotify.Event, pending map[string]struct{},
+) bool {
+	info, err := os.Stat(event.Name)
+	isDir := err == nil && info.IsDir()
+	isAudio := audioExtensions[strings.ToLower(filepath.Ext(event.Name))]
+	switch classifyEvent(event.Op, isDir, isAudio) {
+	case watchScanDir:
+		w.addRecursive(fsw, event.Name)
+		return w.enqueueDirAudio(event.Name, pending)
+	case watchEnqueueFile:
+		pending[event.Name] = struct{}{}
+		return true
+	case watchIgnore:
+		return false
+	default:
+		return false
+	}
+}
+
+// processLoop serializes batch processing so a slow remote enrichment never
+// blocks the fsnotify event loop.
+func (w *Watcher) processLoop(ctx context.Context, batches <-chan []string) {
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case paths, ok := <-batches:
+			if !ok {
+				return
+			}
+			w.process(ctx, paths)
+		}
+	}
+}
+
+// process scans the changed files then enriches just the affected albums.
+func (w *Watcher) process(ctx context.Context, paths []string) {
+	changed, err := w.scanner.ScanFiles(ctx, paths)
+	if err != nil {
+		w.logger.Warn("library watcher: scan batch failed", "err", err)
+	}
+	if w.enricher != nil {
+		for _, albumID := range changed {
+			if ctx.Err() != nil {
+				return
+			}
+			if eerr := w.enricher.EnrichAlbum(ctx, albumID); eerr != nil {
+				w.logger.Warn("library watcher: enrich album failed", "err", eerr)
+			}
+		}
+	}
+	if len(changed) > 0 {
+		w.logger.Info("library watcher: applied", "files", len(paths), "albums", len(changed))
+	}
+}
+
+// addRecursive adds an fsnotify watch for root and every subdirectory under it.
+// Per-directory failures (inotify limits, permissions) are logged and skipped.
+func (w *Watcher) addRecursive(fsw *fsnotify.Watcher, root string) {
+	_ = filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil || !d.IsDir() {
+			return nil //nolint:nilerr // tolerate unreadable subtrees
+		}
+		if aerr := fsw.Add(path); aerr != nil {
+			w.logger.Warn("library watcher: add watch failed", "path", path, "err", aerr)
+		}
+		return nil
+	})
+}
+
+// enqueueDirAudio enqueues every audio file under dir (used when a directory
+// appears wholesale, since fsnotify emits no events for its existing children).
+func (w *Watcher) enqueueDirAudio(dir string, pending map[string]struct{}) bool {
+	added := false
+	_ = filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return nil //nolint:nilerr // tolerate unreadable subtrees
+		}
+		if audioExtensions[strings.ToLower(filepath.Ext(path))] {
+			pending[path] = struct{}{}
+			added = true
+		}
+		return nil
+	})
+	return added
+}
+
+// drainPending returns the pending paths and clears the set.
+func drainPending(pending map[string]struct{}) []string {
+	if len(pending) == 0 {
+		return nil
+	}
+	paths := make([]string, 0, len(pending))
+	for p := range pending {
+		paths = append(paths, p)
+	}
+	clear(pending)
+	return paths
+}
+
+// batchQueueDepth bounds how many debounced batches can be in flight before the
+// event loop would block; generous since each batch is processed quickly.
+const batchQueueDepth = 16

internal/library/watcher_test.go

@@ -0,0 +1,59 @@
+package library
+
+import (
+	"sort"
+	"testing"
+
+	"github.com/fsnotify/fsnotify"
+)
+
+func TestClassifyEvent(t *testing.T) {
+	tests := []struct {
+		name    string
+		op      fsnotify.Op
+		isDir   bool
+		isAudio bool
+		want    watchAction
+	}{
+		{"create audio file enqueues", fsnotify.Create, false, true, watchEnqueueFile},
+		{"write audio file enqueues", fsnotify.Write, false, true, watchEnqueueFile},
+		{"create non-audio file ignored", fsnotify.Create, false, false, watchIgnore},
+		{"create directory scans it", fsnotify.Create, true, false, watchScanDir},
+		{"write on directory ignored", fsnotify.Write, true, false, watchIgnore},
+		{"remove audio file ignored (no pruning)", fsnotify.Remove, false, true, watchIgnore},
+		{"rename audio file ignored", fsnotify.Rename, false, true, watchIgnore},
+		{"chmod audio file ignored", fsnotify.Chmod, false, true, watchIgnore},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := classifyEvent(tt.op, tt.isDir, tt.isAudio); got != tt.want {
+				t.Fatalf("classifyEvent(%v, dir=%v, audio=%v) = %v, want %v",
+					tt.op, tt.isDir, tt.isAudio, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestDrainPending(t *testing.T) {
+	t.Run("empty set returns nil", func(t *testing.T) {
+		if got := drainPending(map[string]struct{}{}); got != nil {
+			t.Fatalf("drainPending(empty) = %v, want nil", got)
+		}
+	})
+
+	t.Run("returns paths and clears the set", func(t *testing.T) {
+		pending := map[string]struct{}{
+			"/music/a.mp3":  {},
+			"/music/b.flac": {},
+		}
+		got := drainPending(pending)
+		sort.Strings(got)
+		want := []string{"/music/a.mp3", "/music/b.flac"}
+		if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+			t.Fatalf("drainPending = %v, want %v", got, want)
+		}
+		if len(pending) != 0 {
+			t.Fatalf("pending not cleared: %v", pending)
+		}
+	})
+}

internal/playevents/writer.go

@@ -180,6 +180,12 @@ func (w *Writer) RecordPlayEnded(
 		if err != nil {
 			return err
 		}
+		// Idempotency for the client's durable close-by-id replay: if the
+		// row is already closed, re-applying the close is harmless (the
+		// UPDATE is last-write-wins) but a second skip_events insert must
+		// NOT fire — a lost-response retry would otherwise double the
+		// skip signal. See the 2026-06-11 contract audit.
+		alreadyEnded := ev.EndedAt.Valid
 		ratio := 0.0
 		if track.DurationMs > 0 {
 			ratio = float64(durationPlayedMs) / float64(track.DurationMs)
@@ -196,7 +202,7 @@ func (w *Writer) RecordPlayEnded(
 		}); err != nil {
 			return err
 		}
-		if isSkip {
+		if isSkip && !alreadyEnded {
 			if _, err := q.InsertSkipEvent(ctx, dbq.InsertSkipEventParams{
 				UserID:     ev.UserID,
 				TrackID:    ev.TrackID,
@@ -356,6 +362,24 @@ func (w *Writer) RecordOfflinePlay(
 		if err != nil {
 			return err
 		}
+		// Idempotency: the offline queue is at-least-once, so a response lost
+		// after commit makes the client re-fire the same play. The replayed
+		// payload carries the original `at`, so an exact (user, track,
+		// started_at) match means we already recorded it — no-op instead of a
+		// duplicate history row. See the 2026-06-11 contract audit.
+		var dupID pgtype.UUID
+		err = tx.QueryRow(ctx,
+			`SELECT id FROM play_events
+			 WHERE user_id = $1 AND track_id = $2 AND started_at = $3
+			 LIMIT 1`,
+			userID, trackID, pgtype.Timestamptz{Time: at, Valid: true},
+		).Scan(&dupID)
+		if err == nil {
+			return nil
+		}
+		if !errors.Is(err, pgx.ErrNoRows) {
+			return err
+		}
 		if err := w.autoClosePriorOpen(ctx, q, userID, at); err != nil {
 			return err
 		}
@@ -471,10 +495,15 @@ func (w *Writer) captureSessionVector(
 }
 
 // autoClosePriorOpen closes any open (ended_at IS NULL) play_event for the
-// user. Sets ended_at = at, duration_played_ms = min(at - started_at, track
-// duration), was_skipped = true. Skip rule is NOT applied — auto-closed
-// rows are flagged skipped regardless because we don't know what the user
-// actually heard.
+// user. Sets ended_at = at and duration_played_ms = min(at - started_at,
+// track duration) — our best estimate of how long the orphan played when
+// the client never sent play_ended (e.g. backgrounded mid-track). The same
+// skip rule as RecordPlayEnded is then applied to that estimate: an orphan
+// that sat open past the track's length reads as ratio ~1 → a real play, so
+// a fully-listened track that lost its close still lands in history instead
+// of being force-hidden. Deliberately writes no skip_events row — an
+// auto-close is an ambiguous signal, not a deliberate skip, and must not
+// feed the skip-ratio / recommendation signal.
 func (w *Writer) autoClosePriorOpen(
 	ctx context.Context,
 	q *dbq.Queries,
@@ -503,6 +532,7 @@ func (w *Writer) autoClosePriorOpen(
 	if track.DurationMs > 0 {
 		ratio = float64(elapsedMs) / float64(track.DurationMs)
 	}
+	isSkip := ratio < w.skipMaxCompletionRatio && elapsedMs < w.skipMaxDurationPlayedMs
 	ratioPtr := ratio
 	durPtr := elapsedMs
 	if _, err := q.UpdatePlayEventEnded(ctx, dbq.UpdatePlayEventEndedParams{
@@ -510,11 +540,11 @@ func (w *Writer) autoClosePriorOpen(
 		EndedAt:          pgtype.Timestamptz{Time: at, Valid: true},
 		DurationPlayedMs: &durPtr,
 		CompletionRatio:  &ratioPtr,
-		WasSkipped:       true,
+		WasSkipped:       isSkip,
 	}); err != nil {
 		return err
 	}
 	w.logger.Info("playevents: auto-closed prior open row",
-		"play_event_id", prior.ID, "elapsed_ms", elapsedMs)
+		"play_event_id", prior.ID, "elapsed_ms", elapsedMs, "was_skipped", isSkip)
 	return nil
 }

internal/playevents/writer_test.go

@@ -122,14 +122,32 @@ func TestRecordPlayStarted_AutoClosesPriorOpenRow(t *testing.T) {
 	if !prior.EndedAt.Valid {
 		t.Errorf("prior should be closed")
 	}
-	if !prior.WasSkipped {
-		t.Errorf("prior should be marked was_skipped=true (auto-close convention)")
+	// 45s elapsed on a 200s track clears the 30s duration threshold, so the
+	// skip rule's AND fails -> NOT a skip. An orphan that played long enough
+	// to count must still land in history rather than being force-hidden.
+	if prior.WasSkipped {
+		t.Errorf("auto-close at 45s should apply the skip rule -> was_skipped=false")
 	}
 	if prior.DurationPlayedMs == nil || *prior.DurationPlayedMs != 45_000 {
 		t.Errorf("duration_played_ms = %v, want 45000", prior.DurationPlayedMs)
 	}
 }
 
+func TestRecordPlayStarted_AutoCloseShortPlayIsSkip(t *testing.T) {
+	f := newFixture(t, 200_000)
+	t1 := time.Now().UTC()
+	first, _ := f.w.RecordPlayStarted(context.Background(), f.user, f.track, "c", t1)
+	// 5s elapsed: ratio 0.025 < 0.5 AND 5000 < 30000 -> both fail -> a skip.
+	t2 := t1.Add(5 * time.Second)
+	if _, err := f.w.RecordPlayStarted(context.Background(), f.user, f.track, "c", t2); err != nil {
+		t.Fatalf("second: %v", err)
+	}
+	prior, _ := f.q.GetPlayEventByID(context.Background(), first.PlayEventID)
+	if !prior.WasSkipped {
+		t.Errorf("auto-close at 5s should be was_skipped=true")
+	}
+}
+
 func TestRecordPlayStarted_AutoCloseCapsAtTrackDuration(t *testing.T) {
 	f := newFixture(t, 60_000) // 60s track
 	t1 := time.Now().UTC()
@@ -201,6 +219,55 @@ func TestRecordPlayEnded_DurationOver50Percent_NotSkip(t *testing.T) {
 	}
 }
 
+// A lost-response retry of an offline play (same user/track/started_at)
+// must not create a second history row. Guards the at-least-once replay
+// path added in the 2026-06-11 audit.
+func TestRecordOfflinePlay_DedupsByUserTrackStartedAt(t *testing.T) {
+	f := newFixture(t, 200_000)
+	ctx := context.Background()
+	at := time.Now().UTC()
+	if err := f.w.RecordOfflinePlay(ctx, f.user, f.track, "c", "", at, 120_000); err != nil {
+		t.Fatalf("first offline: %v", err)
+	}
+	if err := f.w.RecordOfflinePlay(ctx, f.user, f.track, "c", "", at, 120_000); err != nil {
+		t.Fatalf("replay offline: %v", err)
+	}
+	var count int
+	if err := f.pool.QueryRow(ctx,
+		"SELECT COUNT(*) FROM play_events WHERE user_id=$1 AND track_id=$2 AND started_at=$3",
+		f.user, f.track, pgtype.Timestamptz{Time: at, Valid: true}).Scan(&count); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+	if count != 1 {
+		t.Errorf("play_events count = %d, want 1 (deduped)", count)
+	}
+}
+
+// Re-closing an already-ended row (the client's durable close-by-id replay)
+// updates the row but must NOT insert a second skip_events row.
+func TestRecordPlayEnded_IdempotentClose_NoDuplicateSkipEvent(t *testing.T) {
+	f := newFixture(t, 200_000)
+	ctx := context.Background()
+	t1 := time.Now().UTC()
+	res, _ := f.w.RecordPlayStarted(ctx, f.user, f.track, "c", t1)
+	t2 := t1.Add(10 * time.Second) // 5% / 10s -> skip
+	if err := f.w.RecordPlayEnded(ctx, res.PlayEventID, 10_000, t2); err != nil {
+		t.Fatalf("first end: %v", err)
+	}
+	if err := f.w.RecordPlayEnded(ctx, res.PlayEventID, 10_000, t2); err != nil {
+		t.Fatalf("replay end: %v", err)
+	}
+	var count int
+	if err := f.pool.QueryRow(ctx,
+		"SELECT COUNT(*) FROM skip_events WHERE user_id=$1 AND track_id=$2",
+		f.user, f.track).Scan(&count); err != nil {
+		t.Fatalf("count: %v", err)
+	}
+	if count != 1 {
+		t.Errorf("skip_events count = %d, want 1 (idempotent close)", count)
+	}
+}
+
 func TestRecordPlaySkipped_AlwaysSkipFlagAndSkipEventRow(t *testing.T) {
 	f := newFixture(t, 200_000)
 	t1 := time.Now().UTC()

internal/playlists/scheduler.go

@@ -28,6 +28,7 @@ import (
 	"github.com/jackc/pgx/v5/pgxpool"
 
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/taste"
 )
 
 // dailyRebuildHour is the local-time hour at which each user's system
@@ -158,10 +159,7 @@ func (s *Scheduler) registerLocked(ctx context.Context, userID pgtype.UUID, tz s
 	job, err := s.gocron.NewJob(
 		gocron.CronJob(cronExpr, false /* withSeconds */),
 		gocron.NewTask(func() {
-			if err := BuildSystemPlaylists(ctx, s.pool, s.logger, userID, time.Now(), s.dataDir); err != nil {
-				s.logger.Warn("scheduler: build failed",
-					"user_id", uuidStringPL(userID), "err", err)
-			}
+			s.rebuildUserDaily(ctx, userID, time.Now())
 		}),
 	)
 	if err != nil {
@@ -220,10 +218,22 @@ func (s *Scheduler) reconcile(ctx context.Context) {
 // whose scheduled fire was missed during downtime get caught up.
 func (s *Scheduler) runStartupCatchUp(ctx context.Context, users []dbq.ListActiveUsersWithTimezonesRow) {
 	for _, u := range users {
-		if err := BuildSystemPlaylists(ctx, s.pool, s.logger, u.ID, time.Now(), s.dataDir); err != nil {
-			s.logger.Warn("scheduler: startup catch-up build failed",
-				"user_id", uuidStringPL(u.ID), "err", err)
-		}
+		s.rebuildUserDaily(ctx, u.ID, time.Now())
+	}
+}
+
+// rebuildUserDaily recomputes the user's taste profile, then rebuilds their
+// system playlists + You-might-like rows. Taste runs first so the playlist
+// build can read a fresh profile (phase-2 consumption); both steps are
+// best-effort and a failure in one is logged without blocking the other.
+func (s *Scheduler) rebuildUserDaily(ctx context.Context, userID pgtype.UUID, now time.Time) {
+	if err := taste.BuildTasteProfile(ctx, s.pool, s.logger, userID, taste.DefaultConfig()); err != nil {
+		s.logger.Warn("scheduler: taste profile rebuild failed",
+			"user_id", uuidStringPL(userID), "err", err)
+	}
+	if err := BuildSystemPlaylists(ctx, s.pool, s.logger, userID, now, s.dataDir); err != nil {
+		s.logger.Warn("scheduler: build failed",
+			"user_id", uuidStringPL(userID), "err", err)
 	}
 }
 

internal/playlists/system.go

@@ -5,6 +5,7 @@
 package playlists
 
 import (
+	"bytes"
 	"context"
 	"crypto/sha256"
 	"encoding/binary"
@@ -147,6 +148,11 @@ var systemMixWeights = recommendation.ScoringWeights{
 	JitterMagnitude:  0.1,
 	ContextWeight:    0.5,
 	SimilarityWeight: 1.5,
+	// Taste profile (#796 phase 2): the daily mixes are the primary
+	// taste-driven surface, so they lean on it. TasteMatchScore is in
+	// [-1,+1], so 1.5 makes a strong taste fit comparable to a like boost
+	// while passive avoidance (negative) gently demotes.
+	TasteWeight: 1.5,
 }
 
 // forYouHeadN is the number of top-scored tracks that anchor the For-You
@@ -180,8 +186,21 @@ func scoreAndSortCandidates(cands []recommendation.Candidate, userID pgtype.UUID
 		c     recommendation.Candidate
 		score float64
 	}
-	pairs := make([]scored, len(cands))
-	for i, c := range cands {
+	// Pin candidate order by track id before drawing jitter. The candidate
+	// query (LoadRadioCandidatesV2) has ORDER BY random() arms and no
+	// stable outer ordering, so DB row order varies call-to-call. Since
+	// the i-th candidate gets the i-th seeded jitter draw, an unstable
+	// input order would assign different jitter to the same track across
+	// same-day rebuilds and reorder near-ties — breaking the daily
+	// determinism this function promises. Sorting by id first makes the
+	// jitter assignment a function of (track, day) alone.
+	ordered := make([]recommendation.Candidate, len(cands))
+	copy(ordered, cands)
+	sort.SliceStable(ordered, func(i, j int) bool {
+		return uuidLessPL(ordered[i].Track.ID, ordered[j].Track.ID)
+	})
+	pairs := make([]scored, len(ordered))
+	for i, c := range ordered {
 		pairs[i] = scored{c: c, score: recommendation.Score(c.Inputs, systemMixWeights, now, rng.Float64)}
 	}
 	sort.SliceStable(pairs, func(i, j int) bool {
@@ -497,6 +516,13 @@ func BuildSystemPlaylists(ctx context.Context, pool *pgxpool.Pool, logger *slog.
 		built = append(built, out...)
 	}
 
+	// "You might like" Home rows reuse the same similarity engine but
+	// persist to dedicated album/artist tables (not playlist_tracks).
+	// Computed here (reads only) and atomic-replaced inside the tx below,
+	// alongside the system playlists. A failed/gated computation is
+	// handled by yml.built (leave prior rows vs. clear) — never fatal.
+	yml := buildYouMightLike(ctx, q, logger, userID, dateStr, now)
+
 	// Atomic replace inside a transaction.
 	tx, err := pool.Begin(ctx)
 	if err != nil {
@@ -530,6 +556,13 @@ func BuildSystemPlaylists(ctx context.Context, pool *pgxpool.Pool, logger *slog.
 		createdIDs = append(createdIDs, id)
 	}
 
+	if yml.built {
+		if err := persistYouMightLike(ctx, qtx, userID, yml); err != nil {
+			buildErr = fmt.Errorf("persist you-might-like: %w", err)
+			return buildErr
+		}
+	}
+
 	if err := tx.Commit(ctx); err != nil {
 		buildErr = fmt.Errorf("commit tx: %w", err)
 		return buildErr
@@ -695,6 +728,12 @@ func insertSystemPlaylist(ctx context.Context, qtx *dbq.Queries, userID pgtype.U
 // (pgtype.UUID's String method exists on some pgx versions but not others;
 // also the playlists package needs this independent of test helpers.)
 // Suffix `PL` distinguishes it from any test helper named uuidString.
+// uuidLessPL reports whether a sorts before b by raw 16-byte value. Used
+// to pin candidate order deterministically before jitter assignment.
+func uuidLessPL(a, b pgtype.UUID) bool {
+	return bytes.Compare(a.Bytes[:], b.Bytes[:]) < 0
+}
+
 func uuidStringPL(u pgtype.UUID) string {
 	if !u.Valid {
 		return "<nil>"

internal/playlists/you_might_like.go

@@ -0,0 +1,227 @@
+// you_might_like.go builds the per-user "You might like" Home rows
+// (#790): in-library albums/artists the listener doesn't actively spin
+// but is predicted to enjoy. It reuses the For-You candidate engine
+// (similarity + like-weighted scoring) and rolls the per-track scores up
+// to album/artist granularity, gated on a minimum listening history so a
+// near-empty profile ships nothing rather than noise.
+//
+// Built in the same daily BuildSystemPlaylists pass and atomic-replaced
+// alongside the system playlists; read back by /api/home.
+package playlists
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"math/rand"
+	"sort"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recommendation"
+)
+
+const (
+	// Cold-start gate. Below this much *real* listening the similarity
+	// roll-up degrades toward random fill, so You-might-like ships
+	// nothing rather than arbitrary tiles. Both bars must clear: distinct
+	// tracks rules out "played 3 songs on repeat," distinct artists rules
+	// out "hammered one album." Conservative defaults; raise if early
+	// rows feel random on thin libraries.
+	youMightLikeMinDistinctTracks  = 20
+	youMightLikeMinDistinctArtists = 5
+
+	// Persisted depth — a few more than the rendered HomeYouMightLikeLimit
+	// so the read-time cross-section dedup (vs Most Played / Rediscover)
+	// has headroom before trimming.
+	youMightLikeAlbumsN  = 12
+	youMightLikeArtistsN = 12
+
+	// One strongly-matched artist shouldn't fill the albums row.
+	youMightLikeMaxAlbumsPerArtist = 2
+
+	// Aggregation: sum of an entity's top-K track scores. Favors albums/
+	// artists with several good matches over a single outlier track.
+	youMightLikeAggTopK = 3
+)
+
+// youMightLikeResult carries one day's roll-up. built=false means the
+// computation failed and the caller must leave any existing rows intact;
+// built=true with nil slices means "explicitly empty" (cold-start gate or
+// no candidates) and the caller should clear the user's rows.
+type youMightLikeResult struct {
+	albumIDs  []pgtype.UUID
+	artistIDs []pgtype.UUID
+	built     bool
+}
+
+// buildYouMightLike computes the user's daily album/artist rolls. Reads
+// only — the caller persists inside the build tx. Never returns an error:
+// a failure logs and yields built=false so the prior day's rows survive.
+func buildYouMightLike(
+	ctx context.Context, q *dbq.Queries, logger *slog.Logger,
+	userID pgtype.UUID, dateStr string, now time.Time,
+) youMightLikeResult {
+	signal, err := q.CountListeningSignalForUser(ctx, userID)
+	if err != nil {
+		logger.Warn("you-might-like: listening-signal query failed; skipping",
+			"user_id", uuidStringPL(userID), "err", err)
+		return youMightLikeResult{built: false}
+	}
+	if signal.DistinctTracks < youMightLikeMinDistinctTracks ||
+		signal.DistinctArtists < youMightLikeMinDistinctArtists {
+		// Cold start: not enough listening to recommend from. built=true
+		// clears any stale rows (normally none) and ships an empty row.
+		return youMightLikeResult{built: true}
+	}
+
+	seeds, err := q.PickTopPlayedTracksForUser(ctx, userID)
+	if err != nil {
+		logger.Warn("you-might-like: seed query failed; skipping",
+			"user_id", uuidStringPL(userID), "err", err)
+		return youMightLikeResult{built: false}
+	}
+	seed := pickForYouSeedForDay(seeds, userID, dateStr)
+	if !seed.Valid {
+		return youMightLikeResult{built: true}
+	}
+
+	zeroVec := recommendation.SessionVector{Seed: true}
+	cands, err := recommendation.LoadCandidatesFromSimilarity(
+		ctx, q, userID, seed, 1, zeroVec,
+		[]pgtype.UUID{seed}, systemForYouSourceLimits(),
+	)
+	if err != nil {
+		logger.Warn("you-might-like: candidate load failed; skipping",
+			"user_id", uuidStringPL(userID), "err", err)
+		return youMightLikeResult{built: false}
+	}
+
+	albumIDs, artistIDs := rollUpCandidates(cands, userID, dateStr, now)
+	return youMightLikeResult{albumIDs: albumIDs, artistIDs: artistIDs, built: true}
+}
+
+// scoredEntity is an album or artist with its aggregated score.
+type scoredEntity struct {
+	id    pgtype.UUID
+	score float64
+}
+
+// rollUpCandidates scores every candidate track (systemMixWeights, jitter
+// seeded by userIDHash so near-ties rotate day-to-day) and aggregates the
+// scores up to album and artist via sum-of-top-K. Returns the top-N album
+// and artist IDs, with a per-artist cap on the album list.
+func rollUpCandidates(
+	cands []recommendation.Candidate, userID pgtype.UUID, dateStr string, now time.Time,
+) (albumIDs, artistIDs []pgtype.UUID) {
+	rng := rand.New(rand.NewSource(int64(userIDHash(userID, dateStr))))
+	albumScores := map[pgtype.UUID][]float64{}
+	artistScores := map[pgtype.UUID][]float64{}
+	albumArtist := map[pgtype.UUID]pgtype.UUID{}
+	for _, c := range cands {
+		s := recommendation.Score(c.Inputs, systemMixWeights, now, rng.Float64)
+		if c.Track.AlbumID.Valid {
+			albumScores[c.Track.AlbumID] = append(albumScores[c.Track.AlbumID], s)
+			albumArtist[c.Track.AlbumID] = c.Track.ArtistID
+		}
+		if c.Track.ArtistID.Valid {
+			artistScores[c.Track.ArtistID] = append(artistScores[c.Track.ArtistID], s)
+		}
+	}
+
+	rankedAlbums := capAlbumsPerArtist(
+		rankEntities(albumScores, dateStr), albumArtist, youMightLikeMaxAlbumsPerArtist)
+	albumIDs = topNEntityIDs(rankedAlbums, youMightLikeAlbumsN)
+	artistIDs = topNEntityIDs(rankEntities(artistScores, dateStr), youMightLikeArtistsN)
+	return albumIDs, artistIDs
+}
+
+// rankEntities aggregates each entity's track scores (sum-of-top-K) and
+// returns them sorted by score DESC, ties broken deterministically by
+// tieBreakHash(id, dateStr) so ordering is stable within a day.
+func rankEntities(scoresByEntity map[pgtype.UUID][]float64, dateStr string) []scoredEntity {
+	out := make([]scoredEntity, 0, len(scoresByEntity))
+	for id, scores := range scoresByEntity {
+		out = append(out, scoredEntity{id: id, score: sumTopK(scores, youMightLikeAggTopK)})
+	}
+	sort.SliceStable(out, func(i, j int) bool {
+		if out[i].score != out[j].score {
+			return out[i].score > out[j].score
+		}
+		return tieBreakHash(out[i].id, dateStr) < tieBreakHash(out[j].id, dateStr)
+	})
+	return out
+}
+
+// sumTopK sorts scores DESC and sums the highest k.
+func sumTopK(scores []float64, k int) float64 {
+	sort.Sort(sort.Reverse(sort.Float64Slice(scores)))
+	sum := 0.0
+	for i := 0; i < len(scores) && i < k; i++ {
+		sum += scores[i]
+	}
+	return sum
+}
+
+// capAlbumsPerArtist drops albums beyond maxPerArtist for any one artist,
+// preserving input (score) order.
+func capAlbumsPerArtist(
+	albums []scoredEntity, albumArtist map[pgtype.UUID]pgtype.UUID, maxPerArtist int,
+) []scoredEntity {
+	perArtist := map[pgtype.UUID]int{}
+	out := make([]scoredEntity, 0, len(albums))
+	for _, a := range albums {
+		art := albumArtist[a.id]
+		if art.Valid {
+			if perArtist[art] >= maxPerArtist {
+				continue
+			}
+			perArtist[art]++
+		}
+		out = append(out, a)
+	}
+	return out
+}
+
+// topNEntityIDs truncates to n and projects the IDs in rank order.
+func topNEntityIDs(entities []scoredEntity, n int) []pgtype.UUID {
+	if len(entities) > n {
+		entities = entities[:n]
+	}
+	out := make([]pgtype.UUID, 0, len(entities))
+	for _, e := range entities {
+		out = append(out, e.id)
+	}
+	return out
+}
+
+// persistYouMightLike atomic-replaces the user's You-might-like rows
+// inside the build tx. Called only when the roll-up was freshly built;
+// a failed computation leaves the prior rows untouched.
+func persistYouMightLike(
+	ctx context.Context, qtx *dbq.Queries, userID pgtype.UUID, r youMightLikeResult,
+) error {
+	if err := qtx.DeleteYouMightLikeAlbumsForUser(ctx, userID); err != nil {
+		return fmt.Errorf("delete you-might-like albums: %w", err)
+	}
+	for i, id := range r.albumIDs {
+		if err := qtx.InsertYouMightLikeAlbum(ctx, dbq.InsertYouMightLikeAlbumParams{
+			UserID: userID, AlbumID: id, Rank: int32(i),
+		}); err != nil {
+			return fmt.Errorf("insert you-might-like album: %w", err)
+		}
+	}
+	if err := qtx.DeleteYouMightLikeArtistsForUser(ctx, userID); err != nil {
+		return fmt.Errorf("delete you-might-like artists: %w", err)
+	}
+	for i, id := range r.artistIDs {
+		if err := qtx.InsertYouMightLikeArtist(ctx, dbq.InsertYouMightLikeArtistParams{
+			UserID: userID, ArtistID: id, Rank: int32(i),
+		}); err != nil {
+			return fmt.Errorf("insert you-might-like artist: %w", err)
+		}
+	}
+	return nil
+}

internal/playlists/you_might_like_db_test.go

@@ -0,0 +1,99 @@
+package playlists_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
+)
+
+// countYouMightLike returns the persisted row counts for a user.
+func countYouMightLike(t *testing.T, pool *pgxpool.Pool, userID pgtype.UUID) (albums, artists int) {
+	t.Helper()
+	ctx := context.Background()
+	if err := pool.QueryRow(ctx,
+		`SELECT count(*) FROM you_might_like_albums WHERE user_id = $1`, userID,
+	).Scan(&albums); err != nil {
+		t.Fatalf("count albums: %v", err)
+	}
+	if err := pool.QueryRow(ctx,
+		`SELECT count(*) FROM you_might_like_artists WHERE user_id = $1`, userID,
+	).Scan(&artists); err != nil {
+		t.Fatalf("count artists: %v", err)
+	}
+	return albums, artists
+}
+
+// TestYouMightLike_ColdStartGate: a thin profile (3 artists × 3 tracks =
+// 9 distinct tracks, below the 20-track / 5-artist gate) must produce no
+// You-might-like rows — the build ships nothing rather than near-random
+// tiles.
+func TestYouMightLike_ColdStartGate(t *testing.T) {
+	pool := newPool(t)
+	logger := discardLogger()
+	u, _ := seedActiveLibrary(t, pool, "ymlcold", 3, 3)
+
+	if err := playlists.BuildSystemPlaylists(
+		context.Background(), pool, logger, u.ID, time.Now().UTC(), t.TempDir(),
+	); err != nil {
+		t.Fatalf("build: %v", err)
+	}
+
+	albums, artists := countYouMightLike(t, pool, u.ID)
+	if albums != 0 || artists != 0 {
+		t.Errorf("cold-start user should have no you-might-like rows; got %d albums, %d artists",
+			albums, artists)
+	}
+}
+
+// TestYouMightLike_SufficientActivityPopulates: a rich profile (8 artists
+// × 4 tracks = 32 distinct tracks, clearing both gate bars) populates the
+// You-might-like tables in the daily build.
+func TestYouMightLike_SufficientActivityPopulates(t *testing.T) {
+	pool := newPool(t)
+	logger := discardLogger()
+	u, _ := seedActiveLibrary(t, pool, "ymlrich", 8, 4)
+
+	if err := playlists.BuildSystemPlaylists(
+		context.Background(), pool, logger, u.ID, time.Now().UTC(), t.TempDir(),
+	); err != nil {
+		t.Fatalf("build: %v", err)
+	}
+
+	albums, artists := countYouMightLike(t, pool, u.ID)
+	if albums == 0 {
+		t.Error("rich user should have you-might-like album rows; got 0")
+	}
+	if artists == 0 {
+		t.Error("rich user should have you-might-like artist rows; got 0")
+	}
+}
+
+// TestYouMightLike_AtomicReplace: a second build replaces rather than
+// appends, so counts stay bounded by the persisted depth.
+func TestYouMightLike_AtomicReplace(t *testing.T) {
+	pool := newPool(t)
+	logger := discardLogger()
+	u, _ := seedActiveLibrary(t, pool, "ymlreplace", 8, 4)
+	ctx := context.Background()
+
+	for i := 0; i < 2; i++ {
+		if err := playlists.BuildSystemPlaylists(
+			ctx, pool, logger, u.ID, time.Now().UTC(), t.TempDir(),
+		); err != nil {
+			t.Fatalf("build %d: %v", i, err)
+		}
+	}
+
+	albums, artists := countYouMightLike(t, pool, u.ID)
+	if albums > 12 {
+		t.Errorf("albums = %d after two builds, want <= 12 (atomic replace)", albums)
+	}
+	if artists > 12 {
+		t.Errorf("artists = %d after two builds, want <= 12 (atomic replace)", artists)
+	}
+}

internal/playlists/you_might_like_test.go

@@ -0,0 +1,125 @@
+package playlists
+
+import (
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recommendation"
+)
+
+// fixedNow keeps recencyDecay stable across the pure roll-up tests.
+var fixedNow = time.Date(2026, 6, 11, 12, 0, 0, 0, time.UTC)
+
+// byteOf returns the per-test entity discriminator (makeCand sets it in
+// Bytes[15]) so assertions can name albums/artists by their small int.
+func byteOf(u pgtype.UUID) byte { return u.Bytes[15] }
+
+// countWithByte reports how many of ids carry the given Bytes[15] marker.
+func countWithByte(ids []pgtype.UUID, want byte) int {
+	n := 0
+	for _, id := range ids {
+		if byteOf(id) == want {
+			n++
+		}
+	}
+	return n
+}
+
+func TestSumTopK(t *testing.T) {
+	if got := sumTopK([]float64{1, 2, 3, 4}, 2); got != 7 {
+		t.Errorf("sumTopK top-2 of 1..4 = %v, want 7", got)
+	}
+	if got := sumTopK([]float64{5}, 3); got != 5 {
+		t.Errorf("sumTopK fewer-than-k = %v, want 5", got)
+	}
+	if got := sumTopK(nil, 3); got != 0 {
+		t.Errorf("sumTopK empty = %v, want 0", got)
+	}
+}
+
+func TestRollUpCandidates_MultiMatchAlbumRanksFirst(t *testing.T) {
+	// Album 10 (artist 100): three solid matches. Album 20 (artist 200):
+	// one slightly-stronger single match. Sum-of-top-3 should rank the
+	// multi-match album ahead of the single-match one. Similarity gaps are
+	// wide enough that the ±0.1 jitter can't reorder the result.
+	cands := []recommendation.Candidate{
+		makeCand(1, 10, 100, 0.8),
+		makeCand(2, 10, 100, 0.8),
+		makeCand(3, 10, 100, 0.8),
+		makeCand(4, 20, 200, 0.95),
+	}
+	albums, _ := rollUpCandidates(cands, testUserID, "2026-06-11", fixedNow)
+	if len(albums) < 2 {
+		t.Fatalf("want >=2 albums, got %d", len(albums))
+	}
+	if byteOf(albums[0]) != 10 {
+		t.Errorf("top album = %d, want 10 (multi-match beats single)", byteOf(albums[0]))
+	}
+}
+
+func TestRollUpCandidates_PerArtistAlbumCap(t *testing.T) {
+	// Artist 100 spans albums 10/11/12; the album row caps any one artist
+	// at youMightLikeMaxAlbumsPerArtist (2). Artist 200's album 20 should
+	// still appear.
+	cands := []recommendation.Candidate{
+		makeCand(1, 10, 100, 0.9),
+		makeCand(2, 11, 100, 0.85),
+		makeCand(3, 12, 100, 0.8),
+		makeCand(4, 20, 200, 0.7),
+	}
+	albums, _ := rollUpCandidates(cands, testUserID, "2026-06-11", fixedNow)
+	from100 := countWithByte(albums, 10) + countWithByte(albums, 11) + countWithByte(albums, 12)
+	if from100 > youMightLikeMaxAlbumsPerArtist {
+		t.Errorf("artist 100 contributed %d albums, want <= %d",
+			from100, youMightLikeMaxAlbumsPerArtist)
+	}
+	if countWithByte(albums, 20) != 1 {
+		t.Errorf("album 20 (artist 200) should survive the cap; got %d",
+			countWithByte(albums, 20))
+	}
+}
+
+func TestRollUpCandidates_ArtistRollupDistinct(t *testing.T) {
+	// Three artists; the artist roll-up should surface all three distinct
+	// artist IDs (no per-artist cap on the artist row).
+	cands := []recommendation.Candidate{
+		makeCand(1, 10, 100, 0.9),
+		makeCand(2, 11, 101, 0.6),
+		makeCand(3, 12, 102, 0.3),
+	}
+	_, artists := rollUpCandidates(cands, testUserID, "2026-06-11", fixedNow)
+	seen := map[byte]bool{}
+	for _, a := range artists {
+		seen[byteOf(a)] = true
+	}
+	for _, want := range []byte{100, 101, 102} {
+		if !seen[want] {
+			t.Errorf("artist %d missing from roll-up", want)
+		}
+	}
+}
+
+func TestCapAlbumsPerArtist_DropsBeyondCap(t *testing.T) {
+	mk := func(albumN, artistN int) (pgtype.UUID, pgtype.UUID) {
+		var al, ar pgtype.UUID
+		al.Valid, ar.Valid = true, true
+		al.Bytes[15], ar.Bytes[15] = byte(albumN), byte(artistN)
+		return al, ar
+	}
+	a10, ar1 := mk(10, 1)
+	a11, _ := mk(11, 1)
+	a12, _ := mk(12, 1)
+	a20, ar2 := mk(20, 2)
+	albumArtist := map[pgtype.UUID]pgtype.UUID{a10: ar1, a11: ar1, a12: ar1, a20: ar2}
+	in := []scoredEntity{{a10, 3}, {a11, 2}, {a12, 1}, {a20, 0.5}}
+	got := capAlbumsPerArtist(in, albumArtist, 2)
+	if len(got) != 3 {
+		t.Fatalf("len = %d, want 3 (artist 1 capped at 2 + artist 2's one)", len(got))
+	}
+	// Highest-scored two of artist 1 (albums 10, 11) kept; 12 dropped.
+	if byteOf(got[2].id) != 20 {
+		t.Errorf("third survivor = %d, want 20", byteOf(got[2].id))
+	}
+}

internal/recommendation/candidates.go

@@ -36,6 +36,11 @@ func LoadCandidates(
 		return nil, err
 	}
 
+	profile, err := LoadTasteProfile(ctx, q, userID)
+	if err != nil {
+		return nil, err
+	}
+
 	out := make([]Candidate, 0, len(rows))
 	for _, r := range rows {
 		var lpt *time.Time
@@ -52,6 +57,7 @@ func LoadCandidates(
 				PlayCount:            int(r.PlayCount),
 				SkipCount:            int(r.SkipCount),
 				ContextualMatchScore: ctxScore,
+				TasteMatchScore:      profile.Match(r.Track.ArtistID, r.Track.Genre),
 			},
 		})
 	}
@@ -117,6 +123,11 @@ func LoadCandidatesFromSimilarity(
 		return nil, err
 	}
 
+	profile, err := LoadTasteProfile(ctx, q, userID)
+	if err != nil {
+		return nil, err
+	}
+
 	out := make([]Candidate, 0, len(rows))
 	for _, r := range rows {
 		var lpt *time.Time
@@ -141,6 +152,7 @@ func LoadCandidatesFromSimilarity(
 				SkipCount:            int(r.SkipCount),
 				ContextualMatchScore: ctxScore,
 				SimilarityScore:      simScore,
+				TasteMatchScore:      profile.Match(r.Track.ArtistID, r.Track.Genre),
 			},
 		})
 	}

internal/recommendation/home.go

@@ -34,6 +34,13 @@ const (
 	// artist from dominating the row. Two is enough variety; higher
 	// reads as "this artist's discography" instead of "rediscover".
 	maxAlbumsPerArtistInRediscover = 2
+
+	// HomeYouMightLikeLimit is the rendered count for each You-might-like
+	// row. The build persists a few more (youMightLikeAlbumsN/ArtistsN)
+	// so the read-time cross-section dedup has headroom; this query asks
+	// for the persisted depth and the Go layer trims to this after dedup.
+	HomeYouMightLikeLimit = 10
+	youMightLikeFetch     = 12
 )
 
 // HomePayload is the composite returned by HomeData. All slices are
@@ -45,6 +52,8 @@ type HomePayload struct {
 	RediscoverArtists   []dbq.ListRediscoverArtistsForUserRow
 	MostPlayedTracks    []dbq.ListMostPlayedTracksForUserRow
 	LastPlayedArtists   []dbq.ListLastPlayedArtistsForUserRow
+	YouMightLikeAlbums  []dbq.ListYouMightLikeAlbumsForUserRow
+	YouMightLikeArtists []dbq.ListYouMightLikeArtistsForUserRow
 }
 
 // HomeData runs five queries in parallel and assembles the payload.
@@ -77,9 +86,11 @@ func HomeData(ctx context.Context, pool *pgxpool.Pool, userID pgtype.UUID) (*Hom
 		RediscoverArtists:   []dbq.ListRediscoverArtistsForUserRow{},
 		MostPlayedTracks:    []dbq.ListMostPlayedTracksForUserRow{},
 		LastPlayedArtists:   []dbq.ListLastPlayedArtistsForUserRow{},
+		YouMightLikeAlbums:  []dbq.ListYouMightLikeAlbumsForUserRow{},
+		YouMightLikeArtists: []dbq.ListYouMightLikeArtistsForUserRow{},
 	}
 
-	wg.Add(5)
+	wg.Add(7)
 	go func() {
 		defer wg.Done()
 		rows, err := q.ListRecentlyAddedAlbumsWithArtist(ctx, HomeRecentlyAddedLimit)
@@ -129,6 +140,28 @@ func HomeData(ctx context.Context, pool *pgxpool.Pool, userID pgtype.UUID) (*Hom
 		}
 		out.RediscoverArtists = rows
 	}()
+	go func() {
+		defer wg.Done()
+		rows, err := q.ListYouMightLikeAlbumsForUser(ctx, dbq.ListYouMightLikeAlbumsForUserParams{
+			UserID: userID, Limit: youMightLikeFetch,
+		})
+		if err != nil {
+			fail("you_might_like_albums", err)
+			return
+		}
+		out.YouMightLikeAlbums = rows
+	}()
+	go func() {
+		defer wg.Done()
+		rows, err := q.ListYouMightLikeArtistsForUser(ctx, dbq.ListYouMightLikeArtistsForUserParams{
+			UserID: userID, Limit: youMightLikeFetch,
+		})
+		if err != nil {
+			fail("you_might_like_artists", err)
+			return
+		}
+		out.YouMightLikeArtists = rows
+	}()
 	wg.Wait()
 
 	if firstErr != nil {
@@ -140,9 +173,154 @@ func HomeData(ctx context.Context, pool *pgxpool.Pool, userID pgtype.UUID) (*Hom
 	// the rediscover lists down toward HomeRediscoverLimit.
 	out.RediscoverAlbums = applyRediscoverAlbumFilters(out.RediscoverAlbums, out.MostPlayedTracks)
 	out.RediscoverArtists = applyRediscoverArtistFilters(out.RediscoverArtists, out.MostPlayedTracks)
+	// You-might-like dedups against what the user already engages with
+	// (Most Played) and against the other Home rows so a tile doesn't
+	// appear twice. Trims to HomeYouMightLikeLimit after dedup.
+	out.YouMightLikeAlbums = applyYouMightLikeAlbumFilters(
+		out.YouMightLikeAlbums, out.MostPlayedTracks, out.RediscoverAlbums)
+	out.YouMightLikeArtists = applyYouMightLikeArtistFilters(
+		out.YouMightLikeArtists, out.MostPlayedTracks, out.RediscoverArtists, out.LastPlayedArtists)
+	// The taste roll-up surfaces top-similar entities, which for a heavy
+	// listener are mostly ones they already play — so the dedup above can
+	// leave the section thin (often a single artist). Top up from the much
+	// larger pool of liked entities, applying the same exclusions so the
+	// fallback neither duplicates a tile nor suggests an actively-played one.
+	if len(out.YouMightLikeArtists) < HomeYouMightLikeLimit {
+		out.YouMightLikeArtists = topUpYouMightLikeArtists(ctx, q, userID, out)
+	}
+	if len(out.YouMightLikeAlbums) < HomeYouMightLikeLimit {
+		out.YouMightLikeAlbums = topUpYouMightLikeAlbums(ctx, q, userID, out)
+	}
 	return out, nil
 }
 
+// youMightLikeFallbackFetch is the liked-entity pool the fallback draws from.
+// Generous so the dedup still leaves enough to fill the row.
+const youMightLikeFallbackFetch = 100
+
+// topUpYouMightLikeArtists fills a thin You-might-like artist row from the
+// user's liked artists (daily-stable sample), excluding what's already shown
+// on Home (the section itself, Rediscover, Most/Last Played) so the fallback
+// neither duplicates a tile nor suggests an actively-played artist. The liked
+// pool dwarfs the similarity roll-up, so the same exclusions still fill it.
+// Best-effort: a query error leaves the section as-is.
+func topUpYouMightLikeArtists(
+	ctx context.Context, q *dbq.Queries, userID pgtype.UUID, out *HomePayload,
+) []dbq.ListYouMightLikeArtistsForUserRow {
+	excluded := mostPlayedArtistIDs(out.MostPlayedTracks)
+	for _, r := range out.RediscoverArtists {
+		excluded[r.Artist.ID] = struct{}{}
+	}
+	for _, r := range out.LastPlayedArtists {
+		excluded[r.Artist.ID] = struct{}{}
+	}
+	result := out.YouMightLikeArtists
+	for _, r := range result {
+		excluded[r.Artist.ID] = struct{}{}
+	}
+	fb, err := q.ListRediscoverArtistsFallbackForUser(ctx, dbq.ListRediscoverArtistsFallbackForUserParams{
+		UserID: userID, Limit: youMightLikeFallbackFetch,
+	})
+	if err != nil {
+		return result
+	}
+	for _, r := range fb {
+		if _, dup := excluded[r.Artist.ID]; dup {
+			continue
+		}
+		result = append(result, dbq.ListYouMightLikeArtistsForUserRow(r))
+		if len(result) >= HomeYouMightLikeLimit {
+			break
+		}
+	}
+	return result
+}
+
+// topUpYouMightLikeAlbums is the album-row counterpart to
+// topUpYouMightLikeArtists, drawing from the user's liked albums.
+func topUpYouMightLikeAlbums(
+	ctx context.Context, q *dbq.Queries, userID pgtype.UUID, out *HomePayload,
+) []dbq.ListYouMightLikeAlbumsForUserRow {
+	excluded := mostPlayedAlbumIDs(out.MostPlayedTracks)
+	for _, r := range out.RediscoverAlbums {
+		excluded[r.Album.ID] = struct{}{}
+	}
+	result := out.YouMightLikeAlbums
+	for _, r := range result {
+		excluded[r.Album.ID] = struct{}{}
+	}
+	fb, err := q.ListRediscoverAlbumsFallbackForUser(ctx, dbq.ListRediscoverAlbumsFallbackForUserParams{
+		UserID: userID, Limit: youMightLikeFallbackFetch,
+	})
+	if err != nil {
+		return result
+	}
+	for _, r := range fb {
+		if _, dup := excluded[r.Album.ID]; dup {
+			continue
+		}
+		result = append(result, dbq.ListYouMightLikeAlbumsForUserRow(r))
+		if len(result) >= HomeYouMightLikeLimit {
+			break
+		}
+	}
+	return result
+}
+
+// applyYouMightLikeAlbumFilters drops albums the user actively plays
+// (Most Played) or that already appear in Rediscover, then trims to
+// HomeYouMightLikeLimit. Build-time rank order is preserved.
+func applyYouMightLikeAlbumFilters(
+	rows []dbq.ListYouMightLikeAlbumsForUserRow,
+	mostPlayed []dbq.ListMostPlayedTracksForUserRow,
+	rediscover []dbq.ListRediscoverAlbumsForUserRow,
+) []dbq.ListYouMightLikeAlbumsForUserRow {
+	excluded := mostPlayedAlbumIDs(mostPlayed)
+	for _, r := range rediscover {
+		excluded[r.Album.ID] = struct{}{}
+	}
+	out := make([]dbq.ListYouMightLikeAlbumsForUserRow, 0, HomeYouMightLikeLimit)
+	for _, r := range rows {
+		if _, dup := excluded[r.Album.ID]; dup {
+			continue
+		}
+		out = append(out, r)
+		if len(out) >= HomeYouMightLikeLimit {
+			break
+		}
+	}
+	return out
+}
+
+// applyYouMightLikeArtistFilters drops artists the user actively plays
+// (Most Played), recently played (Last Played), or that already appear in
+// Rediscover, then trims to HomeYouMightLikeLimit.
+func applyYouMightLikeArtistFilters(
+	rows []dbq.ListYouMightLikeArtistsForUserRow,
+	mostPlayed []dbq.ListMostPlayedTracksForUserRow,
+	rediscover []dbq.ListRediscoverArtistsForUserRow,
+	lastPlayed []dbq.ListLastPlayedArtistsForUserRow,
+) []dbq.ListYouMightLikeArtistsForUserRow {
+	excluded := mostPlayedArtistIDs(mostPlayed)
+	for _, r := range rediscover {
+		excluded[r.Artist.ID] = struct{}{}
+	}
+	for _, r := range lastPlayed {
+		excluded[r.Artist.ID] = struct{}{}
+	}
+	out := make([]dbq.ListYouMightLikeArtistsForUserRow, 0, HomeYouMightLikeLimit)
+	for _, r := range rows {
+		if _, dup := excluded[r.Artist.ID]; dup {
+			continue
+		}
+		out = append(out, r)
+		if len(out) >= HomeYouMightLikeLimit {
+			break
+		}
+	}
+	return out
+}
+
 // mostPlayedAlbumIDs returns the set of album IDs whose tracks appear
 // in the Most Played row. Used to dedup Rediscover so it doesn't list
 // albums the user is actively spinning.

internal/recommendation/home_integration_test.go

@@ -2,6 +2,7 @@ package recommendation
 
 import (
 	"context"
+	"fmt"
 	"testing"
 	"time"
 
@@ -10,6 +11,43 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
 )
 
+// TestHomeData_YouMightLike_FallbackFillsFromLikedArtists: when the taste
+// roll-up is empty/thin (no you_might_like_artists rows here), the section
+// fills from the user's liked artists. Rediscover takes its share first; the
+// You-might-like fallback fills the rest disjointly so no artist is shown
+// twice. 20 liked artists, none played → Rediscover 10 + You-might-like 10.
+func TestHomeData_YouMightLike_FallbackFillsFromLikedArtists(t *testing.T) {
+	pool := newPool(t)
+	user := seedUser(t, pool, "home-yml-fallback")
+	liked := make(map[pgtype.UUID]bool, 20)
+	for i := 0; i < 20; i++ {
+		a := seedArtist(t, pool, fmt.Sprintf("YmlArtist%02d", i), "")
+		likeArtist(t, pool, user.ID, a.ID)
+		liked[a.ID] = true
+	}
+
+	got, err := HomeData(context.Background(), pool, user.ID)
+	if err != nil {
+		t.Fatalf("HomeData: %v", err)
+	}
+	if len(got.YouMightLikeArtists) != HomeYouMightLikeLimit {
+		t.Fatalf("you-might-like artists = %d, want %d (filled by fallback)",
+			len(got.YouMightLikeArtists), HomeYouMightLikeLimit)
+	}
+	inRediscover := map[pgtype.UUID]bool{}
+	for _, r := range got.RediscoverArtists {
+		inRediscover[r.Artist.ID] = true
+	}
+	for _, r := range got.YouMightLikeArtists {
+		if !liked[r.Artist.ID] {
+			t.Errorf("you-might-like artist %s not from the liked pool", r.Artist.Name)
+		}
+		if inRediscover[r.Artist.ID] {
+			t.Errorf("artist %s shown in both Rediscover and You-might-like", r.Artist.Name)
+		}
+	}
+}
+
 func TestHomeData_NewUser_AllSectionsEmpty(t *testing.T) {
 	pool := newPool(t)
 	user := seedUser(t, pool, "home-newuser")