Merge pull request 'Taste-profile fidelity (M160) + Songs-like row + home polish' (#109) from dev into main

Milestone #160 Opt 3b. Adds device class as a third context axis on top
of the #1531 time-of-day/weekday affinity: on the radio path, a candidate
is boosted when its artist concentrates in the current (daypart × weekday
× device) cell. Client-sent (client_id is opaque; no UA stored), so it's
captured going forward and applies to radio only (daily mixes are
cron-built with no device → stay device-agnostic).

Server:
- Migration 0048: play_events.device_class text NULL (no CHECK; normalized
  in Go — one whitelist entry per new client class, not a migration).
- events.go: eventRequest.device_class + normalizeDeviceClass (whitelist →
  mobile/web/…, else "other", empty → NULL); threaded through both
  RecordPlayStartedWithSource and RecordOfflinePlay into InsertPlayEvent.
- ListArtistContextPlayCountsForUser gains a current-device param; the cell
  FILTER adds AND ($2='' OR device_class=$2) — '' reproduces the #1531
  time-only behaviour exactly (used by mixes). SessionVector.DeviceClass
  carries it; the radio handler derives the current device from the user's
  latest play (GetLatestPlayDeviceClassForUser) — request-free proxy.
- No new tuning knob: device narrows the existing ContextAffinityScore
  (reuses context_time_weight).

Clients:
- web: play_started sends device_class 'web'.
- android: play_started + offline replay send 'mobile' (EventsWire +
  PlayOfflinePayload + MutationReplayer + PlayEventsReporter).

Test: LoadContextAffinity device-narrowing integration test (mobile vs web
artist separation; device-agnostic parity).

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

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

@@ -10,6 +10,8 @@ import com.fabledsword.minstrel.cache.CacheIndexer
 import com.fabledsword.minstrel.cache.mutations.MutationReplayer
 import com.fabledsword.minstrel.cache.sync.SyncController
 import com.fabledsword.minstrel.di.ApplicationScope
+import com.fabledsword.minstrel.diagnostics.DiagnosticsReporter
+import com.fabledsword.minstrel.diagnostics.DiagnosticsUploader
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.events.LiveEventsDispatcher
 import com.fabledsword.minstrel.metadata.FreshnessSweeper
@@ -155,6 +157,11 @@ class MinstrelApplication :
      */
     @Suppress("unused") @Inject lateinit var liveEventsDispatcher: LiveEventsDispatcher
 
+    // Device diagnostics (M9). The reporter gates itself on the account's
+    // debug flag; the uploader drains its buffer on a tick / recovery.
+    @Suppress("unused") @Inject lateinit var diagnosticsReporter: DiagnosticsReporter
+    @Suppress("unused") @Inject lateinit var diagnosticsUploader: DiagnosticsUploader
+
     @Inject @ApplicationScope lateinit var appScope: CoroutineScope
 
     override fun onCreate() {

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

@@ -0,0 +1,48 @@
+package com.fabledsword.minstrel.admin.data
+
+import com.fabledsword.minstrel.api.endpoints.AdminTagSourcesApi
+import com.fabledsword.minstrel.api.endpoints.UpdateTagSourceBody
+import com.fabledsword.minstrel.models.AdminTagSourceRef
+import com.fabledsword.minstrel.models.TagSourceTestResult
+import com.fabledsword.minstrel.models.wire.AdminTagSourceWire
+import com.fabledsword.minstrel.models.wire.TestTagSourceWire
+import retrofit2.Retrofit
+import retrofit2.create
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Read-through accessor for the tag-enrichment provider settings (#1521).
+ * No Room caching — admin settings are infrequent point-and-shoot edits;
+ * mutations fire direct REST and the ViewModel reconciles on failure.
+ * Exceptions propagate to the ViewModel (which maps them via ErrorCopy).
+ */
+@Singleton
+class AdminTagSourcesRepository @Inject constructor(
+    retrofit: Retrofit,
+) {
+    private val api: AdminTagSourcesApi = retrofit.create()
+
+    suspend fun list(): List<AdminTagSourceRef> = api.list().providers.map { it.toDomain() }
+
+    suspend fun setEnabled(id: String, enabled: Boolean): AdminTagSourceRef =
+        api.update(id, UpdateTagSourceBody(enabled = enabled)).toDomain()
+
+    suspend fun setApiKey(id: String, apiKey: String): AdminTagSourceRef =
+        api.update(id, UpdateTagSourceBody(apiKey = apiKey)).toDomain()
+
+    suspend fun test(id: String): TagSourceTestResult = api.test(id).toResult()
+}
+
+private fun AdminTagSourceWire.toDomain(): AdminTagSourceRef = AdminTagSourceRef(
+    id = id,
+    displayName = displayName,
+    requiresApiKey = requiresApiKey,
+    supports = supports,
+    enabled = enabled,
+    apiKeySet = apiKeySet,
+    testable = testable,
+)
+
+private fun TestTagSourceWire.toResult(): TagSourceTestResult =
+    TagSourceTestResult(ok = ok, durationMs = durationMs, error = error)

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

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

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

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

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

@@ -29,6 +29,7 @@ import androidx.navigation.NavHostController
 import com.fabledsword.minstrel.models.AdminQuarantineItemRef
 import com.fabledsword.minstrel.nav.AdminQuarantine
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -62,9 +63,10 @@ fun AdminQuarantineScreen(
                     body = "When users flag tracks as bad rips, wrong tags, or " +
                         "duplicates, their reports get aggregated and surfaced here.",
                 )
-                is AdminQuarantineUiState.Error -> EmptyState(
+                is AdminQuarantineUiState.Error -> ErrorRetry(
                     title = "Couldn't load queue",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                 )
                 is AdminQuarantineUiState.Success -> QueueList(
                     rows = s.rows,

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

@@ -4,6 +4,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.admin.data.AdminQuarantineRepository
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.AdminQuarantineItemRef
 import dagger.hilt.android.lifecycle.HiltViewModel
@@ -26,6 +28,7 @@ sealed interface AdminQuarantineUiState {
 class AdminQuarantineViewModel @Inject constructor(
     private val repository: AdminQuarantineRepository,
     private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val internal = MutableStateFlow<AdminQuarantineUiState>(AdminQuarantineUiState.Loading)
@@ -38,6 +41,13 @@ class AdminQuarantineViewModel @Inject constructor(
                 .filter { it.kind.startsWith("quarantine.") }
                 .collect { refresh() }
         }
+        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // when server health returns instead of waiting for a manual pull.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AdminQuarantineUiState.Error) refresh()
+            }
+        }
     }
 
     fun refresh(): Job = viewModelScope.launch {

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

@@ -28,6 +28,7 @@ import androidx.navigation.NavHostController
 import com.fabledsword.minstrel.models.RequestRef
 import com.fabledsword.minstrel.nav.AdminRequests
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -61,9 +62,10 @@ fun AdminRequestsScreen(
                     body = "When users ask Lidarr for new music, their pending " +
                         "requests show up here for approval.",
                 )
-                is AdminRequestsUiState.Error -> EmptyState(
+                is AdminRequestsUiState.Error -> ErrorRetry(
                     title = "Couldn't load requests",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                 )
                 is AdminRequestsUiState.Success -> RequestList(
                     rows = s.rows,

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,36 @@
+package com.fabledsword.minstrel.api.endpoints
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonElement
+import retrofit2.http.Body
+import retrofit2.http.POST
+
+/**
+ * Retrofit interface for device diagnostics ingest (M9). One call
+ * uploads a batch of buffered events. The server stores them only when
+ * the account's debug_mode_enabled flag is on (it returns 204 otherwise,
+ * which the uploader treats as success so it can drop the batch).
+ */
+interface DiagnosticsApi {
+    @POST("api/diagnostics")
+    suspend fun report(@Body body: DiagnosticsReportRequest)
+}
+
+@Serializable
+data class DiagnosticsReportRequest(
+    @SerialName("client_id") val clientId: String,
+    @SerialName("app_version") val appVersion: String? = null,
+    @SerialName("os_version") val osVersion: String? = null,
+    val events: List<DiagnosticEventWire>,
+)
+
+@Serializable
+data class DiagnosticEventWire(
+    val kind: String,
+    // Device-clock epoch milliseconds. The server stamps its own
+    // received_at; both are stored so a skewed device clock is visible.
+    @SerialName("occurred_at") val occurredAt: Long,
+    // Opaque structured payload carrying the event sub-type + fields.
+    val payload: JsonElement,
+)

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

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

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

@@ -59,6 +59,9 @@ class AuthStore @Inject constructor(
     private val cacheSettingsState = MutableStateFlow(CacheSettings.DEFAULT)
     val cacheSettings: StateFlow<CacheSettings> = cacheSettingsState.asStateFlow()
 
+    private val diagnosticsOptOutState = MutableStateFlow(false)
+    val diagnosticsOptOut: StateFlow<Boolean> = diagnosticsOptOutState.asStateFlow()
+
     private val json = Json { ignoreUnknownKeys = true }
 
     init {
@@ -70,6 +73,7 @@ class AuthStore @Inject constructor(
                 themeModeState.value = row?.themeMode
                 clientIdState.value = row?.clientId
                 cacheSettingsState.value = decodeCacheSettings(row?.cacheSettingsJson)
+                diagnosticsOptOutState.value = row?.diagnosticsOptOut ?: false
             }
         }
     }
@@ -112,6 +116,11 @@ class AuthStore @Inject constructor(
         scope.launch { persistCacheSettings(encoded) }
     }
 
+    fun setDiagnosticsOptOut(value: Boolean) {
+        diagnosticsOptOutState.value = value
+        scope.launch { persistDiagnosticsOptOut(value) }
+    }
+
     private suspend fun persistCookie(value: String?) {
         if (dao.get() == null) {
             dao.upsert(currentEntity().copy(sessionCookie = value))
@@ -160,6 +169,14 @@ class AuthStore @Inject constructor(
         }
     }
 
+    private suspend fun persistDiagnosticsOptOut(value: Boolean) {
+        if (dao.get() == null) {
+            dao.upsert(currentEntity().copy(diagnosticsOptOut = value))
+        } else {
+            dao.setDiagnosticsOptOut(value)
+        }
+    }
+
     private fun currentEntity(): AuthSessionEntity = AuthSessionEntity(
         id = ROW_ID,
         sessionCookie = sessionCookieState.value,
@@ -171,6 +188,7 @@ class AuthStore @Inject constructor(
             CacheSettings.serializer(),
             cacheSettingsState.value,
         ),
+        diagnosticsOptOut = diagnosticsOptOutState.value,
     )
 
     companion object {

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

@@ -16,6 +16,7 @@ import com.fabledsword.minstrel.cache.db.dao.CachedResumeStateDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistTrackDao
 import com.fabledsword.minstrel.cache.db.dao.CachedQuarantineDao
 import com.fabledsword.minstrel.cache.db.dao.CachedTrackDao
+import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
 import com.fabledsword.minstrel.cache.db.dao.SyncMetadataDao
 import com.fabledsword.minstrel.cache.db.entities.AudioCacheIndexEntity
 import com.fabledsword.minstrel.cache.db.entities.AuthSessionEntity
@@ -30,6 +31,7 @@ import com.fabledsword.minstrel.cache.db.entities.CachedResumeStateEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedPlaylistTrackEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedQuarantineEntity
 import com.fabledsword.minstrel.cache.db.entities.CachedTrackEntity
+import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
 import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity
 
 /**
@@ -61,8 +63,11 @@ import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity
         CachedHomeIndexEntity::class,
         CachedHistorySnapshotEntity::class,
         AuthSessionEntity::class,
+        DiagnosticEventEntity::class,
     ],
-    version = 6,
+    // v7: + diagnostic_events table (M9) and the diagnosticsOptOut column
+    // on auth_session. Pre-v1 destructive fallback rebuilds on mismatch.
+    version = 7,
     exportSchema = true,
 )
 @TypeConverters(MinstrelTypeConverters::class)
@@ -81,4 +86,5 @@ abstract class AppDatabase : RoomDatabase() {
     abstract fun cachedHomeIndexDao(): CachedHomeIndexDao
     abstract fun cachedHistorySnapshotDao(): CachedHistorySnapshotDao
     abstract fun authSessionDao(): AuthSessionDao
+    abstract fun diagnosticEventDao(): DiagnosticEventDao
 }

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

@@ -10,6 +10,7 @@ import com.fabledsword.minstrel.cache.db.dao.CachedHistorySnapshotDao
 import com.fabledsword.minstrel.cache.db.dao.CachedHomeIndexDao
 import com.fabledsword.minstrel.cache.db.dao.CachedLikeDao
 import com.fabledsword.minstrel.cache.db.dao.CachedMutationDao
+import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistDao
 import com.fabledsword.minstrel.cache.db.dao.CachedPlaylistTrackDao
 import com.fabledsword.minstrel.cache.db.dao.CachedQuarantineDao
@@ -105,5 +106,10 @@ object DatabaseModule {
     fun provideAudioCacheIndexDao(db: AppDatabase): AudioCacheIndexDao =
         db.audioCacheIndexDao()
 
+    @Provides
+    @Singleton
+    fun provideDiagnosticEventDao(db: AppDatabase): DiagnosticEventDao =
+        db.diagnosticEventDao()
+
     private const val DATABASE_NAME = "minstrel.db"
 }

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

@@ -42,4 +42,8 @@ interface AuthSessionDao {
     /** Partial update: change only the serialized cache settings. */
     @Query("UPDATE auth_session SET cacheSettingsJson = :json WHERE id = 0")
     suspend fun setCacheSettingsJson(json: String?)
+
+    /** Partial update: change only the per-device diagnostics opt-out. */
+    @Query("UPDATE auth_session SET diagnosticsOptOut = :optOut WHERE id = 0")
+    suspend fun setDiagnosticsOptOut(optOut: Boolean)
 }

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

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

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

@@ -36,4 +36,11 @@ data class AuthSessionEntity(
      * CacheSettings shape evolves.
      */
     val cacheSettingsJson: String? = null,
+    /**
+     * Per-device opt-out of diagnostics reporting (M9). When the
+     * account's debug mode is enabled by an admin, the user can still
+     * turn reporting OFF on this device (battery/privacy) — that local
+     * choice lives here. Default false = honor the account flag.
+     */
+    val diagnosticsOptOut: Boolean = false,
 )

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

@@ -0,0 +1,28 @@
+package com.fabledsword.minstrel.cache.db.entities
+
+import androidx.room.Entity
+import androidx.room.PrimaryKey
+
+/**
+ * One buffered device-diagnostics event (M9). The DiagnosticsReporter
+ * writes rows here when the account's debug mode is on; the
+ * DiagnosticsUploader drains them to POST /api/diagnostics and deletes
+ * on success.
+ *
+ * This is a deliberate ring buffer that is NOT routed through the offline
+ * MutationQueue: diagnostics are high-volume, best-effort telemetry, and
+ * the bug we're chasing (roaming / dead-zone recovery) happens WHILE
+ * offline — so events must persist locally through the dead zone and
+ * upload on recovery, without clogging the user-data mutation replay.
+ *
+ * `occurredAtMillis` is the device-clock epoch-ms when the event happened
+ * (the server also stamps its own received_at). `payloadJson` is an
+ * opaque JSON object carrying the event sub-type + fields.
+ */
+@Entity(tableName = "diagnostic_events")
+data class DiagnosticEventEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val kind: String,
+    val occurredAtMillis: Long,
+    val payloadJson: String,
+)

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

@@ -239,6 +239,9 @@ data class PlayOfflinePayload(
     val atIso: String,
     val durationPlayedMs: Long,
     val source: String? = null,
+    // #1551: device class for context conditioning; null on payloads queued
+    // before this field existed (decodes to null → server stores NULL).
+    val deviceClass: String? = null,
 )
 
 /**

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

@@ -254,6 +254,7 @@ class MutationReplayer @Inject constructor(
                 at = decoded.atIso,
                 durationPlayedMs = decoded.durationPlayedMs,
                 source = decoded.source,
+                deviceClass = decoded.deviceClass,
             ),
         )
         return Outcome.SENT

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

@@ -1,5 +1,6 @@
 package com.fabledsword.minstrel.cache.sync
 
+import com.fabledsword.minstrel.api.ErrorCopy
 import com.fabledsword.minstrel.api.endpoints.SyncApi
 import com.fabledsword.minstrel.auth.AuthStore
 import com.fabledsword.minstrel.connectivity.NetworkStatusController
@@ -17,6 +18,9 @@ import com.fabledsword.minstrel.models.wire.SyncAlbumWire
 import com.fabledsword.minstrel.models.wire.SyncArtistWire
 import com.fabledsword.minstrel.models.wire.SyncTrackWire
 import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.filterNotNull
@@ -64,6 +68,17 @@ class SyncController @Inject constructor(
     // pull-to-refresh) can fire concurrently; coalesce them into one pass.
     private val mutex = Mutex()
 
+    private val lastSyncErrorInternal = MutableStateFlow<String?>(null)
+
+    /**
+     * Human copy for the most recent sync failure; null after any clean
+     * pass. Lets the Library screen distinguish "empty because the first
+     * sync failed" (show error + retry) from "genuinely empty library"
+     * (show welcome copy) — a failed sync over a populated cache stays
+     * silent, since the cached content is still the better surface.
+     */
+    val lastSyncError: StateFlow<String?> = lastSyncErrorInternal.asStateFlow()
+
     init {
         scope.launch {
             authStore.sessionCookie
@@ -82,11 +97,13 @@ class SyncController @Inject constructor(
         }
     }
 
-    /** Public entry-point for "Sync now" affordances. Swallows errors. */
+    /** Public entry-point for "Sync now" affordances. Swallows errors into [lastSyncError]. */
     suspend fun syncSafe() {
         if (!mutex.tryLock()) return
         try {
             runCatching { sync() }
+                .onSuccess { lastSyncErrorInternal.value = null }
+                .onFailure { lastSyncErrorInternal.value = ErrorCopy.fromThrowable(it) }
         } finally {
             mutex.unlock()
         }

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

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

android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsReporter.kt

@@ -0,0 +1,328 @@
+package com.fabledsword.minstrel.diagnostics
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.os.PowerManager
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import androidx.core.content.ContextCompat
+import androidx.lifecycle.ProcessLifecycleOwner
+import com.fabledsword.minstrel.auth.AuthController
+import com.fabledsword.minstrel.auth.AuthStore
+import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
+import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
+import com.fabledsword.minstrel.connectivity.ConnectivityObserver
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.di.ApplicationScope
+import com.fabledsword.minstrel.player.PlayerController
+import com.fabledsword.minstrel.player.RemotePlayerState
+import com.fabledsword.minstrel.player.output.OutputPickerController
+import com.fabledsword.minstrel.player.output.OutputRoute
+import dagger.hilt.android.qualifiers.ApplicationContext
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.combine
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.launch
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.put
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * On-device diagnostics collector (M9). Active only while the account's
+ * debug mode is enabled (server flag, read via AuthController.currentUser)
+ * AND the user hasn't opted out locally. When active it taps existing
+ * connectivity / player / UPnP / power seams READ-ONLY and writes a
+ * timeseries of events into the [DiagnosticEventDao] ring buffer; the
+ * [DiagnosticsUploader] drains that buffer to the server.
+ *
+ * The aim is to explain two failure classes after the fact: roaming /
+ * poor-data recovery (connectivity + server-health transitions) and
+ * locked-phone UPnP desync (power/Doze transitions correlated with the
+ * Sonos-vs-local position deltas captured in the heartbeat).
+ */
+@Suppress("TooManyFunctions") // one collector + one (un)register pair per signal; cohesive
+@Singleton
+class DiagnosticsReporter @Inject constructor(
+    @ApplicationContext private val context: Context,
+    @ApplicationScope private val scope: CoroutineScope,
+    private val dao: DiagnosticEventDao,
+    private val authController: AuthController,
+    private val authStore: AuthStore,
+    private val connectivity: ConnectivityObserver,
+    private val networkStatus: NetworkStatusController,
+    private val playerController: PlayerController,
+    private val outputPicker: OutputPickerController,
+    private val remoteState: RemotePlayerState,
+    private val json: Json,
+) {
+    @Volatile private var enabled = false
+    private var collectorJob: Job? = null
+    private var powerReceiver: BroadcastReceiver? = null
+    private var lifecycleObserver: DefaultLifecycleObserver? = null
+
+    init {
+        // Gate = account flag (currentUser.debugModeEnabled) AND not the
+        // per-device local opt-out.
+        scope.launch {
+            combine(authController.currentUser, authStore.diagnosticsOptOut) { user, optOut ->
+                (user?.debugModeEnabled == true) && !optOut
+            }.distinctUntilChanged().collect { setEnabled(it) }
+        }
+        // Periodically re-pull /me so a remote admin flip propagates
+        // without a re-login or app restart.
+        scope.launch {
+            while (true) {
+                delay(GATE_REFRESH_MS)
+                authController.refreshProfile()
+            }
+        }
+    }
+
+    private fun setEnabled(value: Boolean) {
+        if (value == enabled) return
+        enabled = value
+        if (value) start() else stop()
+    }
+
+    private fun start() {
+        registerPowerReceiver()
+        registerLifecycleObserver()
+        collectorJob = scope.launch {
+            record("lifecycle", buildJsonObject { put("event", "reporting_started") })
+            launch { collectConnectivity() }
+            launch { collectServerHealth() }
+            launch { collectUpnpDrops() }
+            launch { collectPlayerState() }
+            launch { collectTrackChanges() }
+            launch { collectRoutes() }
+            launch { heartbeatLoop() }
+        }
+    }
+
+    private fun stop() {
+        collectorJob?.cancel()
+        collectorJob = null
+        unregisterPowerReceiver()
+        unregisterLifecycleObserver()
+        // Off means off: drop any unsent buffer (honors the user OFF
+        // intent and avoids leaking data captured before disable).
+        scope.launch { runCatching { dao.clear() } }
+    }
+
+    private suspend fun collectConnectivity() {
+        connectivity.online.distinctUntilChanged().collect { online ->
+            record("connectivity", buildJsonObject {
+                put("event", "online_changed")
+                put("online", online)
+            })
+        }
+    }
+
+    private suspend fun collectServerHealth() {
+        // state is a StateFlow — already conflated/distinct, so no
+        // distinctUntilChanged (it's a deprecation warning = build error).
+        networkStatus.state.collect { s ->
+            record("connectivity", buildJsonObject {
+                put("event", "server_health")
+                put("state", s.name)
+            })
+        }
+    }
+
+    private suspend fun collectUpnpDrops() {
+        playerController.dropEvents.collect { msg ->
+            record("upnp_sync", buildJsonObject {
+                put("event", "drop")
+                put("message", msg)
+            })
+        }
+    }
+
+    private suspend fun collectPlayerState() {
+        // 'playback', not 'upnp_sync' — player state applies to every output
+        // route (phone speaker, Bluetooth, UPnP), not just casting.
+        playerController.uiState
+            .map { Triple(it.currentSource, it.isUpnpLoading, it.playbackError) }
+            .distinctUntilChanged()
+            .collect { (source, upnpLoading, err) ->
+                record("playback", buildJsonObject {
+                    put("event", "player_state")
+                    put("source", source ?: "")
+                    put("upnp_loading", upnpLoading)
+                    if (err != null) put("error", err)
+                })
+            }
+    }
+
+    // Emit a snapshot at each track/queue-index change — captures a
+    // skip-induced local↔Sonos desync at the INSTANT it happens, which the
+    // 45s heartbeat misses. Note: uiState is a conflated StateFlow, so a
+    // very rapid skip burst may coalesce intermediate indices (we still get
+    // the boundaries + the local-vs-Sonos snapshot).
+    private suspend fun collectTrackChanges() {
+        playerController.uiState
+            .map { it.queueIndex to it.currentTrack?.id }
+            .distinctUntilChanged()
+            .collect { (index, _) ->
+                val ui = playerController.uiState.value
+                val casting = outputPicker.routesState.value.current.protocol !=
+                    OutputRoute.Protocol.SYSTEM
+                record("playback", buildJsonObject {
+                    put("event", "track_change")
+                    put("local_index", index)
+                    // Track IDENTITY, not just index — indices wobble across
+                    // re-casts, so the id + Sonos URI make a desync unambiguous.
+                    put("local_track_id", ui.currentTrack?.id ?: "")
+                    put("local_pos_ms", ui.positionMs)
+                    putSonos(this, casting)
+                    put("upnp_loading", ui.isUpnpLoading)
+                    put("server_health", networkStatus.state.value.name)
+                    put("route", outputPicker.routesState.value.current.name)
+                })
+            }
+    }
+
+    private suspend fun collectRoutes() {
+        // 'playback' — route changes happen for all outputs. This only ever
+        // logs the ACTIVE route (routesState.current), so no "connected" flag.
+        outputPicker.routesState.map { it.current }.distinctUntilChanged().collect { r ->
+            record("playback", buildJsonObject {
+                put("event", "route")
+                put("id", r.id)
+                put("name", r.name)
+                put("kind", r.kind.name)
+                put("protocol", r.protocol.name)
+            })
+        }
+    }
+
+    private suspend fun heartbeatLoop() {
+        while (true) {
+            delay(HEARTBEAT_MS)
+            val ui = playerController.uiState.value
+            val route = outputPicker.routesState.value.current
+            val routeActive = route.protocol != OutputRoute.Protocol.SYSTEM
+            // Idle = nothing worth sampling. Skip to keep the buffer lean.
+            if (!ui.isPlaying && !routeActive) continue
+            record("heartbeat", buildJsonObject {
+                put("server_health", networkStatus.state.value.name)
+                put("is_playing", ui.isPlaying)
+                put("source", ui.currentSource ?: "")
+                put("local_index", ui.queueIndex)
+                put("local_track_id", ui.currentTrack?.id ?: "")
+                put("local_pos_ms", ui.positionMs)
+                put("route", route.name)
+                put("route_protocol", route.protocol.name)
+                putSonos(this, routeActive)
+                addPowerFields(this)
+            })
+        }
+    }
+
+    // --- power + lifecycle taps -------------------------------------------
+
+    private fun registerPowerReceiver() {
+        if (powerReceiver != null) return
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(c: Context?, intent: Intent?) {
+                val action = intent?.action ?: return
+                if (!enabled) return
+                scope.launch { record("power", powerEvent(action)) }
+            }
+        }
+        val filter = IntentFilter().apply {
+            addAction(Intent.ACTION_SCREEN_ON)
+            addAction(Intent.ACTION_SCREEN_OFF)
+            addAction(PowerManager.ACTION_DEVICE_IDLE_MODE_CHANGED)
+        }
+        // System-protected broadcasts, but pass NOT_EXPORTED explicitly so
+        // the API 34+ registerReceiver flag requirement is satisfied.
+        ContextCompat.registerReceiver(
+            context, receiver, filter, ContextCompat.RECEIVER_NOT_EXPORTED,
+        )
+        powerReceiver = receiver
+    }
+
+    private fun unregisterPowerReceiver() {
+        powerReceiver?.let { runCatching { context.unregisterReceiver(it) } }
+        powerReceiver = null
+    }
+
+    private fun registerLifecycleObserver() {
+        if (lifecycleObserver != null) return
+        val obs = object : DefaultLifecycleObserver {
+            override fun onStart(owner: LifecycleOwner) = logLifecycle("app_foreground")
+            override fun onStop(owner: LifecycleOwner) = logLifecycle("app_background")
+        }
+        lifecycleObserver = obs
+        scope.launch(Dispatchers.Main) {
+            ProcessLifecycleOwner.get().lifecycle.addObserver(obs)
+        }
+    }
+
+    private fun unregisterLifecycleObserver() {
+        val obs = lifecycleObserver ?: return
+        lifecycleObserver = null
+        scope.launch(Dispatchers.Main) {
+            ProcessLifecycleOwner.get().lifecycle.removeObserver(obs)
+        }
+    }
+
+    private fun logLifecycle(event: String) {
+        if (!enabled) return
+        scope.launch { record("lifecycle", buildJsonObject { put("event", event) }) }
+    }
+
+    private fun powerEvent(action: String): JsonObject = buildJsonObject {
+        put("event", action.substringAfterLast('.'))
+        addPowerFields(this)
+    }
+
+    // Sonos/UPnP remote-vs-local desync fields. Only meaningful while a
+    // remote route is active; zeroed otherwise so a stale RemotePlayerState
+    // from a just-ended cast can't masquerade as live Sonos data (the
+    // cast→phone handoff artifact). currentTrackUri is the desync ground
+    // truth — it carries the track the speaker is actually streaming.
+    private fun putSonos(builder: kotlinx.serialization.json.JsonObjectBuilder, casting: Boolean) {
+        builder.put("sonos_track", if (casting) remoteState.trackNumber else 0)
+        builder.put("sonos_pos_ms", if (casting) remoteState.positionMs else 0)
+        builder.put("sonos_playing", casting && remoteState.isPlaying)
+        if (casting) builder.put("sonos_uri", remoteState.currentTrackUri)
+    }
+
+    private fun addPowerFields(builder: kotlinx.serialization.json.JsonObjectBuilder) {
+        val pm = context.getSystemService(Context.POWER_SERVICE) as PowerManager
+        builder.put("doze", pm.isDeviceIdleMode)
+        builder.put("screen_on", pm.isInteractive)
+        builder.put("battery_opt_ignored", pm.isIgnoringBatteryOptimizations(context.packageName))
+    }
+
+    private suspend fun record(kind: String, payload: JsonObject) {
+        runCatching {
+            val id = dao.insert(
+                DiagnosticEventEntity(
+                    kind = kind,
+                    occurredAtMillis = System.currentTimeMillis(),
+                    payloadJson = json.encodeToString(JsonObject.serializer(), payload),
+                ),
+            )
+            if (id % TRIM_INTERVAL == 0L) dao.trimToNewest(MAX_BUFFER)
+        }
+    }
+
+    private companion object {
+        const val HEARTBEAT_MS = 45_000L
+        const val GATE_REFRESH_MS = 300_000L // re-pull /me every 5 min
+        const val MAX_BUFFER = 5_000 // ring-buffer ceiling, oldest dropped
+        const val TRIM_INTERVAL = 50L // trim every N inserts, not every one
+    }
+}

android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsUploader.kt

@@ -0,0 +1,118 @@
+package com.fabledsword.minstrel.diagnostics
+
+import android.os.Build
+import com.fabledsword.minstrel.BuildConfig
+import com.fabledsword.minstrel.api.endpoints.DiagnosticEventWire
+import com.fabledsword.minstrel.api.endpoints.DiagnosticsApi
+import com.fabledsword.minstrel.api.endpoints.DiagnosticsReportRequest
+import com.fabledsword.minstrel.auth.AuthStore
+import com.fabledsword.minstrel.cache.db.dao.DiagnosticEventDao
+import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.ServerHealth
+import com.fabledsword.minstrel.di.ApplicationScope
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.delay
+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.serialization.json.Json
+import retrofit2.Retrofit
+import retrofit2.create
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Drains the [DiagnosticEventDao] ring buffer to POST /api/diagnostics
+ * (M9). Triggers mirror [com.fabledsword.minstrel.cache.mutations.MutationReplayer]:
+ * a periodic tick, a sign-in (sessionCookie non-null), and a server-health
+ * recovery to [ServerHealth.Healthy] — so a dead-zone's buffered events
+ * upload the moment the link comes back.
+ *
+ * Deliberately NOT the MutationQueue: diagnostics are high-volume,
+ * best-effort telemetry. A failed upload just retries on the next tick;
+ * the server no-ops (204) when the account's debug flag is off, which the
+ * uploader treats as success so the buffer drains either way.
+ */
+@Singleton
+class DiagnosticsUploader @Inject constructor(
+    private val dao: DiagnosticEventDao,
+    private val authStore: AuthStore,
+    private val json: Json,
+    @ApplicationScope private val scope: CoroutineScope,
+    networkStatus: NetworkStatusController,
+    retrofit: Retrofit,
+) {
+    private val api: DiagnosticsApi = retrofit.create()
+    private val mutex = Mutex()
+
+    init {
+        scope.launch {
+            while (true) {
+                delay(UPLOAD_INTERVAL_MS)
+                drainSafe()
+            }
+        }
+        scope.launch {
+            authStore.sessionCookie.filterNotNull().distinctUntilChanged().collect { drainSafe() }
+        }
+        scope.launch {
+            networkStatus.state
+                .map { it == ServerHealth.Healthy }
+                .distinctUntilChanged()
+                .filter { it }
+                .collect { drainSafe() }
+        }
+    }
+
+    /** Coalesces concurrent triggers via tryLock — a drain in flight wins. */
+    private suspend fun drainSafe() {
+        val clientId = authStore.clientId.value
+        // Signed out / no client id yet → nothing to do. Single guard keeps
+        // the return count within the detekt gate.
+        if (authStore.sessionCookie.value.isNullOrEmpty() || clientId == null) return
+        if (!mutex.tryLock()) return
+        try {
+            drain(clientId)
+        } finally {
+            mutex.unlock()
+        }
+    }
+
+    private suspend fun drain(clientId: String) {
+        var more = true
+        while (more) {
+            val batch = runCatching { dao.takeBatch(BATCH_SIZE) }.getOrNull().orEmpty()
+            val sent = batch.isNotEmpty() && runCatching { upload(clientId, batch) }.isSuccess
+            if (sent) runCatching { dao.deleteByIds(batch.map { it.id }) }
+            // Keep going only while a full batch sent cleanly; otherwise stop
+            // (empty buffer, or a failure to retry on the next trigger).
+            more = sent && batch.size >= BATCH_SIZE
+        }
+    }
+
+    private suspend fun upload(clientId: String, batch: List<DiagnosticEventEntity>) {
+        api.report(
+            DiagnosticsReportRequest(
+                clientId = clientId,
+                appVersion = BuildConfig.VERSION_NAME,
+                osVersion = "Android ${Build.VERSION.RELEASE} (${Build.MODEL})",
+                events = batch.map { row ->
+                    DiagnosticEventWire(
+                        kind = row.kind,
+                        occurredAt = row.occurredAtMillis,
+                        payload = json.parseToJsonElement(row.payloadJson),
+                    )
+                },
+            ),
+        )
+    }
+
+    private companion object {
+        const val UPLOAD_INTERVAL_MS = 60_000L
+        const val BATCH_SIZE = 100
+    }
+}

android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverScreen.kt

@@ -41,6 +41,7 @@ import com.fabledsword.minstrel.models.ArtistSuggestionRef
 import com.fabledsword.minstrel.models.LidarrRequestKind
 import com.fabledsword.minstrel.models.LidarrSearchResultRef
 import com.fabledsword.minstrel.nav.Discover
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -109,6 +110,7 @@ private fun DiscoverBody(
                             snackbar.showSnackbar(snackbarFor(outcome, s.name))
                         }
                     },
+                    onRetry = { viewModel.loadSuggestions() },
                 )
                 ResultsState.Loading -> LoadingCentered()
                 is ResultsState.Loaded -> ResultsList(
@@ -121,7 +123,11 @@ private fun DiscoverBody(
                         }
                     },
                 )
-                is ResultsState.Error -> CenteredMessage("Search failed: ${r.message}")
+                is ResultsState.Error -> ErrorRetry(
+                    title = "Search failed",
+                    message = r.message,
+                    onRetry = viewModel::runSearch,
+                )
             }
         }
     }
@@ -177,10 +183,15 @@ private fun SuggestionsPane(
     state: SuggestionState,
     locallyRequestedMbids: Set<String>,
     onRequest: (ArtistSuggestionRef) -> Unit,
+    onRetry: () -> Unit,
 ) {
     when (state) {
         SuggestionState.Loading -> LoadingCentered()
-        is SuggestionState.Error -> CenteredMessage("Couldn't load suggestions.")
+        is SuggestionState.Error -> ErrorRetry(
+            title = "Couldn't load suggestions",
+            message = state.message,
+            onRetry = onRetry,
+        )
         is SuggestionState.Loaded -> SuggestionsList(
             items = state.items.filter { it.mbid !in locallyRequestedMbids },
             onRequest = onRequest,

android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverViewModel.kt

@@ -3,6 +3,8 @@ package com.fabledsword.minstrel.discover.ui
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.discover.data.DiscoverRepository
 import com.fabledsword.minstrel.discover.data.RequestOutcome
 import com.fabledsword.minstrel.models.ArtistSuggestionRef
@@ -46,6 +48,7 @@ sealed interface ResultsState {
 @HiltViewModel
 class DiscoverViewModel @Inject constructor(
     private val repository: DiscoverRepository,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val internal = MutableStateFlow(DiscoverState())
@@ -53,6 +56,15 @@ class DiscoverViewModel @Inject constructor(
 
     init {
         loadSuggestions()
+        // Screen-level auto-recovery (issue #1245): re-run whichever pane
+        // failed while the server was unreachable once health returns.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                val s = internal.value
+                if (s.suggestions is SuggestionState.Error) loadSuggestions()
+                if (s.results is ResultsState.Error) runSearch()
+            }
+        }
     }
 
     fun setQuery(value: String) {

android/app/src/main/java/com/fabledsword/minstrel/history/ui/HistoryTab.kt

@@ -19,6 +19,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.history.data.HistoryEntry
 import com.fabledsword.minstrel.history.data.HistoryRepository
 import com.fabledsword.minstrel.models.TrackRef
@@ -26,6 +28,7 @@ import com.fabledsword.minstrel.player.PlayerController
 import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.widgets.TrackRow
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.TrackCoverThumb
@@ -56,6 +59,7 @@ private const val SHARE_STOP_TIMEOUT_MS = 5_000L
 class HistoryTabViewModel @Inject constructor(
     private val repository: HistoryRepository,
     private val player: PlayerController,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val refreshError = MutableStateFlow<String?>(null)
@@ -82,6 +86,11 @@ class HistoryTabViewModel @Inject constructor(
 
     init {
         refresh()
+        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // health returns, so a load that failed offline heals unprompted.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refresh() }
+        }
     }
 
     fun refresh(): Job = viewModelScope.launch {
@@ -116,9 +125,10 @@ fun HistoryTab(
                 title = "No listening history yet",
                 body = "Play something — your recent plays will show up here.",
             )
-            is UiState.Error -> EmptyState(
+            is UiState.Error -> ErrorRetry(
                 title = "Couldn't load history",
-                body = s.message,
+                message = s.message,
+                onRetry = { viewModel.refresh() },
             )
             is UiState.Success -> HistoryList(
                 entries = s.data,

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

@@ -2,11 +2,19 @@
 
 package com.fabledsword.minstrel.home.ui
 
+import androidx.compose.animation.AnimatedVisibility
 import androidx.compose.animation.Crossfade
+import androidx.compose.animation.core.tween
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.animation.slideInHorizontally
+import androidx.compose.animation.slideOutHorizontally
 import androidx.compose.foundation.background
 import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxScope
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.PaddingValues
 import androidx.compose.foundation.layout.Row
@@ -27,6 +35,7 @@ import androidx.compose.foundation.lazy.grid.items as gridItems
 import androidx.compose.foundation.lazy.items
 import androidx.compose.foundation.lazy.itemsIndexed
 import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Scaffold
@@ -55,6 +64,7 @@ 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.connectivity.recoveries
 import com.fabledsword.minstrel.home.data.HomeRepository
 import com.fabledsword.minstrel.library.data.LibraryRepository
 import com.fabledsword.minstrel.library.widgets.AlbumCard
@@ -77,6 +87,7 @@ import com.fabledsword.minstrel.playlists.widgets.PlaylistPlaceholderCard
 import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.asCacheFirstStateFlow
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.HorizontalScrollRow
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -86,6 +97,7 @@ import com.fabledsword.minstrel.shared.widgets.SkeletonSectionHeader
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.channels.Channel
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharingStarted
@@ -108,6 +120,16 @@ private const val BOTTOM_PADDING_FOR_MINIPLAYER_DP = 140
 private const val RECENTLY_ADDED_GRID_ROWS = 2
 private const val RECENTLY_ADDED_GRID_HEIGHT_DP = 440
 
+// "Updating your mixes…" veil (automatic refresh). Held through the pull
+// plus VEIL_SETTLE_MS so per-tile hydration lands behind it before it wipes
+// off; near-opaque (VEIL_ALPHA) so the section churn never bleeds through.
+private const val VEIL_SETTLE_MS = 500L
+private const val VEIL_WIPE_MS = 280
+private const val VEIL_ALPHA = 0.96f
+private const val VEIL_SPINNER_DP = 22
+private const val VEIL_SPINNER_STROKE_DP = 2
+private const val VEIL_LABEL_GAP_DP = 12
+
 // ─── State ───────────────────────────────────────────────────────────
 
 data class HomeSections(
@@ -167,16 +189,44 @@ class HomeViewModel @Inject constructor(
     /** Transient snackbar messages from offline-pool taps. */
     val transientMessages: Flow<String> = poolMessages.receiveAsFlow()
 
+    /**
+     * Copy for the most recent /home/index refresh failure; null once a
+     * refresh succeeds. Folded into [uiState] so an empty cache + failed
+     * refresh renders as Error (with retry) instead of masquerading as
+     * the "Welcome to Minstrel" empty state.
+     */
+    private val refreshError = MutableStateFlow<String?>(null)
+
+    private val updatingInternal = MutableStateFlow(false)
+
+    /**
+     * True while an automatic background refresh (the 03:00 daily rebuild
+     * or a reconnect re-pull) is repopulating Home. Drives the "Updating
+     * your mixes…" veil so the section churn — delete-then-insert in
+     * [HomeRepository.refreshIndex] plus per-tile hydration — happens
+     * hidden behind the veil instead of on screen. Manual pull-to-refresh
+     * and cold start are NOT veiled (they own the pull spinner / skeleton).
+     */
+    val isUpdating: StateFlow<Boolean> = updatingInternal.asStateFlow()
+
     init {
         refresh()
+        // Screen-level auto-recovery (issue #1245): a Home that failed to
+        // load while the server was unreachable re-pulls itself the moment
+        // health returns — same idiom as SyncController, one layer up.
+        // Veiled: content is already on screen and would otherwise churn.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refreshBehindVeil() }
+        }
         // #968: the daily 03:00 rebuild (and manual refresh) emit
         // playlist.system_rebuilt; re-pull Home so the system-playlist tiles
         // and You-might-like rows reflect the new snapshot without a manual
-        // reload. Mirrors the web SSE consumer.
+        // reload. Mirrors the web SSE consumer. Veiled so the multi-section
+        // rebuild churn hides behind "Updating your mixes…".
         viewModelScope.launch {
             eventsStream.events
                 .filter { it.kind == "playlist.system_rebuilt" }
-                .collect { refresh() }
+                .collect { refreshBehindVeil() }
         }
     }
 
@@ -289,7 +339,14 @@ class HomeViewModel @Inject constructor(
      * actual completion before hiding the indicator.
      */
     fun refresh(): Job = viewModelScope.launch {
-        val home = launch { runCatching { homeRepository.refreshIndex() } }
+        refreshError.value = null
+        val home = launch {
+            // /home/index is the load-bearing pull: its failure drives the
+            // empty-cache Error state. A failure over a populated cache
+            // stays silent — cached sections beat a full-screen error.
+            runCatching { homeRepository.refreshIndex() }
+                .onFailure { refreshError.value = ErrorCopy.fromThrowable(it) }
+        }
         val lists = launch { runCatching { playlistsRepository.refreshList() } }
         val status = launch {
             runCatching { homeRepository.getSystemPlaylistsStatus() }
@@ -300,6 +357,26 @@ class HomeViewModel @Inject constructor(
         status.join()
     }
 
+    /**
+     * Automatic background refresh with the "Updating your mixes…" veil
+     * raised (see [isUpdating]). Used by the daily-rebuild + reconnect
+     * paths where Home is already on screen. Holds the veil through the
+     * pull plus a short settle so per-tile hydration lands behind it, then
+     * lets it wipe off. Overlapping automatic refreshes are rare enough
+     * (once-daily rebuild, reconnect) that a plain flag beats a counter.
+     */
+    private fun refreshBehindVeil() {
+        viewModelScope.launch {
+            updatingInternal.value = true
+            try {
+                refresh().join()
+                delay(VEIL_SETTLE_MS)
+            } finally {
+                updatingInternal.value = false
+            }
+        }
+    }
+
     val uiState: StateFlow<UiState<HomeSections>> =
         combineHomeFlows().asCacheFirstStateFlow(viewModelScope)
 
@@ -336,9 +413,17 @@ class HomeViewModel @Inject constructor(
     }
 
     private fun combineHomeFlows() =
-        observeHomeSections().combine(playlistsRepository.observeAll()) { sections, playlists ->
+        combine(
+            observeHomeSections(),
+            playlistsRepository.observeAll(),
+            refreshError,
+        ) { sections, playlists, err ->
             val merged = sections.copy(playlists = playlists)
-            if (merged.isAllEmpty) UiState.Empty else UiState.Success(merged)
+            when {
+                !merged.isAllEmpty -> UiState.Success(merged)
+                err != null -> UiState.Error(err)
+                else -> UiState.Empty
+            }
         }
 }
 
@@ -367,46 +452,108 @@ fun HomeScreen(
         val state by viewModel.uiState.collectAsStateWithLifecycle()
         val systemStatus by viewModel.systemStatus.collectAsStateWithLifecycle()
         val offline by viewModel.offline.collectAsStateWithLifecycle()
+        val updating by viewModel.isUpdating.collectAsStateWithLifecycle()
         PullToRefreshScaffold(
             onRefresh = { viewModel.refresh().join() },
             modifier = Modifier.fillMaxSize().padding(inner),
         ) {
-            // Key Crossfade on the state CLASS, not the instance. Each
-            // section emission produces a new UiState.Success(data); if
-            // we keyed on `state` directly, every per-section
-            // hydration tick would re-run the 300ms crossfade, and
-            // first-sign-in (six sections cascading in) reads as
-            // continuous flicker. Keying on the class restricts the
-            // animation to Loading↔Success↔Empty↔Error transitions and
-            // lets normal Success→Success recompositions update the
-            // LazyColumn without a fade.
-            Crossfade(targetState = state::class, label = "home-state") { _ ->
-                when (val s = state) {
-                    UiState.Loading -> HomeSkeletonContent()
-                    UiState.Empty -> EmptyState(
-                        title = "Welcome to Minstrel",
-                        body = "Nothing to show yet — scan a folder in your server " +
-                            "settings, then come back here for system playlists " +
-                            "and recommendations.",
-                    )
-                    is UiState.Error -> EmptyState(
-                        title = "Couldn't load home",
-                        body = s.message,
-                    )
-                    is UiState.Success -> HomeSuccessContent(
-                        sections = s.data,
-                        systemStatus = systemStatus,
-                        offline = offline,
-                        onAlbumClick = { id -> navController.navigate(AlbumDetail(id)) },
-                        onArtistClick = { id -> navController.navigate(ArtistDetail(id)) },
-                        onPlaylistClick = { id -> navController.navigate(PlaylistDetail(id)) },
-                        onMostPlayedTap = viewModel::playMostPlayed,
-                        onPlayPool = viewModel::playPool,
-                        onPlayAlbum = viewModel::playAlbum,
-                        onPlayArtist = viewModel::playArtistShuffled,
-                        onPlayPlaylist = viewModel::playPlaylist,
-                    )
-                }
+            Box(Modifier.fillMaxSize()) {
+                HomeStateCrossfade(state, systemStatus, offline, navController, viewModel)
+                // Automatic-refresh veil: the daily rebuild / reconnect
+                // churn hides behind an "Updating your mixes…" wipe. Manual
+                // pull owns the PullToRefreshBox spinner instead.
+                UpdatingVeil(visible = updating)
+            }
+        }
+    }
+}
+
+/**
+ * The Loading/Empty/Error/Success switch for Home, crossfaded on state.
+ *
+ * Key the Crossfade on the state CLASS, not the instance. Each section
+ * emission produces a new UiState.Success(data); if we keyed on `state`
+ * directly, every per-section hydration tick would re-run the 300ms
+ * crossfade, and first-sign-in (six sections cascading in) reads as
+ * continuous flicker. Keying on the class restricts the animation to
+ * Loading↔Success↔Empty↔Error transitions and lets normal Success→Success
+ * recompositions update the LazyColumn without a fade.
+ */
+@Composable
+private fun HomeStateCrossfade(
+    state: UiState<HomeSections>,
+    systemStatus: SystemPlaylistsStatus,
+    offline: Boolean,
+    navController: NavHostController,
+    viewModel: HomeViewModel,
+) {
+    Crossfade(targetState = state::class, label = "home-state") { _ ->
+        when (val s = state) {
+            UiState.Loading -> HomeSkeletonContent()
+            UiState.Empty -> EmptyState(
+                title = "Welcome to Minstrel",
+                body = "Nothing to show yet — scan a folder in your server " +
+                    "settings, then come back here for system playlists " +
+                    "and recommendations.",
+            )
+            is UiState.Error -> ErrorRetry(
+                title = "Couldn't load home",
+                message = s.message,
+                onRetry = { viewModel.refresh() },
+            )
+            is UiState.Success -> HomeSuccessContent(
+                sections = s.data,
+                systemStatus = systemStatus,
+                offline = offline,
+                onAlbumClick = { id -> navController.navigate(AlbumDetail(id)) },
+                onArtistClick = { id -> navController.navigate(ArtistDetail(id)) },
+                onPlaylistClick = { id -> navController.navigate(PlaylistDetail(id)) },
+                onMostPlayedTap = viewModel::playMostPlayed,
+                onPlayPool = viewModel::playPool,
+                onPlayAlbum = viewModel::playAlbum,
+                onPlayArtist = viewModel::playArtistShuffled,
+                onPlayPlaylist = viewModel::playPlaylist,
+            )
+        }
+    }
+}
+
+/**
+ * Full-bleed "Updating your mixes…" veil that wipes in from the left,
+ * holds while an automatic refresh repopulates Home, then wipes off.
+ * Near-opaque so the section churn underneath never shows; swallows taps
+ * while raised so a mid-hydration tile can't be hit.
+ */
+@Composable
+private fun BoxScope.UpdatingVeil(visible: Boolean) {
+    AnimatedVisibility(
+        visible = visible,
+        enter = slideInHorizontally(tween(VEIL_WIPE_MS)) { -it } + fadeIn(tween(VEIL_WIPE_MS)),
+        exit = slideOutHorizontally(tween(VEIL_WIPE_MS)) { it } + fadeOut(tween(VEIL_WIPE_MS)),
+        modifier = Modifier.matchParentSize(),
+    ) {
+        Box(
+            modifier = Modifier
+                .fillMaxSize()
+                .background(MaterialTheme.colorScheme.background.copy(alpha = VEIL_ALPHA))
+                .clickable(
+                    interactionSource = remember { MutableInteractionSource() },
+                    indication = null,
+                ) {},
+            contentAlignment = Alignment.Center,
+        ) {
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                CircularProgressIndicator(
+                    modifier = Modifier.size(VEIL_SPINNER_DP.dp),
+                    strokeWidth = VEIL_SPINNER_STROKE_DP.dp,
+                    color = MaterialTheme.colorScheme.primary,
+                )
+                Spacer(Modifier.width(VEIL_LABEL_GAP_DP.dp))
+                Text(
+                    text = "Updating your mixes…",
+                    style = MaterialTheme.typography.titleMedium,
+                    color = MaterialTheme.colorScheme.onBackground,
+                )
             }
         }
     }
@@ -476,10 +623,12 @@ private fun HomeSuccessContent(
     ) {
         item {
             // Always rendered: real system/user playlists, with
-            // placeholder cards filling the For You / Discover /
-            // 3× Songs-like slots that haven't generated yet. When
-            // offline, the cache-backed pool cards lead the row.
+            // placeholder cards filling the For You / Discover slots
+            // that haven't generated yet. When offline, the cache-backed
+            // pool cards lead the row. Songs-like now lives in its own
+            // dedicated row below (#1491), no longer inside this carousel.
             PlaylistsRow(
+                title = "Playlists",
                 rowItems = buildPlaylistsRow(sections.playlists, systemStatus, offline),
                 offline = offline,
                 onPlaylistClick = onPlaylistClick,
@@ -487,6 +636,18 @@ private fun HomeSuccessContent(
                 onPlayPlaylist = onPlayPlaylist,
             )
         }
+        // Songs-like is the best-performing surface (#1491) — promoted out
+        // of the Playlists carousel into its own row so it shows a wider
+        // spread of "Songs like {artist}" mixes. Hidden when there's
+        // nothing to show (offline with none cached).
+        songsLikeSection(
+            playlists = sections.playlists,
+            status = systemStatus,
+            offline = offline,
+            onPlaylistClick = onPlaylistClick,
+            onPlayPool = onPlayPool,
+            onPlayPlaylist = onPlayPlaylist,
+        )
         youMightLikeSection(
             albums = sections.youMightLikeAlbums,
             artists = sections.youMightLikeArtists,
@@ -510,6 +671,35 @@ private fun HomeSuccessContent(
     }
 }
 
+/**
+ * The dedicated "Songs like…" row (#1491). Reuses [PlaylistsRow]'s card
+ * rendering with a distinct title; hidden entirely when there's nothing
+ * to show (offline with no cached mixes). Online with none generated yet
+ * still shows a few placeholders so the building / seed-needed state is
+ * visible, matching the pre-promotion carousel behavior.
+ */
+private fun LazyListScope.songsLikeSection(
+    playlists: List<PlaylistRef>,
+    status: SystemPlaylistsStatus,
+    offline: Boolean,
+    onPlaylistClick: (String) -> Unit,
+    onPlayPool: (OfflinePoolKind) -> Unit,
+    onPlayPlaylist: suspend (PlaylistRef) -> Unit,
+) {
+    val rowItems = buildSongsLikeRow(playlists, status, offline)
+    if (rowItems.isEmpty()) return
+    item {
+        PlaylistsRow(
+            title = "Songs like…",
+            rowItems = rowItems,
+            offline = offline,
+            onPlaylistClick = onPlaylistClick,
+            onPlayPool = onPlayPool,
+            onPlayPlaylist = onPlayPlaylist,
+        )
+    }
+}
+
 private fun LazyListScope.recentlyAddedSection(
     albums: List<HomeTile<AlbumRef>>,
     onAlbumClick: (String) -> Unit,
@@ -779,13 +969,14 @@ private fun AlbumsRow(
 
 @Composable
 private fun PlaylistsRow(
+    title: String,
     rowItems: List<PlaylistRowItem>,
     offline: Boolean,
     onPlaylistClick: (String) -> Unit,
     onPlayPool: (OfflinePoolKind) -> Unit,
     onPlayPlaylist: suspend (PlaylistRef) -> Unit,
 ) {
-    HorizontalScrollRow(title = "Playlists") {
+    HorizontalScrollRow(title = title) {
         itemsIndexed(items = rowItems) { _, item ->
             when (item) {
                 is PlaylistRowItem.OfflinePool -> OfflinePoolCard(
@@ -836,11 +1027,12 @@ enum class OfflinePoolKind(val label: String) {
 /**
  * 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 —
+ * Online: For You + Discover 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.
+ * user-owned playlists. Songs-like has its own dedicated row (#1491) via
+ * [buildSongsLikeRow] and no longer appears in this carousel.
  *
  * Offline: the two cache-backed pools (Recently played, Liked) lead, then the
  * same real playlists in curated order but stably partitioned fully-cached
@@ -867,7 +1059,7 @@ internal fun buildPlaylistsRow(
     return out
 }
 
-/** The online layout: fixed system slots (with placeholders), secondary, user. */
+/** The online layout: For You + Discover slots (with placeholders), secondary, user. */
 private fun buildOnlineRow(
     owned: List<PlaylistRef>,
     status: SystemPlaylistsStatus,
@@ -879,12 +1071,7 @@ private fun buildOnlineRow(
     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(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))
-    }
+    // Songs-like is no longer here — it has its own dedicated row (#1491).
     for (variant in SECONDARY_SYSTEM_VARIANTS) {
         owned.firstOrNull { it.systemVariant == variant }?.let { out += PlaylistRowItem.Real(it) }
     }
@@ -892,16 +1079,44 @@ private fun buildOnlineRow(
     return out
 }
 
+/**
+ * Builds the dedicated Songs-like row (#1491): all "Songs like {artist}"
+ * mixes the server generated, no longer capped to the 3 carousel slots.
+ *
+ * Online: every generated mix as a real card; when none exist yet, a few
+ * placeholders so the building / seed-needed state stays visible.
+ * Offline: the cached mixes only (fully-cached first, greyed after), and
+ * an empty list — hiding the whole section — when nothing is cached.
+ */
+internal fun buildSongsLikeRow(
+    owned: List<PlaylistRef>,
+    status: SystemPlaylistsStatus,
+    offline: Boolean,
+): List<PlaylistRowItem> {
+    val mixes = owned.filter { it.systemVariant == "songs_like_artist" }
+    return when {
+        offline -> {
+            val (available, greyed) = mixes.partition { !it.unavailableOffline }
+            (available + greyed).map { PlaylistRowItem.Real(it) }
+        }
+        mixes.isNotEmpty() -> mixes.map { PlaylistRowItem.Real(it) }
+        else -> List(SONGS_LIKE_PLACEHOLDER_SLOTS) {
+            PlaylistRowItem.Placeholder("Songs like…", variantFor("songs-like", status))
+        }
+    }
+}
+
 /**
  * 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.
+ * Songs-like is excluded here too — it renders in its own row via
+ * [buildSongsLikeRow] in both online and offline modes (#1491).
  */
 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 }
     }
@@ -916,7 +1131,10 @@ private fun variantFor(slot: String, s: SystemPlaylistsStatus): String = when {
     else -> "pending"
 }
 
-private const val SONGS_LIKE_SLOTS = 3
+// How many "Songs like…" placeholder cards the dedicated row shows while
+// the mixes haven't generated yet (building / seed-needed). Real mixes,
+// once generated, are shown in full and no longer capped by this (#1491).
+private const val SONGS_LIKE_PLACEHOLDER_SLOTS = 3
 
 /**
  * The 5 system playlist kinds the server generates that aren't pinned

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

@@ -53,7 +53,7 @@ import com.fabledsword.minstrel.nav.AlbumDetail
 import com.fabledsword.minstrel.nav.ArtistDetail
 import com.fabledsword.minstrel.shared.formatDuration
 import com.fabledsword.minstrel.shared.widgets.TrackRow
-import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LikeButton
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.ServerImage
@@ -116,9 +116,10 @@ private fun AlbumDetailStateContent(
         when (val s = state) {
             is AlbumDetailUiState.Loading ->
                 if (s.seed != null) SeededAlbumLoading(s.seed) else SkeletonTrackList()
-            is AlbumDetailUiState.Error -> EmptyState(
+            is AlbumDetailUiState.Error -> ErrorRetry(
                 title = "Couldn't load album",
-                body = s.message,
+                message = s.message,
+                onRetry = { viewModel.refresh() },
             )
             is AlbumDetailUiState.Success -> {
                 val albumLiked by viewModel.albumLiked.collectAsStateWithLifecycle()

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

@@ -5,6 +5,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.toRoute
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.library.data.LibraryRepository
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.models.AlbumDetailRef
@@ -36,6 +38,7 @@ class AlbumDetailViewModel @Inject constructor(
     private val likes: LikesRepository,
     private val player: PlayerController,
     private val seedCache: DetailSeedCache,
+    networkStatus: NetworkStatusController,
     savedStateHandle: SavedStateHandle,
 ) : ViewModel() {
 
@@ -64,6 +67,14 @@ class AlbumDetailViewModel @Inject constructor(
 
     init {
         refresh()
+        // Screen-level auto-recovery (issue #1245): a detail that failed to
+        // load while the server was unreachable re-fetches when health
+        // returns, so coming back to the screen shows content, not an error.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is AlbumDetailUiState.Error) refresh()
+            }
+        }
     }
 
     fun refresh(): Job = viewModelScope.launch {

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

@@ -56,7 +56,7 @@ 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.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.HorizontalScrollRow
 import com.fabledsword.minstrel.shared.widgets.LikeButton
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -107,9 +107,10 @@ fun ArtistDetailScreen(
                         } else {
                             SkeletonArtistAlbumsGrid()
                         }
-                    is ArtistDetailUiState.Error -> EmptyState(
+                    is ArtistDetailUiState.Error -> ErrorRetry(
                         title = "Couldn't load artist",
-                        body = s.message,
+                        message = s.message,
+                        onRetry = { viewModel.refresh() },
                     )
                     is ArtistDetailUiState.Success ->
                         ArtistSuccessBody(s, viewModel, playerViewModel, navController)

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

@@ -5,6 +5,8 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.toRoute
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.library.data.LibraryRepository
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.models.ArtistDetailRef
@@ -45,6 +47,7 @@ class ArtistDetailViewModel @Inject constructor(
     private val likes: LikesRepository,
     private val player: PlayerController,
     private val seedCache: DetailSeedCache,
+    networkStatus: NetworkStatusController,
     savedStateHandle: SavedStateHandle,
 ) : ViewModel() {
 
@@ -69,6 +72,19 @@ class ArtistDetailViewModel @Inject constructor(
 
     init {
         refresh()
+        // Screen-level auto-recovery (issue #1245). From Error, redo the
+        // whole load; from Success, re-pull just the secondary sections —
+        // their fetch failures are swallowed to emptyList, so a dead zone
+        // during the first load leaves them permanently absent otherwise.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                when (internal.value) {
+                    is ArtistDetailUiState.Error -> refresh()
+                    is ArtistDetailUiState.Success -> loadSecondarySections()
+                    is ArtistDetailUiState.Loading -> Unit
+                }
+            }
+        }
     }
 
     fun toggleLikeArtist() {

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

@@ -24,11 +24,17 @@ class LibraryViewModel @Inject constructor(
         combine(
             repository.observeArtists(),
             repository.observeAlbums(),
-        ) { artists, albums ->
-            if (artists.isEmpty() && albums.isEmpty()) {
-                UiState.Empty
-            } else {
-                UiState.Success(LibraryData(artists, albums))
+            syncController.lastSyncError,
+        ) { artists, albums, syncError ->
+            when {
+                artists.isNotEmpty() || albums.isNotEmpty() ->
+                    UiState.Success(LibraryData(artists, albums))
+                // Empty cache + failed sync is a load failure, not an empty
+                // library — surface it so the user gets a Retry instead of
+                // the welcome copy. Heals automatically: SyncController
+                // re-syncs on health recovery, clearing lastSyncError.
+                syncError != null -> UiState.Error(syncError)
+                else -> UiState.Empty
             }
         }
             .asCacheFirstStateFlow(viewModelScope)

android/app/src/main/java/com/fabledsword/minstrel/likes/ui/LikedTab.kt

@@ -25,6 +25,9 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.NavHostController
+import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.likes.data.LikesRepository
 import com.fabledsword.minstrel.library.widgets.AlbumCard
 import com.fabledsword.minstrel.library.widgets.ArtistCard
@@ -38,6 +41,7 @@ import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.asCacheFirstStateFlow
 import com.fabledsword.minstrel.shared.widgets.TrackRow
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.HorizontalScrollRow
 import com.fabledsword.minstrel.shared.widgets.LikeButton
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
@@ -46,6 +50,7 @@ import com.fabledsword.minstrel.shared.widgets.TrackCoverThumb
 import com.fabledsword.minstrel.shared.widgets.trackactions.TrackActionsButton
 import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.launch
@@ -68,14 +73,25 @@ data class LikedSections(
 class LikedTabViewModel @Inject constructor(
     private val repository: LikesRepository,
     private val player: PlayerController,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
+    /** Copy for the most recent refresh failure; null once one succeeds. */
+    private val refreshError = MutableStateFlow<String?>(null)
+
     init {
         refresh()
+        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // health returns, so a load that failed offline heals unprompted.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refresh() }
+        }
     }
 
     fun refresh(): Job = viewModelScope.launch {
+        refreshError.value = null
         runCatching { repository.refreshIds() }
+            .onFailure { refreshError.value = ErrorCopy.fromThrowable(it) }
     }
 
     /**
@@ -92,9 +108,16 @@ class LikedTabViewModel @Inject constructor(
         repository.observeLikedArtists(),
         repository.observeLikedAlbums(),
         repository.observeLikedTracks(),
-    ) { artists, albums, tracks ->
+        refreshError,
+    ) { artists, albums, tracks, err ->
         val sections = LikedSections(artists, albums, tracks)
-        if (sections.isAllEmpty) UiState.Empty else UiState.Success(sections)
+        when {
+            !sections.isAllEmpty -> UiState.Success(sections)
+            // Empty cache + failed refresh is a load failure, not "no
+            // likes yet" — surface Error so the user gets a Retry.
+            err != null -> UiState.Error(err)
+            else -> UiState.Empty
+        }
     }.asCacheFirstStateFlow(viewModelScope)
 
     /**
@@ -130,9 +153,10 @@ fun LikedTab(
                 body = "Tap the heart on an artist, album, or track to start " +
                     "building your liked collection.",
             )
-            is UiState.Error -> EmptyState(
+            is UiState.Error -> ErrorRetry(
                 title = "Couldn't load likes",
-                body = s.message,
+                message = s.message,
+                onRetry = { viewModel.refresh() },
             )
             is UiState.Success -> LikedContent(
                 sections = s.data,

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

@@ -0,0 +1,19 @@
+package com.fabledsword.minstrel.models
+
+/** Domain model for one tag-enrichment provider in the admin surface (#1521). */
+data class AdminTagSourceRef(
+    val id: String,
+    val displayName: String,
+    val requiresApiKey: Boolean,
+    val supports: List<String>,
+    val enabled: Boolean,
+    val apiKeySet: Boolean,
+    val testable: Boolean,
+)
+
+/** Result of a provider "test connection" call. */
+data class TagSourceTestResult(
+    val ok: Boolean,
+    val durationMs: Long = 0,
+    val error: String = "",
+)

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

@@ -16,4 +16,11 @@ data class UserRef(
     val id: String,
     val username: String,
     val isAdmin: Boolean = false,
+    /**
+     * Account-level diagnostics opt-in (M9). NOT present in the login
+     * response (that's the narrow UserView) — populated by the /api/me
+     * refresh in AuthController so a remote admin flip reaches the
+     * device. Default false until the first refresh.
+     */
+    val debugModeEnabled: Boolean = false,
 )

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

@@ -0,0 +1,35 @@
+package com.fabledsword.minstrel.models.wire
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+/**
+ * Wire DTOs for the `/api/admin/tag-sources` admin surface (#1521).
+ * Every field defaults defensively so a missing JSON key never crashes
+ * deserialization. `versionBumped` is present only on the PATCH response.
+ */
+@Serializable
+data class AdminTagSourceWire(
+    val id: String = "",
+    @SerialName("display_name") val displayName: String = "",
+    @SerialName("requires_api_key") val requiresApiKey: Boolean = false,
+    val supports: List<String> = emptyList(),
+    val enabled: Boolean = false,
+    @SerialName("api_key_set") val apiKeySet: Boolean = false,
+    @SerialName("display_order") val displayOrder: Int = 0,
+    val testable: Boolean = false,
+    @SerialName("version_bumped") val versionBumped: Boolean = false,
+)
+
+@Serializable
+data class AdminTagSourcesListWire(
+    val providers: List<AdminTagSourceWire> = emptyList(),
+    @SerialName("sources_version") val sourcesVersion: Int = 0,
+)
+
+@Serializable
+data class TestTagSourceWire(
+    val ok: Boolean = false,
+    @SerialName("duration_ms") val durationMs: Long = 0,
+    val error: String = "",
+)

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

@@ -27,6 +27,8 @@ data class PlayStartedRequest(
     @SerialName("track_id") val trackId: String,
     @SerialName("client_id") val clientId: String,
     val source: String? = null,
+    // #1551: device class for context conditioning (server normalizes).
+    @SerialName("device_class") val deviceClass: String? = null,
 )
 
 @Serializable
@@ -56,4 +58,6 @@ data class PlayOfflineRequest(
     val at: String,
     @SerialName("duration_played_ms") val durationPlayedMs: Long,
     val source: String? = null,
+    // #1551: device class for context conditioning (server normalizes).
+    @SerialName("device_class") val deviceClass: String? = null,
 )

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

@@ -18,4 +18,5 @@ data class MyProfileWire(
     @SerialName("display_name") val displayName: String? = null,
     val email: String? = null,
     @SerialName("is_admin") val isAdmin: Boolean = false,
+    @SerialName("debug_mode_enabled") val debugModeEnabled: Boolean = false,
 )

android/app/src/main/java/com/fabledsword/minstrel/nav/MinstrelNavGraph.kt

@@ -16,6 +16,7 @@ import androidx.navigation.compose.composable
 import com.fabledsword.minstrel.admin.ui.AdminLandingScreen
 import com.fabledsword.minstrel.admin.ui.AdminQuarantineScreen
 import com.fabledsword.minstrel.admin.ui.AdminRequestsScreen
+import com.fabledsword.minstrel.admin.ui.AdminTagSourcesScreen
 import com.fabledsword.minstrel.admin.ui.AdminUsersScreen
 import com.fabledsword.minstrel.auth.ui.LoginScreen
 import com.fabledsword.minstrel.auth.ui.ServerUrlScreen
@@ -190,6 +191,13 @@ private fun NavGraphBuilder.inShellDetail(
             }
         }
     }
+    composable<AdminTagSources> {
+        WithAnimatedScope {
+            ShellScaffold(onExpandPlayer = expandPlayer) {
+                AdminTagSourcesScreen(navController = navController)
+            }
+        }
+    }
 }
 
 private fun NavGraphBuilder.outsideShell(navController: NavHostController) {

android/app/src/main/java/com/fabledsword/minstrel/nav/Routes.kt

@@ -22,6 +22,7 @@ import kotlinx.serialization.Serializable
 @Serializable data object AdminRequests
 @Serializable data object AdminQuarantine
 @Serializable data object AdminUsers
+@Serializable data object AdminTagSources
 
 // ── Outside-shell full-screen routes ──────────────────────────────────
 

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

@@ -155,6 +155,7 @@ class PlayEventsReporter @Inject constructor(
                         trackId = trackId,
                         clientId = cid,
                         source = source.takeIf { !it.isNullOrEmpty() },
+                        deviceClass = DEVICE_CLASS,
                     ),
                 )
                 if (curTrackId == trackId) {
@@ -248,6 +249,7 @@ class PlayEventsReporter @Inject constructor(
                     atIso = startedAt.toString(),
                     durationPlayedMs = durationPlayedMs,
                     source = source.takeIf { !it.isNullOrEmpty() },
+                    deviceClass = DEVICE_CLASS,
                 ),
             )
         }
@@ -268,6 +270,12 @@ class PlayEventsReporter @Inject constructor(
 
     // ── Lifecycle: durable-close on app background / detach ────────
 
+    companion object {
+        // #1551: Android is a mobile client. Refine to tablet/tv via device
+        // configuration later if the metrics trend view shows it matters.
+        private const val DEVICE_CLASS = "mobile"
+    }
+
     override fun onStop(owner: LifecycleOwner) {
         // App backgrounded. If the tracked play is still PLAYING, leave it
         // alone: the foreground media service keeps the process — and this

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

@@ -133,7 +133,7 @@ private fun RouteRow(
                     maxLines = 2,
                     overflow = TextOverflow.Ellipsis,
                 )
-                val subtitle = route.description ?: defaultSubtitle(route)
+                val subtitle = route.description ?: defaultSubtitle(route, isSelected)
                 Text(
                     text = subtitle,
                     style = MaterialTheme.typography.bodySmall,
@@ -198,10 +198,13 @@ private fun MulticastHintRow() {
     }
 }
 
-private fun defaultSubtitle(route: OutputRoute): String = when (route.kind) {
+// isSelected (route == the active/selected route) drives the Bluetooth
+// "Connected" subtitle. RouteInfo.connectionState can't — it stays
+// DISCONNECTED for local SYSTEM routes even when they're in use.
+private fun defaultSubtitle(route: OutputRoute, isSelected: Boolean): String = when (route.kind) {
     OutputRoute.Kind.BuiltIn -> "Phone speaker"
     OutputRoute.Kind.Wired -> "Wired"
-    OutputRoute.Kind.Bluetooth -> if (route.isConnected) "Connected" else "Available"
+    OutputRoute.Kind.Bluetooth -> if (isSelected) "Connected" else "Available"
     OutputRoute.Kind.Cast -> "Cast"
     OutputRoute.Kind.Other -> "Available"
 }

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

@@ -21,7 +21,6 @@ data class OutputRoute(
     val description: String?,
     val kind: Kind,
     val protocol: Protocol,
-    val isConnected: Boolean,
 ) {
     enum class Kind { BuiltIn, Wired, Bluetooth, Cast, Other }
 
@@ -43,9 +42,11 @@ data class OutputRoute(
         /**
          * Lift a MediaRouter [route] into the domain model. Kind is
          * inferred from [MediaRouter.RouteInfo.getDeviceType]; unknown
-         * device types fall through to [Kind.Other]. The
-         * `connectionState` proxy is good enough for the chip's
-         * "Connected"/"Available" subtitle.
+         * device types fall through to [Kind.Other]. "Active" is NOT an
+         * intrinsic of the route — the caller derives it by comparing to
+         * the selected route (RouteSnapshot.current), because
+         * RouteInfo.connectionState only reflects remote-route handshakes
+         * and stays DISCONNECTED for local SYSTEM routes even when in use.
          */
         fun fromRouteInfo(route: MediaRouter.RouteInfo): OutputRoute {
             val kind = when (route.deviceType) {
@@ -58,15 +59,12 @@ data class OutputRoute(
                 MediaRouter.RouteInfo.DEVICE_TYPE_SPEAKER -> Kind.Other
                 else -> Kind.Other
             }
-            val connected =
-                route.connectionState == MediaRouter.RouteInfo.CONNECTION_STATE_CONNECTED
             return OutputRoute(
                 id = route.id,
                 name = route.name,
                 description = route.description,
                 kind = kind,
                 protocol = Protocol.SYSTEM,
-                isConnected = connected,
             )
         }
 
@@ -76,10 +74,10 @@ data class OutputRoute(
          * network speakers into the same `OutputPickerController`
          * routes stream the system routes come through.
          *
-         * `isConnected = false` because UPnP devices have no
-         * MediaRouter connection-state concept — they're always
-         * "available" on the LAN, and the picker's selected-route
-         * rendering handles the "currently playing" indicator.
+         * UPnP devices have no MediaRouter connection-state concept —
+         * they're always "available" on the LAN, and the picker's
+         * selected-route rendering handles the "currently playing"
+         * indicator.
          *
          * Subtitle is `manufacturer modelName` joined by a single
          * space, falling back to "Network speaker" when both fields
@@ -96,7 +94,6 @@ data class OutputRoute(
                 description = description,
                 kind = Kind.Other,
                 protocol = Protocol.UPNP,
-                isConnected = false,
             )
         }
     }

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

@@ -38,9 +38,7 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 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.draw.clip
@@ -60,6 +58,8 @@ import com.composables.icons.lucide.Play
 import com.composables.icons.lucide.RefreshCw
 import com.composables.icons.lucide.Shuffle
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.events.LiveEvent
 import com.fabledsword.minstrel.models.PlaylistRef
@@ -76,6 +76,7 @@ import com.fabledsword.minstrel.playlists.data.PlaylistsRepository
 import com.fabledsword.minstrel.playlists.data.toPlayableTrackRefs
 import com.fabledsword.minstrel.shared.formatDuration
 import com.fabledsword.minstrel.shared.widgets.TrackRow
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LikeButton
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.SkeletonTrackRow
@@ -117,6 +118,7 @@ class PlaylistDetailViewModel @Inject constructor(
     private val player: PlayerController,
     private val eventsStream: EventsStream,
     private val seedCache: DetailSeedCache,
+    networkStatus: NetworkStatusController,
     savedStateHandle: SavedStateHandle,
 ) : ViewModel() {
 
@@ -167,6 +169,14 @@ class PlaylistDetailViewModel @Inject constructor(
                 .filter { it.kind.startsWith("playlist.") }
                 .collect { handlePlaylistEvent(it) }
         }
+        // Screen-level auto-recovery (issue #1245): a detail that failed to
+        // load while the server was unreachable re-fetches when health
+        // returns, instead of waiting for the Retry tap.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is PlaylistDetailUiState.Error) refresh()
+            }
+        }
     }
 
     /**
@@ -369,7 +379,11 @@ private fun PlaylistDetailContent(
     Crossfade(targetState = state::class, label = "playlist-detail") { _ -> when (val s = state) {
         is PlaylistDetailUiState.Loading ->
             s.seed?.let { SeededPlaylistLoading(it) } ?: SkeletonPlaylistTrackList()
-        is PlaylistDetailUiState.Error -> ErrorBlock(s.message, viewModel::refresh)
+        is PlaylistDetailUiState.Error -> ErrorRetry(
+            title = "Couldn't load playlist",
+            message = s.message,
+            onRetry = { viewModel.refresh() },
+        )
         is PlaylistDetailUiState.Success -> {
             val likedTrackIds by viewModel.likedTrackIds.collectAsState()
             val playerState by playerViewModel.uiState.collectAsState()
@@ -653,33 +667,6 @@ private fun SeededPlaylistLoading(seed: PlaylistRef) {
     }
 }
 
-@Composable
-private fun ErrorBlock(message: String, onRetry: () -> Unit) {
-    var retried by remember { mutableStateOf(false) }
-    Column(
-        modifier = Modifier
-            .fillMaxSize()
-            .padding(24.dp),
-        verticalArrangement = Arrangement.Center,
-        horizontalAlignment = Alignment.CenterHorizontally,
-    ) {
-        Text(
-            text = message,
-            color = MaterialTheme.colorScheme.error,
-            style = MaterialTheme.typography.bodyLarge,
-        )
-        Spacer(Modifier.height(12.dp))
-        OutlinedButton(
-            onClick = {
-                if (!retried) {
-                    retried = true
-                    onRetry()
-                }
-            },
-        ) { Text("Retry") }
-    }
-}
-
 // ─── Helpers ─────────────────────────────────────────────────────────
 
 private const val UNAVAILABLE_ALPHA = 0.4f

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

@@ -27,8 +27,10 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.compose.collectAsStateWithLifecycle
 import androidx.lifecycle.viewModelScope
 import androidx.navigation.NavHostController
+import com.fabledsword.minstrel.api.ErrorCopy
 import com.fabledsword.minstrel.connectivity.NetworkStatusController
 import com.fabledsword.minstrel.connectivity.ServerHealth
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.PlaylistRef
 import com.fabledsword.minstrel.nav.PlaylistDetail
@@ -40,6 +42,7 @@ import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.asCacheFirstStateFlow
 import com.fabledsword.minstrel.playlists.widgets.PlaylistCard
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -47,8 +50,10 @@ import dagger.hilt.android.lifecycle.HiltViewModel
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.channels.Channel
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.flow.receiveAsFlow
@@ -84,6 +89,9 @@ class PlaylistsListViewModel @Inject constructor(
             initialValue = false,
         )
 
+    /** Copy for the most recent list-refresh failure; null once one succeeds. */
+    private val refreshError = MutableStateFlow<String?>(null)
+
     init {
         refresh()
         // Live updates: a playlist created/updated/deleted from another
@@ -93,11 +101,18 @@ class PlaylistsListViewModel @Inject constructor(
                 .filter { it.kind.startsWith("playlist.") }
                 .collect { refresh() }
         }
+        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // health returns, so a load that failed offline heals unprompted.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refresh() }
+        }
     }
 
     /** Re-pull the playlists list. Returns the Job for pull-to-refresh awaits. */
     fun refresh(): Job = viewModelScope.launch {
+        refreshError.value = null
         runCatching { repository.refreshList() }
+            .onFailure { refreshError.value = ErrorCopy.fromThrowable(it) }
     }
 
     /** Tile play button: shuffle the playlist's tracks and start at index 0. */
@@ -110,14 +125,15 @@ class PlaylistsListViewModel @Inject constructor(
     }
 
     val uiState: StateFlow<UiState<List<PlaylistRef>>> =
-        repository.observeAll()
-            .map { list ->
-                if (list.isEmpty()) {
-                    UiState.Empty
-                } else {
-                    UiState.Success(list)
-                }
+        combine(repository.observeAll(), refreshError) { list, err ->
+            when {
+                list.isNotEmpty() -> UiState.Success(list)
+                // Empty cache + failed refresh is a load failure, not "no
+                // playlists yet" — surface Error so the user gets a Retry.
+                err != null -> UiState.Error(err)
+                else -> UiState.Empty
             }
+        }
             .asCacheFirstStateFlow(viewModelScope)
 }
 
@@ -157,9 +173,10 @@ fun PlaylistsListScreen(
                         "appear once your library has enough plays. Create your " +
                         "own playlist from any album or track in the meantime.",
                 )
-                is UiState.Error -> EmptyState(
+                is UiState.Error -> ErrorRetry(
                     title = "Couldn't load playlists",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                 )
                 is UiState.Success -> PlaylistsGrid(
                     playlists = s.data,

android/app/src/main/java/com/fabledsword/minstrel/quarantine/ui/HiddenTab.kt

@@ -27,6 +27,7 @@ import com.composables.icons.lucide.Lucide
 import com.fabledsword.minstrel.models.QuarantineRef
 import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
 import com.fabledsword.minstrel.shared.widgets.TrackCoverThumb
@@ -43,9 +44,10 @@ fun HiddenTab(viewModel: HiddenTabViewModel = hiltViewModel()) {
                     "and it'll show up here. The track stays out of system " +
                     "playlists until you unhide it.",
             )
-            is UiState.Error -> EmptyState(
+            is UiState.Error -> ErrorRetry(
                 title = "Couldn't load hidden tracks",
-                body = s.message,
+                message = s.message,
+                onRetry = { viewModel.refresh() },
             )
             is UiState.Success -> HiddenList(
                 rows = s.data,

android/app/src/main/java/com/fabledsword/minstrel/quarantine/ui/HiddenTabViewModel.kt

@@ -3,6 +3,8 @@ package com.fabledsword.minstrel.quarantine.ui
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.QuarantineRef
 import com.fabledsword.minstrel.shared.UiState
@@ -24,6 +26,7 @@ private const val SHARE_STOP_TIMEOUT_MS = 5_000L
 class HiddenTabViewModel @Inject constructor(
     private val repository: QuarantineRepository,
     private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val refreshError = MutableStateFlow<String?>(null)
@@ -61,6 +64,11 @@ class HiddenTabViewModel @Inject constructor(
                 .filter { it.kind.startsWith("quarantine.") }
                 .collect { refresh() }
         }
+        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // health returns, so a load that failed offline heals unprompted.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect { refresh() }
+        }
     }
 
     fun refresh(): Job = viewModelScope.launch {

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

@@ -46,6 +46,7 @@ import com.fabledsword.minstrel.shared.UiState
 import com.fabledsword.minstrel.nav.ArtistDetail
 import com.fabledsword.minstrel.nav.Requests
 import com.fabledsword.minstrel.shared.widgets.EmptyState
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MinstrelTopAppBar
 import com.fabledsword.minstrel.shared.widgets.PullToRefreshScaffold
@@ -78,9 +79,10 @@ fun RequestsScreen(
                     body = "Use Discover to ask Lidarr for new music; your " +
                         "requests show up here.",
                 )
-                is UiState.Error -> EmptyState(
+                is UiState.Error -> ErrorRetry(
                     title = "Couldn't load requests",
-                    body = s.message,
+                    message = s.message,
+                    onRetry = { viewModel.refresh() },
                 )
                 is UiState.Success -> RequestList(
                     rows = s.data,

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

@@ -3,6 +3,8 @@ package com.fabledsword.minstrel.requests.ui
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.events.EventsStream
 import com.fabledsword.minstrel.models.RequestRef
 import com.fabledsword.minstrel.models.RequestStatus
@@ -30,6 +32,7 @@ private const val POLL_INTERVAL_MS = 12_000L
 class RequestsViewModel @Inject constructor(
     private val repository: RequestsRepository,
     private val eventsStream: EventsStream,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val internal = MutableStateFlow<UiState<List<RequestRef>>>(UiState.Loading)
@@ -45,6 +48,14 @@ class RequestsViewModel @Inject constructor(
                 .collect { silentReload() }
         }
         viewModelScope.launch { pollWhileInFlight() }
+        // Screen-level auto-recovery (issue #1245): a load that failed while
+        // the server was unreachable heals the moment health returns, without
+        // waiting for the next poll tick.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value is UiState.Error) silentReload()
+            }
+        }
     }
 
     fun refresh(): Job = viewModelScope.launch {
@@ -71,7 +82,11 @@ class RequestsViewModel @Inject constructor(
      */
     private suspend fun pollWhileInFlight() {
         while (true) {
-            if (hasInFlightRequest()) {
+            // Also retry from a failed load (issue #1245): from UiState.Error
+            // the in-flight predicate can never become true, so without this
+            // the poll never self-heals the screen — e.g. after a transient
+            // 500 that health monitoring (transport-level) never saw.
+            if (hasInFlightRequest() || internal.value is UiState.Error) {
                 silentReload()
             }
             delay(POLL_INTERVAL_MS)

android/app/src/main/java/com/fabledsword/minstrel/search/ui/SearchScreen.kt

@@ -56,6 +56,7 @@ import com.fabledsword.minstrel.nav.AlbumDetail
 import com.fabledsword.minstrel.nav.ArtistDetail
 import com.fabledsword.minstrel.nav.Search as SearchRoute
 import com.fabledsword.minstrel.shared.widgets.TrackRow
+import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 import com.fabledsword.minstrel.shared.widgets.LoadingCentered
 import com.fabledsword.minstrel.shared.widgets.MainAppBarActions
 import com.fabledsword.minstrel.shared.widgets.TrackCoverThumb
@@ -113,6 +114,7 @@ fun SearchScreen(
                 onTrackPlay = viewModel::playTrack,
                 onNavigateToAlbum = { id -> navController.navigate(AlbumDetail(id)) },
                 onNavigateToArtist = { id -> navController.navigate(ArtistDetail(id)) },
+                onRetry = viewModel::retry,
             )
         }
     }
@@ -151,11 +153,16 @@ private fun ResultsPane(
     onTrackPlay: (TrackRef) -> Unit,
     onNavigateToAlbum: (String) -> Unit,
     onNavigateToArtist: (String) -> Unit,
+    onRetry: () -> Unit,
 ) {
     when (state) {
         SearchResultsState.Idle -> CenteredHint("Type to search your library.")
         SearchResultsState.Loading -> LoadingCentered()
-        is SearchResultsState.Error -> CenteredHint("Search failed: ${state.message}")
+        is SearchResultsState.Error -> ErrorRetry(
+            title = "Search failed",
+            message = state.message,
+            onRetry = onRetry,
+        )
         is SearchResultsState.Loaded -> {
             if (state.response.isEmpty) {
                 CenteredHint(

android/app/src/main/java/com/fabledsword/minstrel/search/ui/SearchViewModel.kt

@@ -3,6 +3,8 @@ package com.fabledsword.minstrel.search.ui
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.fabledsword.minstrel.api.ErrorCopy
+import com.fabledsword.minstrel.connectivity.NetworkStatusController
+import com.fabledsword.minstrel.connectivity.recoveries
 import com.fabledsword.minstrel.models.SearchResponseRef
 import com.fabledsword.minstrel.models.TrackRef
 import com.fabledsword.minstrel.player.PlayerController
@@ -43,6 +45,7 @@ data class SearchState(
 class SearchViewModel @Inject constructor(
     private val repository: SearchRepository,
     private val player: PlayerController,
+    networkStatus: NetworkStatusController,
 ) : ViewModel() {
 
     private val queryFlow = MutableStateFlow("")
@@ -69,6 +72,14 @@ class SearchViewModel @Inject constructor(
                     runSearch(q)
                 }
         }
+        // Screen-level auto-recovery (issue #1245): a search that failed
+        // while the server was unreachable re-runs when health returns —
+        // the queryFlow pipeline can't, since the text hasn't changed.
+        viewModelScope.launch {
+            networkStatus.recoveries().collect {
+                if (internal.value.results is SearchResultsState.Error) retry()
+            }
+        }
     }
 
     fun setQuery(value: String) {
@@ -80,6 +91,18 @@ class SearchViewModel @Inject constructor(
         setQuery("")
     }
 
+    /**
+     * Re-run the current query after a failure. Bypasses the queryFlow
+     * pipeline, whose distinctUntilChanged drops a same-text resubmit —
+     * without this, a transient error pins "Search failed" until the
+     * user edits the query.
+     */
+    fun retry() {
+        val q = internal.value.query.trim()
+        if (q.isEmpty()) return
+        viewModelScope.launch { runSearch(q) }
+    }
+
     /**
      * Tapping a search result builds a queue from the full visible
      * track-results list starting at the tapped entry, matching Flutter.

android/app/src/main/java/com/fabledsword/minstrel/settings/ui/SettingsScreen.kt

@@ -28,6 +28,7 @@ import androidx.compose.material3.Scaffold
 import androidx.compose.material3.SegmentedButton
 import androidx.compose.material3.SegmentedButtonDefaults
 import androidx.compose.material3.SingleChoiceSegmentedButtonRow
+import androidx.compose.material3.Switch
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
@@ -94,6 +95,7 @@ fun SettingsScreen(
             onPickTheme = themeVm::setThemeMode,
             onNavToRequests = { navController.navigate(Requests) },
             onNavToAdmin = { navController.navigate(Admin) },
+            onToggleDiagnostics = viewModel::setDiagnosticsOptOut,
             onSignOutClick = { showSignOutConfirm = true },
         )
     }
@@ -116,6 +118,7 @@ private fun SettingsList(
     onPickTheme: (ThemeMode) -> Unit,
     onNavToRequests: () -> Unit,
     onNavToAdmin: () -> Unit,
+    onToggleDiagnostics: (Boolean) -> Unit,
     onSignOutClick: () -> Unit,
 ) {
     Column(
@@ -148,6 +151,12 @@ private fun SettingsList(
         ProfileCard()
         PasswordCard()
         ListenBrainzCard()
+        if (state.diagnosticsEnabledByAdmin) {
+            DiagnosticsCard(
+                optOut = state.diagnosticsOptOut,
+                onToggle = onToggleDiagnostics,
+            )
+        }
         AppearanceCard(themeMode = themeMode, onPick = onPickTheme)
         StorageCard()
         AboutCard()
@@ -262,6 +271,46 @@ private fun AccountCard(username: String, isAdmin: Boolean, serverUrl: String) {
     }
 }
 
+// Shown only while an admin has enabled debug mode on this account. Lets
+// the user turn reporting OFF on this device (battery/privacy) without
+// touching the account flag. Checked = reporting on = NOT opted out.
+@Composable
+private fun DiagnosticsCard(optOut: Boolean, onToggle: (Boolean) -> Unit) {
+    ElevatedCard(modifier = Modifier.fillMaxWidth()) {
+        Column(
+            modifier = Modifier.padding(16.dp),
+            verticalArrangement = Arrangement.spacedBy(8.dp),
+        ) {
+            Text(
+                text = "Diagnostics",
+                style = MaterialTheme.typography.titleMedium,
+                color = MaterialTheme.colorScheme.onSurface,
+            )
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                Column(modifier = Modifier.weight(1f)) {
+                    Text(
+                        text = "Send diagnostic reports",
+                        style = MaterialTheme.typography.bodyLarge,
+                        color = MaterialTheme.colorScheme.onSurface,
+                    )
+                    Text(
+                        text = "Your admin enabled debug mode to investigate an " +
+                            "issue. This device streams connectivity and playback " +
+                            "diagnostics. Turn off any time.",
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                Spacer(Modifier.size(12.dp))
+                Switch(
+                    checked = !optOut,
+                    onCheckedChange = { checked -> onToggle(!checked) },
+                )
+            }
+        }
+    }
+}
+
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 private fun AppearanceCard(themeMode: ThemeMode, onPick: (ThemeMode) -> Unit) {

android/app/src/main/java/com/fabledsword/minstrel/settings/ui/SettingsViewModel.kt

@@ -19,12 +19,15 @@ data class SettingsState(
     val isAdmin: Boolean = false,
     val isSigningOut: Boolean = false,
     val signedOut: Boolean = false,
+    // M9: account debug flag (admin-set) + this device's local opt-out.
+    val diagnosticsEnabledByAdmin: Boolean = false,
+    val diagnosticsOptOut: Boolean = false,
 )
 
 @HiltViewModel
 class SettingsViewModel @Inject constructor(
     private val authController: AuthController,
-    authStore: AuthStore,
+    private val authStore: AuthStore,
 ) : ViewModel() {
 
     private val transient = MutableStateFlow(TransientState())
@@ -41,19 +44,27 @@ class SettingsViewModel @Inject constructor(
             combine(
                 authStore.baseUrl,
                 authController.currentUser,
+                authStore.diagnosticsOptOut,
                 transient,
-            ) { url, user, t ->
+            ) { url, user, optOut, t ->
                 SettingsState(
                     serverUrl = url,
                     username = user?.username.orEmpty(),
                     isAdmin = user?.isAdmin == true,
                     isSigningOut = t.isSigningOut,
                     signedOut = t.signedOut,
+                    diagnosticsEnabledByAdmin = user?.debugModeEnabled == true,
+                    diagnosticsOptOut = optOut,
                 )
             }.collect { internal.value = it }
         }
     }
 
+    /** Per-device opt-out of diagnostics while the account flag is on. */
+    fun setDiagnosticsOptOut(optOut: Boolean) {
+        authStore.setDiagnosticsOptOut(optOut)
+    }
+
     fun signOut() {
         if (transient.value.isSigningOut) return
         viewModelScope.launch {

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

@@ -23,8 +23,12 @@ import com.fabledsword.minstrel.theme.FabledSwordFlatTokens
  * ServerImage + fallback structure was identical at all three sites.
  *
  * [overlay] is a `BoxScope` slot for things drawn on top of the cover
- * (e.g. the `VariantPill` system-playlist label) — callers can use
- * `Modifier.align(...)` inside it.
+ * (e.g. the `VariantPill` system-playlist label, the play button) —
+ * callers can use `Modifier.align(...)` inside it. The overlay sits on
+ * an outer, UN-clipped box so corner-anchored widgets are not cut off by
+ * [shape]: a `BottomEnd` play button on a `CircleShape` avatar falls in
+ * the square's corner, outside the circle, and would otherwise be clipped
+ * away. Only the artwork + background are clipped to [shape].
  */
 @Composable
 fun CoverTile(
@@ -38,18 +42,23 @@ fun CoverTile(
     overlay: @Composable BoxScope.() -> Unit = {},
 ) {
     Box(
-        modifier = modifier
-            .size(size)
-            .clip(shape)
-            .background(background),
+        modifier = modifier.size(size),
         contentAlignment = Alignment.Center,
     ) {
-        ServerImage(
-            url = url,
-            contentDescription = contentDescription,
-            modifier = Modifier.fillMaxSize(),
+        Box(
+            modifier = Modifier
+                .fillMaxSize()
+                .clip(shape)
+                .background(background),
+            contentAlignment = Alignment.Center,
         ) {
-            fallback()
+            ServerImage(
+                url = url,
+                contentDescription = contentDescription,
+                modifier = Modifier.fillMaxSize(),
+            ) {
+                fallback()
+            }
         }
         overlay()
     }

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

@@ -5,6 +5,7 @@ import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.lazy.LazyColumn
 import androidx.compose.material3.Button
 import androidx.compose.material3.ButtonDefaults
 import androidx.compose.material3.Icon
@@ -23,44 +24,63 @@ import com.fabledsword.minstrel.theme.LocalActionColors
  * Shared error-with-retry widget. Surfaces a brief message and a
  * primary action button. Per the design system, the button uses
  * `LocalActionColors.primary` (Moss) — NEVER the accent.
+ *
+ * Renders inside a single-item LazyColumn (same rationale as
+ * [EmptyState]) so the widget participates in nested-scroll dispatch
+ * under PullToRefreshBox — both the Retry button and a pull gesture
+ * can recover from the error state.
  */
 @Composable
 fun ErrorRetry(
     message: String,
     onRetry: () -> Unit,
     modifier: Modifier = Modifier,
+    title: String? = null,
     retryLabel: String = "Retry",
 ) {
     val actionColors = LocalActionColors.current
-    Column(
-        modifier = modifier
-            .fillMaxSize()
-            .padding(32.dp),
-        verticalArrangement = Arrangement.Center,
-        horizontalAlignment = Alignment.CenterHorizontally,
-    ) {
-        Icon(
-            imageVector = Lucide.TriangleAlert,
-            contentDescription = null,
-            modifier = Modifier.size(48.dp),
-            tint = MaterialTheme.colorScheme.error,
-        )
-        Text(
-            text = message,
-            modifier = Modifier.padding(top = 16.dp),
-            style = MaterialTheme.typography.bodyMedium,
-            color = MaterialTheme.colorScheme.onSurface,
-            textAlign = TextAlign.Center,
-        )
-        Button(
-            onClick = onRetry,
-            modifier = Modifier.padding(top = 16.dp),
-            colors = ButtonDefaults.buttonColors(
-                containerColor = actionColors.primary,
-                contentColor = actionColors.onAction,
-            ),
-        ) {
-            Text(retryLabel)
+    LazyColumn(modifier = modifier.fillMaxSize()) {
+        item {
+            Column(
+                modifier = Modifier
+                    .fillParentMaxSize()
+                    .padding(32.dp),
+                verticalArrangement = Arrangement.Center,
+                horizontalAlignment = Alignment.CenterHorizontally,
+            ) {
+                Icon(
+                    imageVector = Lucide.TriangleAlert,
+                    contentDescription = null,
+                    modifier = Modifier.size(48.dp),
+                    tint = MaterialTheme.colorScheme.error,
+                )
+                if (title != null) {
+                    Text(
+                        text = title,
+                        modifier = Modifier.padding(top = 16.dp),
+                        style = MaterialTheme.typography.titleMedium,
+                        color = MaterialTheme.colorScheme.onSurface,
+                        textAlign = TextAlign.Center,
+                    )
+                }
+                Text(
+                    text = message,
+                    modifier = Modifier.padding(top = if (title != null) 8.dp else 16.dp),
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurface,
+                    textAlign = TextAlign.Center,
+                )
+                Button(
+                    onClick = onRetry,
+                    modifier = Modifier.padding(top = 16.dp),
+                    colors = ButtonDefaults.buttonColors(
+                        containerColor = actionColors.primary,
+                        contentColor = actionColors.onAction,
+                    ),
+                ) {
+                    Text(retryLabel)
+                }
+            }
         }
     }
 }

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

@@ -56,4 +56,51 @@ class BuildPlaylistsRowTest {
         assertTrue(row.none { it is PlaylistRowItem.OfflinePool })
         assertTrue(row.any { it is PlaylistRowItem.Placeholder })
     }
+
+    private fun songsLike(id: String, cached: Boolean) = PlaylistRef(
+        id = id,
+        userId = "u",
+        name = "Songs like $id",
+        systemVariant = "songs_like_artist",
+        trackCount = 25,
+        fullyCached = cached,
+    )
+
+    @Test
+    fun `songs-like no longer appears in the main playlists carousel`() {
+        val owned = listOf(songsLike("a", cached = true), user("u1", cached = true))
+        val row = buildPlaylistsRow(owned, SystemPlaylistsStatus(), offline = false)
+        val reals = row.filterIsInstance<PlaylistRowItem.Real>().map { it.playlist.id }
+        assertTrue("a" !in reals, "songs-like mix leaked into the Playlists row: $reals")
+        assertTrue("u1" in reals)
+    }
+
+    @Test
+    fun `online songs-like row shows every generated mix uncapped`() {
+        // Six generated mixes — the old carousel capped at 3; the dedicated row shows all.
+        val owned = (1..6).map { songsLike("a$it", cached = true) }
+        val row = buildSongsLikeRow(owned, SystemPlaylistsStatus(), offline = false)
+        val reals = row.filterIsInstance<PlaylistRowItem.Real>().map { it.playlist.id }
+        assertEquals((1..6).map { "a$it" }, reals)
+    }
+
+    @Test
+    fun `online songs-like row shows placeholders when none generated`() {
+        val row = buildSongsLikeRow(emptyList(), SystemPlaylistsStatus(), offline = false)
+        assertTrue(row.isNotEmpty())
+        assertTrue(row.all { it is PlaylistRowItem.Placeholder })
+    }
+
+    @Test
+    fun `offline songs-like row shows cached mixes available-first, none hides it`() {
+        val owned = listOf(songsLike("partial", cached = false), songsLike("full", cached = true))
+        val row = buildSongsLikeRow(owned, SystemPlaylistsStatus(), offline = true)
+        val reals = row.filterIsInstance<PlaylistRowItem.Real>().map { it.playlist.id }
+        // Fully-cached songs-like mix (not refreshable) is available; the
+        // un-cached one greys and sorts after. No placeholders offline.
+        assertEquals(listOf("full", "partial"), reals)
+        assertTrue(row.none { it is PlaylistRowItem.Placeholder })
+
+        assertTrue(buildSongsLikeRow(emptyList(), SystemPlaylistsStatus(), offline = true).isEmpty())
+    }
 }

android/app/src/test/java/com/fabledsword/minstrel/library/ui/LibraryViewModelTest.kt

@@ -11,6 +11,7 @@ import com.fabledsword.minstrel.testutil.MainDispatcherExtension
 import io.mockk.every
 import io.mockk.mockk
 import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.flow
 import kotlinx.coroutines.flow.flowOf
 import kotlinx.coroutines.test.runTest
@@ -21,6 +22,13 @@ import kotlin.test.assertEquals
 @ExtendWith(MainDispatcherExtension::class)
 class LibraryViewModelTest {
 
+    // lastSyncError needs a real StateFlow: the VM combines it into uiState,
+    // and a relaxed-mock flow never emits, so the combine would never fire.
+    private fun syncControllerMock(): SyncController =
+        mockk<SyncController>(relaxed = true) {
+            every { lastSyncError } returns MutableStateFlow(null)
+        }
+
     @Test
     fun `initial state is Loading before any DAO emission`() = runTest {
         val repo = mockk<LibraryRepository>()
@@ -29,7 +37,7 @@ class LibraryViewModelTest {
 
         val vm = LibraryViewModel(
             repo,
-            mockk<SyncController>(relaxed = true),
+            syncControllerMock(),
             mockk<PlayerController>(relaxed = true),
         )
 
@@ -51,7 +59,7 @@ class LibraryViewModelTest {
 
         val vm = LibraryViewModel(
             repo,
-            mockk<SyncController>(relaxed = true),
+            syncControllerMock(),
             mockk<PlayerController>(relaxed = true),
         )
 
@@ -71,7 +79,7 @@ class LibraryViewModelTest {
 
         val vm = LibraryViewModel(
             repo,
-            mockk<SyncController>(relaxed = true),
+            syncControllerMock(),
             mockk<PlayerController>(relaxed = true),
         )
 
@@ -94,7 +102,7 @@ class LibraryViewModelTest {
 
         val vm = LibraryViewModel(
             repo,
-            mockk<SyncController>(relaxed = true),
+            syncControllerMock(),
             mockk<PlayerController>(relaxed = true),
         )
 

cmd/minstrel/main.go

@@ -15,6 +15,7 @@ import (
 	"github.com/jackc/pgx/v5/pgxpool"
 
 	"git.fabledsword.com/bvandeusen/minstrel/internal/config"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/coplay"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/coverart"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/eventbus"
@@ -25,12 +26,14 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrrequests"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/logging"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/scrobble"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/scrobble/listenbrainz"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/server"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/similarity"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/subsonic"
 	syncpkg "git.fabledsword.com/bvandeusen/minstrel/internal/sync"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/tags"
 )
 
 func main() {
@@ -146,6 +149,16 @@ func run() error {
 	coverEnricher := coverart.NewEnricher(pool, logger.With("component", "coverart"), coverSettings)
 	coverEnricher.DataDir = cfg.Storage.DataDir
 
+	// Recommendation tuning lab (#1250): seeds shipped defaults on first
+	// boot and pushes the daily_mix weights + taste config into package
+	// playlists — must precede the scheduler so the first builds score
+	// with the operator's tuned values, not the pre-push literals.
+	recSettings, err := recsettings.New(ctx, pool, logger.With("component", "recsettings"))
+	if err != nil {
+		logger.Error("recommendation settings service init failed", "err", err)
+		os.Exit(1)
+	}
+
 	// One unified scan chain: library walk → MBID backfill → cover enrich.
 	// Boot-time scan and manual-trigger scans share this path; results land
 	// in scan_runs for the admin overview.
@@ -194,6 +207,31 @@ func run() error {
 	similarityWorker := similarity.NewWorker(pool, listenbrainz.NewClient(), logger.With("component", "similarity"))
 	go similarityWorker.Run(ctx)
 
+	// Start the household co-play worker (#1533). Recomputes artist–artist
+	// co-occurrence edges (source='user_cooccurrence') from play_events every
+	// 6h — a collaborative candidate arm for the radio/mix pools. Pure local
+	// SQL, no external calls; empty on single-user servers.
+	go coplay.NewWorker(pool, logger.With("component", "coplay")).Run(ctx)
+
+	// Start the tag-enrichment worker (#1490). Reconciles the compiled-in
+	// tag providers with tag_provider_settings, bumps the sources version if
+	// the provider set changed (re-opening settled rows), then drains tracks
+	// needing folksonomy tags on a periodic tick. Standalone (not in the file
+	// scan chain) because tag lookups need only DB fields — MBID / artist /
+	// title — that a scan has already imported.
+	tagSettings, err := tags.NewSettingsService(ctx, pool, logger.With("component", "tags"))
+	if err != nil {
+		logger.Error("tag settings service init failed", "err", err)
+		os.Exit(1)
+	}
+	if newVer, bumped, berr := tagSettings.BumpVersionIfProvidersChanged(ctx); berr != nil {
+		logger.Warn("tags: provider-hash boot check failed", "err", berr)
+	} else if bumped {
+		logger.Info("tags: registered provider set changed; version bumped", "new_version", newVer)
+	}
+	tagEnricher := tags.NewEnricher(pool, logger.With("component", "tags"), tagSettings)
+	go tags.NewWorker(tagEnricher, logger.With("component", "tags")).Run(ctx)
+
 	// Start the GC worker. Runs every 1h and sweeps lifecycle tables
 	// that have no writer-side close path or retention policy:
 	// orphan play_events, stale play_sessions, expired
@@ -294,6 +332,8 @@ func run() error {
 	}, cfg.Events, cfg.Recommendation, cfg.Storage.DataDir, cfg.Branding, coverEnricher, coverSettings, scanner, scanCfg)
 	srv.Bus = bus
 	srv.PlaylistScheduler = playlistScheduler
+	srv.RecSettings = recSettings
+	srv.TagSettings = tagSettings
 	srv.StreamSecret = cfg.StreamSecret
 	httpServer := &http.Server{
 		Addr:              cfg.Server.Address,

internal/api/admin_recommendation_trends.go

@@ -0,0 +1,202 @@
+// Admin recommendation-trends endpoint (#1251): weekly per-surface
+// outcome series with tuning-audit markers — the verify half of the
+// tune→verify loop the tuning lab (#1250) opens. Aggregated across
+// all users because the knobs are global; rows carry rates only.
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"sort"
+	"strconv"
+	"time"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+const (
+	trendsDefaultWeeks = 12
+	trendsMaxWeeks     = 52
+	// trendsAuditFetchCap bounds the audit fetch; markers older than
+	// the window are dropped in Go. Far above any real knob-turn count
+	// inside a year.
+	trendsAuditFetchCap = 500
+)
+
+// trendPoint is one week of one surface family's outcomes.
+type trendPoint struct {
+	WeekStart     string  `json:"week_start"` // ISO date (Monday)
+	Plays         int64   `json:"plays"`
+	Skips         int64   `json:"skips"`
+	SkipRate      float64 `json:"skip_rate"`
+	AvgCompletion float64 `json:"avg_completion"`
+	// TasteHitRate is the share of plays whose track's artist carries a
+	// positive weight in the player's current taste profile — a drifted
+	// but retroactive read on whether the surface feeds taste-fitting
+	// tracks.
+	TasteHitRate float64 `json:"taste_hit_rate"`
+	// completionN carries the completion sample count through same-week
+	// merges so avg_completion stays sample-weighted; not serialized.
+	completionN int64
+}
+
+// trendSeries is one surface family's weekly series.
+type trendSeries struct {
+	Key    string       `json:"key"`
+	Label  string       `json:"label"`
+	Intent string       `json:"intent"` // go_to | discovery | direct; "" for the manual baseline
+	Plays  int64        `json:"plays"`  // window total, for sorting/volume-gating
+	Points []trendPoint `json:"points"`
+}
+
+// trendMarker is one tuning-audit event annotated on the timeline.
+type trendMarker struct {
+	ChangedAt string          `json:"changed_at"`
+	Scope     string          `json:"scope"`
+	Action    string          `json:"action"`
+	Changes   json.RawMessage `json:"changes"`
+}
+
+type trendsResp struct {
+	Weeks   int           `json:"weeks"`
+	Series  []trendSeries `json:"series"`
+	Markers []trendMarker `json:"markers"`
+}
+
+// handleGetRecommendationTrends implements
+// GET /api/admin/recommendation-trends?weeks=N (default 12, cap 52).
+func (h *handlers) handleGetRecommendationTrends(w http.ResponseWriter, r *http.Request) {
+	weeks := trendsDefaultWeeks
+	if v := r.URL.Query().Get("weeks"); v != "" {
+		n, err := strconv.Atoi(v)
+		if err != nil || n < 1 {
+			writeErr(w, apierror.BadRequest("bad_request", "invalid weeks"))
+			return
+		}
+		if n > trendsMaxWeeks {
+			n = trendsMaxWeeks
+		}
+		weeks = n
+	}
+
+	q := dbq.New(h.pool)
+	rows, err := q.RecommendationWeeklyTrends(r.Context(), int32(weeks))
+	if err != nil {
+		h.logger.Error("api: recommendation trends", "err", err)
+		writeErr(w, apierror.InternalMsg("lookup failed", err))
+		return
+	}
+	audits, err := q.ListTuningAudit(r.Context(), trendsAuditFetchCap)
+	if err != nil {
+		h.logger.Error("api: recommendation trends audit", "err", err)
+		writeErr(w, apierror.InternalMsg("lookup failed", err))
+		return
+	}
+
+	writeJSON(w, http.StatusOK, buildTrendsResponse(weeks, time.Now().UTC(), rows, audits))
+}
+
+// buildTrendsResponse folds weekly rows into per-family series and
+// windows the audit markers. Split from the handler for pure-unit
+// testability.
+func buildTrendsResponse(
+	weeks int, now time.Time,
+	rows []dbq.RecommendationWeeklyTrendsRow,
+	audits []dbq.RecommendationTuningAudit,
+) trendsResp {
+	type accum struct {
+		fam    recFamily
+		plays  int64
+		points []trendPoint
+	}
+	families := map[string]*accum{}
+	for _, row := range rows {
+		fam := recFamily{key: "manual", label: "Manual library plays"}
+		if row.Source != nil && *row.Source != "" {
+			fam = bucketRecSource(*row.Source)
+		}
+		acc, ok := families[fam.key]
+		if !ok {
+			acc = &accum{fam: fam}
+			families[fam.key] = acc
+		}
+		acc.plays += row.Plays
+		p := trendPoint{
+			WeekStart:     row.WeekStart.Time.Format("2006-01-02"),
+			Plays:         row.Plays,
+			Skips:         row.Skips,
+			AvgCompletion: row.AvgCompletion,
+			completionN:   row.CompletionN,
+		}
+		if row.Plays > 0 {
+			p.SkipRate = float64(row.Skips) / float64(row.Plays)
+			p.TasteHitRate = float64(row.TasteHits) / float64(row.Plays)
+		}
+		// Same family can arrive as several raw sources (radio:<uuid>);
+		// merge same-week points play-weighted.
+		if n := len(acc.points); n > 0 && acc.points[n-1].WeekStart == p.WeekStart {
+			acc.points[n-1] = mergeTrendPoints(acc.points[n-1], p)
+		} else {
+			acc.points = append(acc.points, p)
+		}
+	}
+
+	resp := trendsResp{Weeks: weeks, Series: []trendSeries{}, Markers: []trendMarker{}}
+	for _, acc := range families {
+		resp.Series = append(resp.Series, trendSeries{
+			Key:    acc.fam.key,
+			Label:  acc.fam.label,
+			Intent: acc.fam.intent,
+			Plays:  acc.plays,
+			Points: acc.points,
+		})
+	}
+	sort.Slice(resp.Series, func(i, j int) bool {
+		if resp.Series[i].Plays != resp.Series[j].Plays {
+			return resp.Series[i].Plays > resp.Series[j].Plays
+		}
+		return resp.Series[i].Key < resp.Series[j].Key
+	})
+
+	cutoff := now.Add(-time.Duration(weeks) * 7 * 24 * time.Hour)
+	for _, a := range audits {
+		if a.ChangedAt.Time.Before(cutoff) {
+			continue
+		}
+		resp.Markers = append(resp.Markers, trendMarker{
+			ChangedAt: a.ChangedAt.Time.UTC().Format(time.RFC3339),
+			Scope:     a.Scope,
+			Action:    a.Action,
+			Changes:   json.RawMessage(a.Changes),
+		})
+	}
+	// ListTuningAudit returns newest-first; the timeline reads better
+	// oldest-first.
+	sort.Slice(resp.Markers, func(i, j int) bool {
+		return resp.Markers[i].ChangedAt < resp.Markers[j].ChangedAt
+	})
+	return resp
+}
+
+// mergeTrendPoints combines two same-week points of one family:
+// counts add, skip/taste rates re-derive from the merged counts, and
+// avg_completion is weighted by each side's completion sample count.
+func mergeTrendPoints(a, b trendPoint) trendPoint {
+	out := trendPoint{
+		WeekStart:   a.WeekStart,
+		Plays:       a.Plays + b.Plays,
+		Skips:       a.Skips + b.Skips,
+		completionN: a.completionN + b.completionN,
+	}
+	if out.Plays > 0 {
+		out.SkipRate = float64(out.Skips) / float64(out.Plays)
+		out.TasteHitRate = (a.TasteHitRate*float64(a.Plays) + b.TasteHitRate*float64(b.Plays)) /
+			float64(out.Plays)
+	}
+	if out.completionN > 0 {
+		out.AvgCompletion = (a.AvgCompletion*float64(a.completionN) + b.AvgCompletion*float64(b.completionN)) /
+			float64(out.completionN)
+	}
+	return out
+}

internal/api/admin_recommendation_trends_test.go

@@ -0,0 +1,152 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+func date(s string) pgtype.Date {
+	t, _ := time.Parse("2006-01-02", s)
+	return pgtype.Date{Time: t, Valid: true}
+}
+
+func TestBuildTrendsResponse_SeriesMergingAndMarkers(t *testing.T) {
+	src := func(s string) *string { return &s }
+	now := time.Date(2026, 7, 3, 12, 0, 0, 0, time.UTC)
+	rows := []dbq.RecommendationWeeklyTrendsRow{
+		// Two radio session sources in the same week collapse into one
+		// family point; completion weighting by sample count.
+		{WeekStart: date("2026-06-22"), Source: src("radio:aaaa"),
+			Plays: 3, Skips: 1, CompletionN: 3, AvgCompletion: 0.6, TasteHits: 3},
+		{WeekStart: date("2026-06-22"), Source: src("radio:bbbb"),
+			Plays: 1, Skips: 1, CompletionN: 1, AvgCompletion: 0.2, TasteHits: 0},
+		{WeekStart: date("2026-06-29"), Source: src("radio:aaaa"),
+			Plays: 2, Skips: 0, CompletionN: 2, AvgCompletion: 0.9, TasteHits: 1},
+		// NULL source = manual baseline family.
+		{WeekStart: date("2026-06-29"), Source: nil,
+			Plays: 5, Skips: 1, CompletionN: 5, AvgCompletion: 0.8, TasteHits: 4},
+	}
+	audits := []dbq.RecommendationTuningAudit{
+		{ID: 2, ChangedAt: pgtype.Timestamptz{Time: now.Add(-24 * time.Hour), Valid: true},
+			Scope: "radio", Action: "update", Changes: []byte(`[{"field":"taste_weight","old":1,"new":2}]`)},
+		// Older than the window → dropped.
+		{ID: 1, ChangedAt: pgtype.Timestamptz{Time: now.Add(-100 * 7 * 24 * time.Hour), Valid: true},
+			Scope: "taste", Action: "reset", Changes: []byte(`[]`)},
+	}
+
+	resp := buildTrendsResponse(12, now, rows, audits)
+
+	if len(resp.Series) != 2 {
+		t.Fatalf("series = %d, want 2 (radio + manual)", len(resp.Series))
+	}
+	radio := resp.Series[0] // 6 plays > manual's 5 → sorted first
+	if radio.Key != "radio" || radio.Plays != 6 {
+		t.Fatalf("series[0] = %s/%d, want radio/6", radio.Key, radio.Plays)
+	}
+	if len(radio.Points) != 2 {
+		t.Fatalf("radio points = %d, want 2 weeks", len(radio.Points))
+	}
+	wk1 := radio.Points[0]
+	if wk1.WeekStart != "2026-06-22" || wk1.Plays != 4 || wk1.Skips != 2 {
+		t.Errorf("week1 = %+v, want 2026-06-22 with 4 plays / 2 skips", wk1)
+	}
+	if wk1.SkipRate != 0.5 {
+		t.Errorf("week1 skip_rate = %v, want 0.5", wk1.SkipRate)
+	}
+	// Completion weighted by sample count: (0.6*3 + 0.2*1) / 4 = 0.5.
+	if wk1.AvgCompletion < 0.49 || wk1.AvgCompletion > 0.51 {
+		t.Errorf("week1 avg_completion = %v, want 0.5", wk1.AvgCompletion)
+	}
+	// Taste hits: 3 of 4 plays.
+	if wk1.TasteHitRate != 0.75 {
+		t.Errorf("week1 taste_hit_rate = %v, want 0.75", wk1.TasteHitRate)
+	}
+	if manual := resp.Series[1]; manual.Key != "manual" || manual.Intent != "" {
+		t.Errorf("series[1] = %+v, want the manual baseline family", manual)
+	}
+
+	if len(resp.Markers) != 1 {
+		t.Fatalf("markers = %d, want 1 (out-of-window marker dropped)", len(resp.Markers))
+	}
+	if resp.Markers[0].Scope != "radio" || resp.Markers[0].Action != "update" {
+		t.Errorf("marker = %+v, want radio/update", resp.Markers[0])
+	}
+}
+
+func newTrendsRouter(h *handlers) chi.Router {
+	r := chi.NewRouter()
+	r.Get("/api/admin/recommendation-trends", h.handleGetRecommendationTrends)
+	return r
+}
+
+func TestRecommendationTrends_EndToEnd(t *testing.T) {
+	h, pool := testHandlers(t)
+	user := seedUser(t, pool, "trends", "pw", true)
+	artist := seedArtist(t, pool, "TrendArtist")
+	album := seedAlbum(t, pool, artist.ID, "TrendAlbum", 2020)
+	tk := seedTrack(t, pool, album.ID, artist.ID, "TrendTrack", 1, 200000)
+	session := seedPlaySession(t, pool, user.ID, time.Now())
+
+	// Positive taste weight for the artist → plays count as taste hits.
+	if _, err := pool.Exec(context.Background(),
+		`INSERT INTO taste_profile_artists (user_id, artist_id, weight) VALUES ($1, $2, 1.5)`,
+		user.ID, artist.ID); err != nil {
+		t.Fatalf("seed taste profile: %v", err)
+	}
+	radio := "radio"
+	seedSourcedPlay(t, h, user.ID, tk.ID, session, &radio, nil, 0.9, false)
+	// A knob turn to mark the timeline.
+	if err := h.recSettings.UpdateProfile(context.Background(), "radio",
+		map[string]float64{"taste_weight": 2}); err != nil {
+		t.Fatalf("UpdateProfile: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodGet, "/api/admin/recommendation-trends", nil)
+	rec := httptest.NewRecorder()
+	newTrendsRouter(h).ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (%s)", rec.Code, rec.Body.String())
+	}
+	var resp trendsResp
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if resp.Weeks != trendsDefaultWeeks {
+		t.Errorf("weeks = %d, want %d", resp.Weeks, trendsDefaultWeeks)
+	}
+	var radioSeries *trendSeries
+	for i := range resp.Series {
+		if resp.Series[i].Key == "radio" {
+			radioSeries = &resp.Series[i]
+		}
+	}
+	if radioSeries == nil || len(radioSeries.Points) != 1 {
+		t.Fatalf("radio series = %+v, want one point", radioSeries)
+	}
+	if radioSeries.Points[0].TasteHitRate != 1.0 {
+		t.Errorf("taste_hit_rate = %v, want 1.0 (positive-weight artist)",
+			radioSeries.Points[0].TasteHitRate)
+	}
+	if len(resp.Markers) != 1 || resp.Markers[0].Scope != "radio" {
+		t.Errorf("markers = %+v, want the radio knob turn", resp.Markers)
+	}
+}
+
+func TestRecommendationTrends_InvalidWeeks(t *testing.T) {
+	h, _ := testHandlers(t)
+	req := httptest.NewRequest(http.MethodGet, "/api/admin/recommendation-trends?weeks=zero", nil)
+	rec := httptest.NewRecorder()
+	newTrendsRouter(h).ServeHTTP(rec, req)
+	if rec.Code != http.StatusBadRequest {
+		t.Errorf("status = %d, want 400", rec.Code)
+	}
+}

internal/api/admin_recommendation_tuning.go

@@ -0,0 +1,160 @@
+// Admin recommendation-tuning endpoints (#1250): the defaults-
+// discovery lab. GET returns current values + shipped defaults for
+// every scope; PATCH applies a partial update to one scope; reset
+// restores a scope to shipped defaults. Every change writes an audit
+// row (consumed by the metrics trend view, #1251).
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recommendation"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
+)
+
+// weightsResp is one weight profile on the wire, keyed by the same
+// snake_case field names the PATCH body accepts.
+type weightsResp struct {
+	BaseWeight        float64 `json:"base_weight"`
+	LikeBoost         float64 `json:"like_boost"`
+	RecencyWeight     float64 `json:"recency_weight"`
+	SkipPenalty       float64 `json:"skip_penalty"`
+	JitterMagnitude   float64 `json:"jitter_magnitude"`
+	ContextWeight     float64 `json:"context_weight"`
+	SimilarityWeight  float64 `json:"similarity_weight"`
+	TasteWeight       float64 `json:"taste_weight"`
+	ContextTimeWeight float64 `json:"context_time_weight"`
+}
+
+func weightsRespFrom(w recommendation.ScoringWeights) weightsResp {
+	return weightsResp{
+		BaseWeight:        w.BaseWeight,
+		LikeBoost:         w.LikeBoost,
+		RecencyWeight:     w.RecencyWeight,
+		SkipPenalty:       w.SkipPenalty,
+		JitterMagnitude:   w.JitterMagnitude,
+		ContextWeight:     w.ContextWeight,
+		SimilarityWeight:  w.SimilarityWeight,
+		TasteWeight:       w.TasteWeight,
+		ContextTimeWeight: w.ContextTimeWeight,
+	}
+}
+
+type tasteTuningResp struct {
+	HalfLifeDays       float64 `json:"half_life_days"`
+	EngagementHardSkip float64 `json:"engagement_hard_skip"`
+	EngagementNeutral  float64 `json:"engagement_neutral"`
+	EngagementFull     float64 `json:"engagement_full"`
+	EnrichedTagScale   float64 `json:"enriched_tag_scale"`
+	EraScale           float64 `json:"era_scale"`
+	MoodScale          float64 `json:"mood_scale"`
+}
+
+func tasteRespFrom(t recsettings.TasteTuning) tasteTuningResp {
+	return tasteTuningResp{
+		HalfLifeDays:       t.HalfLifeDays,
+		EngagementHardSkip: t.EngagementHardSkip,
+		EngagementNeutral:  t.EngagementNeutral,
+		EngagementFull:     t.EngagementFull,
+		EnrichedTagScale:   t.EnrichedTagScale,
+		EraScale:           t.EraScale,
+		MoodScale:          t.MoodScale,
+	}
+}
+
+// tuningSnapshot is both the GET response and the post-mutation echo:
+// current values alongside shipped defaults so the card can mark
+// which knobs deviate.
+type tuningSnapshot struct {
+	Profiles map[string]weightsResp `json:"profiles"`
+	Taste    tasteTuningResp        `json:"taste"`
+	Shipped  struct {
+		Profiles map[string]weightsResp `json:"profiles"`
+		Taste    tasteTuningResp        `json:"taste"`
+	} `json:"shipped"`
+}
+
+func (h *handlers) tuningSnapshot() tuningSnapshot {
+	var out tuningSnapshot
+	out.Profiles = map[string]weightsResp{
+		recsettings.ScopeRadio:    weightsRespFrom(h.recSettings.Weights(recsettings.ScopeRadio)),
+		recsettings.ScopeDailyMix: weightsRespFrom(h.recSettings.Weights(recsettings.ScopeDailyMix)),
+	}
+	out.Taste = tasteRespFrom(h.recSettings.Taste())
+	out.Shipped.Profiles = map[string]weightsResp{
+		recsettings.ScopeRadio:    weightsRespFrom(recsettings.ShippedRadioWeights()),
+		recsettings.ScopeDailyMix: weightsRespFrom(recsettings.ShippedDailyMixWeights()),
+	}
+	out.Shipped.Taste = tasteRespFrom(recsettings.ShippedTasteTuning())
+	return out
+}
+
+// handleGetRecommendationTuning implements GET /api/admin/recommendation-tuning.
+func (h *handlers) handleGetRecommendationTuning(w http.ResponseWriter, _ *http.Request) {
+	writeJSON(w, http.StatusOK, h.tuningSnapshot())
+}
+
+// patchTuningReq carries the partial update: field name → new value,
+// using the same snake_case names the GET response emits.
+type patchTuningReq struct {
+	Values map[string]float64 `json:"values"`
+}
+
+// handlePatchRecommendationTuning implements
+// PATCH /api/admin/recommendation-tuning/{scope}.
+func (h *handlers) handlePatchRecommendationTuning(w http.ResponseWriter, r *http.Request) {
+	scope := chi.URLParam(r, "scope")
+	var body patchTuningReq
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeErr(w, apierror.BadRequest("bad_body", "invalid JSON"))
+		return
+	}
+	if len(body.Values) == 0 {
+		writeErr(w, apierror.BadRequest("bad_body", "values is empty"))
+		return
+	}
+
+	var err error
+	if scope == recsettings.ScopeTaste {
+		err = h.recSettings.UpdateTaste(r.Context(), body.Values)
+	} else {
+		err = h.recSettings.UpdateProfile(r.Context(), scope, body.Values)
+	}
+	if err != nil {
+		writeTuningErr(w, h, scope, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, h.tuningSnapshot())
+}
+
+// handleResetRecommendationTuning implements
+// POST /api/admin/recommendation-tuning/{scope}/reset.
+func (h *handlers) handleResetRecommendationTuning(w http.ResponseWriter, r *http.Request) {
+	scope := chi.URLParam(r, "scope")
+	if err := h.recSettings.Reset(r.Context(), scope); err != nil {
+		writeTuningErr(w, h, scope, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, h.tuningSnapshot())
+}
+
+// writeTuningErr maps recsettings validation errors to 400s and
+// everything else to a logged 500.
+func writeTuningErr(w http.ResponseWriter, h *handlers, scope string, err error) {
+	switch {
+	case errors.Is(err, recsettings.ErrUnknownScope):
+		writeErr(w, &apierror.Error{
+			Status: http.StatusNotFound, Code: "not_found", Message: "no such tuning scope",
+		})
+	case errors.Is(err, recsettings.ErrUnknownField), errors.Is(err, recsettings.ErrOutOfRange):
+		writeErr(w, apierror.BadRequest("invalid_tuning", err.Error()))
+	default:
+		h.logger.Error("admin: recommendation tuning", "scope", scope, "err", err)
+		writeErr(w, apierror.InternalMsg("tuning update failed", err))
+	}
+}

internal/api/admin_recommendation_tuning_test.go

@@ -0,0 +1,110 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
+)
+
+func newTuningRouter(h *handlers) chi.Router {
+	r := chi.NewRouter()
+	r.Get("/api/admin/recommendation-tuning", h.handleGetRecommendationTuning)
+	r.Patch("/api/admin/recommendation-tuning/{scope}", h.handlePatchRecommendationTuning)
+	r.Post("/api/admin/recommendation-tuning/{scope}/reset", h.handleResetRecommendationTuning)
+	return r
+}
+
+func decodeTuning(t *testing.T, rec *httptest.ResponseRecorder) tuningSnapshot {
+	t.Helper()
+	var snap tuningSnapshot
+	if err := json.Unmarshal(rec.Body.Bytes(), &snap); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	return snap
+}
+
+func TestRecommendationTuning_GetReturnsShippedDefaults(t *testing.T) {
+	h, _ := testHandlers(t)
+	req := httptest.NewRequest(http.MethodGet, "/api/admin/recommendation-tuning", nil)
+	rec := httptest.NewRecorder()
+	newTuningRouter(h).ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", rec.Code)
+	}
+	snap := decodeTuning(t, rec)
+	if snap.Profiles["radio"].TasteWeight != 1.0 || snap.Profiles["daily_mix"].TasteWeight != 1.5 {
+		t.Errorf("profiles = %+v, want shipped taste weights 1.0 / 1.5", snap.Profiles)
+	}
+	if snap.Taste.HalfLifeDays != 75 {
+		t.Errorf("taste half-life = %v, want shipped 75", snap.Taste.HalfLifeDays)
+	}
+	if snap.Shipped.Profiles["radio"] != snap.Profiles["radio"] {
+		t.Error("untouched values must equal shipped defaults")
+	}
+}
+
+func TestRecommendationTuning_PatchAndReset(t *testing.T) {
+	h, _ := testHandlers(t)
+	r := newTuningRouter(h)
+
+	req := httptest.NewRequest(http.MethodPatch, "/api/admin/recommendation-tuning/radio",
+		strings.NewReader(`{"values":{"taste_weight": 2.5}}`))
+	rec := httptest.NewRecorder()
+	r.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("patch status = %d, want 200 (%s)", rec.Code, rec.Body.String())
+	}
+	snap := decodeTuning(t, rec)
+	if snap.Profiles["radio"].TasteWeight != 2.5 {
+		t.Errorf("patched taste_weight = %v, want 2.5", snap.Profiles["radio"].TasteWeight)
+	}
+	// The change is live for the radio scoring path.
+	if got := h.recSettings.Weights(recsettings.ScopeRadio).TasteWeight; got != 2.5 {
+		t.Errorf("service taste_weight = %v, want 2.5 (live effect)", got)
+	}
+
+	req = httptest.NewRequest(http.MethodPost, "/api/admin/recommendation-tuning/radio/reset", nil)
+	rec = httptest.NewRecorder()
+	r.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("reset status = %d, want 200", rec.Code)
+	}
+	snap = decodeTuning(t, rec)
+	if snap.Profiles["radio"].TasteWeight != 1.0 {
+		t.Errorf("reset taste_weight = %v, want shipped 1.0", snap.Profiles["radio"].TasteWeight)
+	}
+}
+
+func TestRecommendationTuning_PatchErrors(t *testing.T) {
+	h, _ := testHandlers(t)
+	r := newTuningRouter(h)
+	cases := []struct {
+		name, path, body string
+		want             int
+	}{
+		{"unknown scope", "/api/admin/recommendation-tuning/banana",
+			`{"values":{"taste_weight":1}}`, http.StatusNotFound},
+		{"unknown field", "/api/admin/recommendation-tuning/radio",
+			`{"values":{"vibes":1}}`, http.StatusBadRequest},
+		{"out of range", "/api/admin/recommendation-tuning/taste",
+			`{"values":{"engagement_neutral":2}}`, http.StatusBadRequest},
+		{"empty values", "/api/admin/recommendation-tuning/radio",
+			`{"values":{}}`, http.StatusBadRequest},
+		{"bad json", "/api/admin/recommendation-tuning/radio",
+			`{`, http.StatusBadRequest},
+	}
+	for _, c := range cases {
+		req := httptest.NewRequest(http.MethodPatch, c.path, strings.NewReader(c.body))
+		rec := httptest.NewRecorder()
+		r.ServeHTTP(rec, req)
+		if rec.Code != c.want {
+			t.Errorf("%s: status = %d, want %d", c.name, rec.Code, c.want)
+		}
+	}
+}

internal/api/admin_tag_sources.go

@@ -0,0 +1,153 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/tags"
+)
+
+// tagSourceResp is the wire shape for one tag-enrichment provider in the
+// GET /api/admin/tag-sources list. Mirrors the cover-sources admin surface
+// (admin_cover_sources.go) — a separate, independent settings card so a new
+// tag source is added without touching art settings (#1490).
+type tagSourceResp struct {
+	ID             string   `json:"id"`
+	DisplayName    string   `json:"display_name"`
+	RequiresAPIKey bool     `json:"requires_api_key"`
+	Supports       []string `json:"supports"`
+	Enabled        bool     `json:"enabled"`
+	APIKeySet      bool     `json:"api_key_set"`
+	DisplayOrder   int32    `json:"display_order"`
+	Testable       bool     `json:"testable"`
+}
+
+func tagSourceRespFrom(info tags.ProviderInfo) tagSourceResp {
+	supports := info.Supports
+	if supports == nil {
+		supports = []string{}
+	}
+	return tagSourceResp{
+		ID:             info.ID,
+		DisplayName:    info.DisplayName,
+		RequiresAPIKey: info.RequiresAPIKey,
+		Supports:       supports,
+		Enabled:        info.Enabled,
+		APIKeySet:      info.APIKeySet,
+		DisplayOrder:   info.DisplayOrder,
+		Testable:       info.Testable,
+	}
+}
+
+type tagSourcesListResp struct {
+	Providers      []tagSourceResp `json:"providers"`
+	SourcesVersion int32           `json:"sources_version"`
+}
+
+// handleListTagSources implements GET /api/admin/tag-sources.
+func (h *handlers) handleListTagSources(w http.ResponseWriter, _ *http.Request) {
+	infos := h.tagSettings.ListProviderInfo()
+	out := tagSourcesListResp{
+		Providers:      make([]tagSourceResp, 0, len(infos)),
+		SourcesVersion: h.tagSettings.CurrentVersion(),
+	}
+	for _, info := range infos {
+		out.Providers = append(out.Providers, tagSourceRespFrom(info))
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+// updateTagSourceReq is the PATCH body. nil pointers mean "leave
+// unchanged"; non-nil sets (empty api_key clears).
+type updateTagSourceReq struct {
+	Enabled *bool   `json:"enabled,omitempty"`
+	APIKey  *string `json:"api_key,omitempty"`
+}
+
+type updateTagSourceResp struct {
+	tagSourceResp
+	VersionBumped bool `json:"version_bumped"`
+}
+
+// handleUpdateTagSource implements PATCH /api/admin/tag-sources/{provider_id}.
+func (h *handlers) handleUpdateTagSource(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "provider_id")
+
+	var body updateTagSourceReq
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		writeErr(w, apierror.BadRequest("bad_body", "invalid JSON"))
+		return
+	}
+
+	bumped, err := h.tagSettings.UpdateProvider(r.Context(), id, tags.ProviderUpdatePatch{
+		Enabled: body.Enabled,
+		APIKey:  body.APIKey,
+	})
+	if err != nil {
+		if errors.Is(err, tags.ErrProviderNotFound) {
+			writeErr(w, &apierror.Error{Status: http.StatusNotFound, Code: "not_found", Message: "no such provider"})
+			return
+		}
+		h.logger.Error("admin: update tag source", "id", id, "err", err)
+		writeErr(w, apierror.InternalMsg("update failed", err))
+		return
+	}
+
+	var found tagSourceResp
+	for _, info := range h.tagSettings.ListProviderInfo() {
+		if info.ID == id {
+			found = tagSourceRespFrom(info)
+			break
+		}
+	}
+	writeJSON(w, http.StatusOK, updateTagSourceResp{tagSourceResp: found, VersionBumped: bumped})
+}
+
+type testTagSourceResp struct {
+	OK         bool   `json:"ok"`
+	DurationMs int64  `json:"duration_ms,omitempty"`
+	Error      string `json:"error,omitempty"`
+}
+
+// handleTestTagSource implements POST /api/admin/tag-sources/{provider_id}/test.
+func (h *handlers) handleTestTagSource(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "provider_id")
+
+	start := time.Now()
+	err := h.tagSettings.TestProvider(r.Context(), id)
+	duration := time.Since(start).Milliseconds()
+
+	if err == nil {
+		writeJSON(w, http.StatusOK, testTagSourceResp{OK: true, DurationMs: duration})
+		return
+	}
+	if errors.Is(err, tags.ErrProviderNotFound) {
+		writeErr(w, &apierror.Error{Status: http.StatusNotFound, Code: "not_found", Message: "no such provider"})
+		return
+	}
+	// Not testable, or the test failed — both surface as ok=false with a
+	// 200 (the operation completed; the result is data, not an error).
+	writeJSON(w, http.StatusOK, testTagSourceResp{OK: false, DurationMs: duration, Error: err.Error()})
+}
+
+type researchTagsResp struct {
+	SourcesVersion int32 `json:"sources_version"`
+}
+
+// handleResearchTags implements POST /api/admin/tag-sources/research: bump
+// the sources version so every settled ('none') track becomes eligible for
+// a re-enrichment pass, then the background worker re-processes them.
+func (h *handlers) handleResearchTags(w http.ResponseWriter, r *http.Request) {
+	newVer, err := h.tagSettings.BumpVersion(r.Context())
+	if err != nil {
+		h.logger.Error("admin: research tags", "err", err)
+		writeErr(w, apierror.InternalMsg("research failed", err))
+		return
+	}
+	writeJSON(w, http.StatusOK, researchTagsResp{SourcesVersion: newVer})
+}

internal/api/admin_tag_sources_test.go

@@ -0,0 +1,243 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/auth"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/tags"
+)
+
+// apiTestTagProvider is a minimal TrackTagProvider for api-package tests.
+// Does not implement TestableProvider.
+type apiTestTagProvider struct {
+	id      string
+	display string
+}
+
+func (p *apiTestTagProvider) ID() string                              { return p.id }
+func (p *apiTestTagProvider) DisplayName() string                     { return p.display }
+func (p *apiTestTagProvider) RequiresAPIKey() bool                    { return false }
+func (p *apiTestTagProvider) DefaultEnabled() bool                    { return true }
+func (p *apiTestTagProvider) Configure(_ tags.ProviderSettings) error { return nil }
+func (p *apiTestTagProvider) FetchTrackTags(_ context.Context, _ tags.TrackRef) ([]tags.Tag, error) {
+	return []tags.Tag{{Name: "x", Weight: 1}}, nil
+}
+
+// apiTestTestableTagProvider also implements TestableProvider.
+type apiTestTestableTagProvider struct {
+	apiTestTagProvider
+}
+
+func (p *apiTestTestableTagProvider) TestConnection(_ context.Context) error { return nil }
+
+func newAdminTagSourcesRouter(h *handlers) chi.Router {
+	r := chi.NewRouter()
+	r.Route("/api/admin", func(admin chi.Router) {
+		admin.Use(auth.RequireAdmin())
+		admin.Get("/tag-sources", h.handleListTagSources)
+		admin.Patch("/tag-sources/{provider_id}", h.handleUpdateTagSource)
+		admin.Post("/tag-sources/{provider_id}/test", h.handleTestTagSource)
+	})
+	return r
+}
+
+// testHandlersWithTagSettings installs a tags.SettingsService backed by the
+// test DB. Register the needed fake providers BEFORE calling this, and pair
+// with tags.ResetRegistryForTests in t.Cleanup.
+func testHandlersWithTagSettings(t *testing.T) *handlers {
+	t.Helper()
+	h, pool := testHandlers(t)
+	s, err := tags.NewSettingsService(context.Background(), pool, h.logger)
+	if err != nil {
+		t.Fatalf("NewSettingsService: %v", err)
+	}
+	h.tagSettings = s
+	return h
+}
+
+func TestAdminListTagSources_ReturnsRegisteredProviders(t *testing.T) {
+	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
+		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
+	}
+	tags.ResetRegistryForTests()
+	t.Cleanup(tags.ResetRegistryForTests)
+	tags.Register(&apiTestTagProvider{id: "test-tag-prov", display: "Test Tag Provider"})
+
+	h := testHandlersWithTagSettings(t)
+	admin := seedUser(t, h.pool, "tslist", "pw", true)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/admin/tag-sources", nil)
+	req = withUser(req, admin)
+	rec := httptest.NewRecorder()
+	newAdminTagSourcesRouter(h).ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
+	}
+	var resp tagSourcesListResp
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if len(resp.Providers) != 1 || resp.Providers[0].ID != "test-tag-prov" {
+		t.Fatalf("providers = %+v, want 1 (test-tag-prov)", resp.Providers)
+	}
+	found := false
+	for _, s := range resp.Providers[0].Supports {
+		if s == "track_tags" {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("supports = %v, want to include track_tags", resp.Providers[0].Supports)
+	}
+	if resp.Providers[0].Testable {
+		t.Error("testable = true, want false (no TestConnection)")
+	}
+}
+
+func TestAdminUpdateTagSource_FlippingEnabledBumpsVersion(t *testing.T) {
+	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
+		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
+	}
+	tags.ResetRegistryForTests()
+	t.Cleanup(tags.ResetRegistryForTests)
+	tags.Register(&apiTestTagProvider{id: "flip-tag", display: "Flip Tag"})
+
+	h := testHandlersWithTagSettings(t)
+	admin := seedUser(t, h.pool, "tsflip", "pw", true)
+
+	disabled := false
+	body, _ := json.Marshal(updateTagSourceReq{Enabled: &disabled})
+	req := httptest.NewRequest(http.MethodPatch, "/api/admin/tag-sources/flip-tag", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req = withUser(req, admin)
+	rec := httptest.NewRecorder()
+	newAdminTagSourcesRouter(h).ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
+	}
+	var resp updateTagSourceResp
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if !resp.VersionBumped {
+		t.Error("version_bumped = false, want true after flipping enabled")
+	}
+}
+
+func TestAdminUpdateTagSource_KeyOnlyDoesNotBump(t *testing.T) {
+	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
+		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
+	}
+	tags.ResetRegistryForTests()
+	t.Cleanup(tags.ResetRegistryForTests)
+	tags.Register(&apiTestTagProvider{id: "key-tag", display: "Key Tag"})
+
+	h := testHandlersWithTagSettings(t)
+	admin := seedUser(t, h.pool, "tskey", "pw", true)
+
+	newKey := "newkey"
+	body, _ := json.Marshal(updateTagSourceReq{APIKey: &newKey})
+	req := httptest.NewRequest(http.MethodPatch, "/api/admin/tag-sources/key-tag", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req = withUser(req, admin)
+	rec := httptest.NewRecorder()
+	newAdminTagSourcesRouter(h).ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
+	}
+	var resp updateTagSourceResp
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if resp.VersionBumped {
+		t.Error("version_bumped = true, want false for key-only change")
+	}
+	if !resp.APIKeySet {
+		t.Error("api_key_set = false, want true after setting key")
+	}
+}
+
+func TestAdminUpdateTagSource_UnknownProvider404(t *testing.T) {
+	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
+		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
+	}
+	tags.ResetRegistryForTests()
+	t.Cleanup(tags.ResetRegistryForTests)
+
+	h := testHandlersWithTagSettings(t)
+	admin := seedUser(t, h.pool, "ts404", "pw", true)
+
+	body, _ := json.Marshal(updateTagSourceReq{})
+	req := httptest.NewRequest(http.MethodPatch, "/api/admin/tag-sources/missing", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	req = withUser(req, admin)
+	rec := httptest.NewRecorder()
+	newAdminTagSourcesRouter(h).ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want 404; body=%s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestAdminTestTagSource_NonAdminReturns403(t *testing.T) {
+	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
+		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
+	}
+	tags.ResetRegistryForTests()
+	t.Cleanup(tags.ResetRegistryForTests)
+	tags.Register(&apiTestTestableTagProvider{apiTestTagProvider{id: "testable-tag", display: "Testable Tag"}})
+
+	h := testHandlersWithTagSettings(t)
+	nonAdmin := seedUser(t, h.pool, "tsnoadmin", "pw", false)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/admin/tag-sources/testable-tag/test", nil)
+	req = withUser(req, nonAdmin)
+	rec := httptest.NewRecorder()
+	newAdminTagSourcesRouter(h).ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403; body=%s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestAdminTestTagSource_NotTestableReturnsOkFalse(t *testing.T) {
+	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
+		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
+	}
+	tags.ResetRegistryForTests()
+	t.Cleanup(tags.ResetRegistryForTests)
+	tags.Register(&apiTestTagProvider{id: "nontestable-tag", display: "Non-Testable Tag"})
+
+	h := testHandlersWithTagSettings(t)
+	admin := seedUser(t, h.pool, "tsntest", "pw", true)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/admin/tag-sources/nontestable-tag/test", nil)
+	req = withUser(req, admin)
+	rec := httptest.NewRecorder()
+	newAdminTagSourcesRouter(h).ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
+	}
+	var resp testTagSourceResp
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	if resp.OK {
+		t.Error("ok = true, want false for non-testable provider")
+	}
+	if resp.Error == "" {
+		t.Error("error string empty, want a message")
+	}
+}

internal/api/admin_users.go

@@ -22,6 +22,7 @@ type adminUserView struct {
 	DisplayName         *string `json:"display_name"`
 	IsAdmin             bool    `json:"is_admin"`
 	AutoApproveRequests bool    `json:"auto_approve_requests"`
+	DebugModeEnabled    bool    `json:"debug_mode_enabled"`
 	CreatedAt           string  `json:"created_at"`
 }
 
@@ -44,6 +45,7 @@ func (h *handlers) handleAdminListUsers(w http.ResponseWriter, r *http.Request)
 			DisplayName:         row.DisplayName,
 			IsAdmin:             row.IsAdmin,
 			AutoApproveRequests: row.AutoApproveRequests,
+			DebugModeEnabled:    row.DebugModeEnabled,
 			CreatedAt:           row.CreatedAt.Time.UTC().Format(time.RFC3339),
 		}
 		out = append(out, v)
@@ -120,6 +122,7 @@ func (h *handlers) handleUpdateUserAdmin(w http.ResponseWriter, r *http.Request)
 		DisplayName:         updated.DisplayName,
 		IsAdmin:             updated.IsAdmin,
 		AutoApproveRequests: updated.AutoApproveRequests,
+		DebugModeEnabled:    updated.DebugModeEnabled,
 		CreatedAt:           updated.CreatedAt.Time.UTC().Format(time.RFC3339),
 	})
 }
@@ -189,6 +192,7 @@ func (h *handlers) handleAdminCreateUser(w http.ResponseWriter, r *http.Request)
 		DisplayName:         user.DisplayName,
 		IsAdmin:             user.IsAdmin,
 		AutoApproveRequests: user.AutoApproveRequests,
+		DebugModeEnabled:    user.DebugModeEnabled,
 		CreatedAt:           user.CreatedAt.Time.UTC().Format(time.RFC3339),
 	})
 }
@@ -329,6 +333,7 @@ func (h *handlers) handleAdminAutoApproveToggle(w http.ResponseWriter, r *http.R
 		DisplayName:         updated.DisplayName,
 		IsAdmin:             updated.IsAdmin,
 		AutoApproveRequests: updated.AutoApproveRequests,
+		DebugModeEnabled:    updated.DebugModeEnabled,
 		CreatedAt:           updated.CreatedAt.Time.UTC().Format(time.RFC3339),
 	})
 }

internal/api/api.go

@@ -22,16 +22,19 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/mailer"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playevents"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/tags"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/tracks"
 )
 
 // 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, 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, recSettings *recsettings.Service, lidarrCfg *lidarrconfig.Service, lidarrReqs *lidarrrequests.Service, lidarrQuar *lidarrquarantine.Service, tracksSvc *tracks.Service, playlistsSvc *playlists.Service, coverEnricher *coverart.Enricher, coverSettings *coverart.SettingsService, tagSettings *tags.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,
+		recSettings:       recSettings,
 		rng:               rng.Float64,
 		lidarrCfg:         lidarrCfg,
 		lidarrRequests:    lidarrReqs,
@@ -40,6 +43,7 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 		playlists:         playlistsSvc,
 		coverart:          coverEnricher,
 		coverSettings:     coverSettings,
+		tagSettings:       tagSettings,
 		scanner:           scanner,
 		scanCfg:           scanCfg,
 		dataDir:           dataDir,
@@ -135,6 +139,12 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 			// load failures). Admin-only inbox; any user can report.
 			authed.Post("/playback-errors", h.handleReportPlaybackError)
 
+			// Device diagnostics ingest (M9). Any signed-in user can
+			// POST a batch, but events are only stored when the
+			// account's debug_mode_enabled flag is on (handler no-ops
+			// otherwise). Admin views live under /admin/diagnostics.
+			authed.Post("/diagnostics", h.handleReportDiagnostics)
+
 			// Self-hosted in-app update channel (#397). Auth-gated to
 			// prevent anonymous bandwidth abuse on the APK stream;
 			// /apk additionally per-user rate-limited.
@@ -181,15 +191,33 @@ func Mount(r chi.Router, pool *pgxpool.Pool, logger *slog.Logger, events *playev
 				admin.Delete("/users/{id}", h.handleAdminDeleteUser)
 				admin.Post("/users/{id}/reset-password", h.handleAdminResetPassword)
 				admin.Put("/users/{id}/auto-approve", h.handleAdminAutoApproveToggle)
+				admin.Put("/users/{id}/debug-mode", h.handleAdminDebugModeToggle)
+
+				// Device diagnostics timeline + device overview (M9).
+				admin.Get("/diagnostics", h.handleListAdminDiagnostics)
+				admin.Get("/diagnostics/devices", h.handleListAdminDiagnosticDevices)
 
 				admin.Get("/cover-sources", h.handleListCoverSources)
 				admin.Patch("/cover-sources/{provider_id}", h.handleUpdateCoverSource)
 				admin.Post("/cover-sources/{provider_id}/test", h.handleTestCoverSource)
 				admin.Post("/cover-sources/research", h.handleResearchMissingArt)
 
+				admin.Get("/tag-sources", h.handleListTagSources)
+				admin.Patch("/tag-sources/{provider_id}", h.handleUpdateTagSource)
+				admin.Post("/tag-sources/{provider_id}/test", h.handleTestTagSource)
+				admin.Post("/tag-sources/research", h.handleResearchTags)
+
 				admin.Get("/smtp-config", h.handleGetSMTPConfig)
 				admin.Put("/smtp-config", h.handleUpdateSMTPConfig)
 				admin.Post("/smtp-config/test", h.handleTestSMTPConfig)
+
+				// Recommendation tuning lab (#1250): scoring-weight
+				// profiles + taste-build knobs, DB-backed, live effect.
+				admin.Get("/recommendation-tuning", h.handleGetRecommendationTuning)
+				admin.Patch("/recommendation-tuning/{scope}", h.handlePatchRecommendationTuning)
+				admin.Post("/recommendation-tuning/{scope}/reset", h.handleResetRecommendationTuning)
+				// Weekly outcome trends + knob-turn markers (#1251).
+				admin.Get("/recommendation-trends", h.handleGetRecommendationTrends)
 			})
 
 			authed.Get("/playlists", h.handleListPlaylists)
@@ -212,6 +240,7 @@ type handlers struct {
 	logger            *slog.Logger
 	events            *playevents.Writer
 	recCfg            config.RecommendationConfig
+	recSettings       *recsettings.Service
 	rng               func() float64
 	lidarrCfg         *lidarrconfig.Service
 	lidarrRequests    *lidarrrequests.Service
@@ -220,6 +249,7 @@ type handlers struct {
 	playlists         *playlists.Service
 	coverart          *coverart.Enricher
 	coverSettings     *coverart.SettingsService
+	tagSettings       *tags.SettingsService
 	scanner           *library.Scanner
 	scanCfg           library.RunScanConfig
 	dataDir           string

internal/api/auth_test.go

@@ -29,6 +29,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/mailer"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playevents"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/playlists"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/tracks"
 )
 
@@ -56,11 +57,12 @@ func testHandlers(t *testing.T) (*handlers, *pgxpool.Pool) {
 	dbtest.ResetDB(t, pool)
 	w := playevents.NewWriter(pool, logger, 30*time.Minute, 0.5, 30000)
 	recCfg := config.RecommendationConfig{
-		BaseWeight: 1.0, LikeBoost: 2.0, RecencyWeight: 1.0,
-		SkipPenalty: 1.0, JitterMagnitude: 0.1,
-		ContextWeight: 2.0, SimilarityWeight: 2.0,
 		RecentlyPlayedHours: 1, RadioSize: 50, RadioSizeMax: 200,
 	}
+	recSettings, err := recsettings.New(context.Background(), pool, logger)
+	if err != nil {
+		t.Fatalf("recsettings: %v", err)
+	}
 	lidarrCfg := lidarrconfig.New(pool)
 	lidarrReqs := lidarrrequests.NewService(pool, lidarrCfg, nil, nil)
 	lidarrQuar := lidarrquarantine.NewService(pool, lidarrCfg, nil)
@@ -70,7 +72,7 @@ func testHandlers(t *testing.T) (*handlers, *pgxpool.Pool) {
 	dataDir := t.TempDir()
 	tracksSvc := tracks.NewService(pool, logger, nil, dataDir)
 	playlistsSvc := playlists.NewService(pool, logger, dataDir)
-	h := &handlers{pool: pool, logger: logger, events: w, recCfg: recCfg, rng: func() float64 { return 0.5 }, lidarrCfg: lidarrCfg, lidarrRequests: lidarrReqs, lidarrQuarantine: lidarrQuar, tracks: tracksSvc, playlists: playlistsSvc, dataDir: dataDir, scanner: nil, scanCfg: library.RunScanConfig{}, mailer: &mailer.FakeSender{}}
+	h := &handlers{pool: pool, logger: logger, events: w, recCfg: recCfg, recSettings: recSettings, rng: func() float64 { return 0.5 }, lidarrCfg: lidarrCfg, lidarrRequests: lidarrReqs, lidarrQuarantine: lidarrQuar, tracks: tracksSvc, playlists: playlistsSvc, dataDir: dataDir, scanner: nil, scanCfg: library.RunScanConfig{}, mailer: &mailer.FakeSender{}}
 	return h, pool
 }
 

internal/api/diagnostics.go

@@ -0,0 +1,346 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// validDiagnosticKinds is the COARSE category whitelist. Mirrors the
+// CHECK constraint in migration 0036 — keep both in sync (per the
+// enum-CHECK-whitelist rule). The finer event discriminator + all
+// event-specific fields live inside each event's payload, so new event
+// variants do NOT require a new category here.
+var validDiagnosticKinds = map[string]struct{}{
+	"connectivity": {},
+	"upnp_sync":    {}, // genuinely UPnP/Sonos-specific (drops, resync)
+	"playback":     {}, // route + player-state, any output (phone/BT/UPnP)
+	"power":        {},
+	"lifecycle":    {},
+	"heartbeat":    {},
+	"http":         {},
+}
+
+// maxDiagnosticBatch caps a single ingest call. The client buffers and
+// flushes in batches of ~100; 500 leaves generous headroom while
+// bounding a misbehaving client's per-request work.
+const maxDiagnosticBatch = 500
+
+// Diagnostics list paging. Larger than the generic parsePaging caps
+// because the admin timeline is meant to be exported as a slice and
+// handed off for analysis — a heartbeat-dense window has many rows.
+const (
+	defaultDiagnosticPageSize = 500
+	maxDiagnosticPageSize     = 5000
+)
+
+// diagnosticEventIn is one event in a POST /api/diagnostics batch.
+// OccurredAt is the client device clock as epoch milliseconds (may be
+// skewed — the server also stamps received_at). Payload is opaque JSON
+// carrying the event's sub-type + fields.
+type diagnosticEventIn struct {
+	Kind       string          `json:"kind"`
+	OccurredAt int64           `json:"occurred_at"`
+	Payload    json.RawMessage `json:"payload"`
+}
+
+// reportDiagnosticsRequest is the body of POST /api/diagnostics — one
+// batch from one device.
+type reportDiagnosticsRequest struct {
+	ClientID   string              `json:"client_id"`
+	AppVersion *string             `json:"app_version,omitempty"`
+	OsVersion  *string             `json:"os_version,omitempty"`
+	Events     []diagnosticEventIn `json:"events"`
+}
+
+// handleReportDiagnostics implements POST /api/diagnostics. Any signed-in
+// user can call it, but events are only stored when the account's
+// debug_mode_enabled flag is on; otherwise the call is a 204 no-op so the
+// client can safely drop the batch (it gates locally on /api/me, this is
+// the race-safe backstop for "admin just disabled debug").
+func (h *handlers) handleReportDiagnostics(w http.ResponseWriter, r *http.Request) {
+	user, ok := requireUser(w, r)
+	if !ok {
+		return
+	}
+	if !user.DebugModeEnabled {
+		w.WriteHeader(http.StatusNoContent)
+		return
+	}
+	var req reportDiagnosticsRequest
+	if !decodeBody(w, r, &req) {
+		return
+	}
+	if strings.TrimSpace(req.ClientID) == "" {
+		writeErr(w, apierror.BadRequest("bad_request", "client_id required"))
+		return
+	}
+	if len(req.Events) == 0 {
+		writeJSON(w, http.StatusAccepted, map[string]int{"accepted": 0})
+		return
+	}
+	if len(req.Events) > maxDiagnosticBatch {
+		writeErr(w, apierror.BadRequest("batch_too_large", "too many events in one batch"))
+		return
+	}
+	for i := range req.Events {
+		if _, valid := validDiagnosticKinds[req.Events[i].Kind]; !valid {
+			writeErr(w, apierror.BadRequest("invalid_kind", "unknown diagnostic kind"))
+			return
+		}
+	}
+
+	err := pgx.BeginFunc(r.Context(), h.pool, func(tx pgx.Tx) error {
+		q := dbq.New(tx)
+		for i := range req.Events {
+			ev := req.Events[i]
+			payload := ev.Payload
+			if len(payload) == 0 {
+				payload = json.RawMessage("{}")
+			}
+			if _, err := q.InsertDiagnosticEvent(r.Context(), dbq.InsertDiagnosticEventParams{
+				UserID:     user.ID,
+				ClientID:   req.ClientID,
+				AppVersion: req.AppVersion,
+				OsVersion:  req.OsVersion,
+				Kind:       ev.Kind,
+				Payload:    payload,
+				OccurredAt: pgtype.Timestamptz{Time: time.UnixMilli(ev.OccurredAt).UTC(), Valid: true},
+			}); err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		writeErrWithLog(w, h.logger, "diagnostics: insert batch failed", apierror.Internal(err))
+		return
+	}
+	writeJSON(w, http.StatusAccepted, map[string]int{"accepted": len(req.Events)})
+}
+
+// adminDiagnosticView is one row in the admin timeline response. Payload
+// is passed through verbatim as raw JSON so the SPA can render / export
+// the structured event without the server re-shaping it.
+type adminDiagnosticView struct {
+	ID         string          `json:"id"`
+	UserID     string          `json:"user_id"`
+	Username   string          `json:"username"`
+	ClientID   string          `json:"client_id"`
+	AppVersion *string         `json:"app_version,omitempty"`
+	OsVersion  *string         `json:"os_version,omitempty"`
+	Kind       string          `json:"kind"`
+	Payload    json.RawMessage `json:"payload"`
+	OccurredAt string          `json:"occurred_at"`
+	ReceivedAt string          `json:"received_at"`
+}
+
+// handleListAdminDiagnostics implements GET /api/admin/diagnostics with
+// optional filters user_id, client_id, kind, from, to (RFC3339 or epoch
+// millis) plus limit/offset. Newest-first; the SPA reverses for a
+// chronological timeline + export.
+func (h *handlers) handleListAdminDiagnostics(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query()
+	params, ok := h.buildDiagnosticsFilter(w, q)
+	if !ok {
+		return
+	}
+	rows, err := dbq.New(h.pool).ListAdminDiagnostics(r.Context(), params)
+	if err != nil {
+		writeErrWithLog(w, h.logger, "admin: list diagnostics failed", apierror.Internal(err))
+		return
+	}
+	out := make([]adminDiagnosticView, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, adminDiagnosticView{
+			ID:         uuidToString(row.ID),
+			UserID:     uuidToString(row.UserID),
+			Username:   row.Username,
+			ClientID:   row.ClientID,
+			AppVersion: row.AppVersion,
+			OsVersion:  row.OsVersion,
+			Kind:       row.Kind,
+			Payload:    json.RawMessage(row.Payload),
+			OccurredAt: formatTimestamp(row.OccurredAt),
+			ReceivedAt: formatTimestamp(row.ReceivedAt),
+		})
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+// buildDiagnosticsFilter parses the query string into a query param
+// struct, writing a 400 and returning ok=false on a malformed time.
+func (h *handlers) buildDiagnosticsFilter(
+	w http.ResponseWriter, q map[string][]string,
+) (dbq.ListAdminDiagnosticsParams, bool) {
+	get := func(k string) string {
+		if v, present := q[k]; present && len(v) > 0 {
+			return v[0]
+		}
+		return ""
+	}
+	limit, offset, err := parseDiagPaging(get("limit"), get("offset"))
+	if err != nil {
+		writeErr(w, apierror.BadRequest("bad_request", "invalid limit or offset"))
+		return dbq.ListAdminDiagnosticsParams{}, false
+	}
+	from, okFrom := parseDiagTime(get("from"))
+	to, okTo := parseDiagTime(get("to"))
+	if !okFrom || !okTo {
+		writeErr(w, apierror.BadRequest("bad_request", "invalid from/to timestamp"))
+		return dbq.ListAdminDiagnosticsParams{}, false
+	}
+	params := dbq.ListAdminDiagnosticsParams{
+		ClientID: optionalQuery(get("client_id")),
+		Kind:     optionalQuery(get("kind")),
+		FromTs:   from,
+		ToTs:     to,
+		Off:      int32(offset),
+		Lim:      int32(limit),
+	}
+	if uid, valid := parseUUID(get("user_id")); valid {
+		params.UserID = uid
+	}
+	return params, true
+}
+
+// adminDiagnosticDeviceView is one device in the "who is reporting"
+// overview / device filter dropdown.
+type adminDiagnosticDeviceView struct {
+	ClientID   string `json:"client_id"`
+	UserID     string `json:"user_id"`
+	Username   string `json:"username"`
+	AppVersion string `json:"app_version"`
+	OsVersion  string `json:"os_version"`
+	LastSeen   string `json:"last_seen"`
+	EventCount int64  `json:"event_count"`
+}
+
+// handleListAdminDiagnosticDevices implements GET
+// /api/admin/diagnostics/devices?user_id=. Lists distinct reporting
+// devices so the admin UI can populate its device filter.
+func (h *handlers) handleListAdminDiagnosticDevices(w http.ResponseWriter, r *http.Request) {
+	var userID pgtype.UUID
+	if uid, valid := parseUUID(r.URL.Query().Get("user_id")); valid {
+		userID = uid
+	}
+	rows, err := dbq.New(h.pool).ListDiagnosticDevices(r.Context(), userID)
+	if err != nil {
+		writeErrWithLog(w, h.logger, "admin: list diagnostic devices failed", apierror.Internal(err))
+		return
+	}
+	out := make([]adminDiagnosticDeviceView, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, adminDiagnosticDeviceView{
+			ClientID:   row.ClientID,
+			UserID:     uuidToString(row.UserID),
+			Username:   row.Username,
+			AppVersion: row.AppVersion,
+			OsVersion:  row.OsVersion,
+			LastSeen:   formatTimestamp(row.LastSeen),
+			EventCount: row.EventCount,
+		})
+	}
+	writeJSON(w, http.StatusOK, out)
+}
+
+// adminDebugModeReq is the body of PUT /api/admin/users/{id}/debug-mode.
+type adminDebugModeReq struct {
+	Enabled bool `json:"enabled"`
+}
+
+// handleAdminDebugModeToggle implements PUT
+// /api/admin/users/{id}/debug-mode — flip an account's diagnostics
+// opt-in remotely while a bug is live. Echoes the updated user.
+func (h *handlers) handleAdminDebugModeToggle(w http.ResponseWriter, r *http.Request) {
+	targetID, ok := requireURLUUID(w, r, "id")
+	if !ok {
+		return
+	}
+	var req adminDebugModeReq
+	if !decodeBody(w, r, &req) {
+		return
+	}
+	updated, err := dbq.New(h.pool).SetDebugMode(r.Context(), dbq.SetDebugModeParams{
+		ID:               targetID,
+		DebugModeEnabled: req.Enabled,
+	})
+	if err != nil {
+		writeErrWithLog(w, h.logger, "admin: set debug mode failed", apierror.Internal(err))
+		return
+	}
+	h.logger.Info("admin: debug mode toggled",
+		"target_user", uuidToString(targetID), "enabled", req.Enabled)
+	writeJSON(w, http.StatusOK, adminUserView{
+		ID:                  uuidToString(updated.ID),
+		Username:            updated.Username,
+		DisplayName:         updated.DisplayName,
+		IsAdmin:             updated.IsAdmin,
+		AutoApproveRequests: updated.AutoApproveRequests,
+		DebugModeEnabled:    updated.DebugModeEnabled,
+		CreatedAt:           updated.CreatedAt.Time.UTC().Format(time.RFC3339),
+	})
+}
+
+// parseDiagPaging reads limit/offset with diagnostics-specific caps.
+// Blank → defaults; out-of-range clamps; non-numeric → error.
+func parseDiagPaging(rawLimit, rawOffset string) (limit, offset int, err error) {
+	limit = defaultDiagnosticPageSize
+	if s := strings.TrimSpace(rawLimit); s != "" {
+		n, perr := strconv.Atoi(s)
+		if perr != nil {
+			return 0, 0, perr
+		}
+		if n < 1 {
+			n = 1
+		}
+		if n > maxDiagnosticPageSize {
+			n = maxDiagnosticPageSize
+		}
+		limit = n
+	}
+	if s := strings.TrimSpace(rawOffset); s != "" {
+		n, perr := strconv.Atoi(s)
+		if perr != nil {
+			return 0, 0, perr
+		}
+		if n > 0 {
+			offset = n
+		}
+	}
+	return limit, offset, nil
+}
+
+// optionalQuery returns nil for an absent/blank query value so the sqlc
+// NULL-or-equals filter treats it as "no filter."
+func optionalQuery(raw string) *string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil
+	}
+	return &raw
+}
+
+// parseDiagTime accepts RFC3339 or epoch-millis. Empty = absent (NULL
+// filter, ok=true). Returns ok=false only on a non-empty unparseable value.
+func parseDiagTime(raw string) (pgtype.Timestamptz, bool) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return pgtype.Timestamptz{}, true
+	}
+	if t, err := time.Parse(time.RFC3339, raw); err == nil {
+		return pgtype.Timestamptz{Time: t.UTC(), Valid: true}, true
+	}
+	if ms, err := strconv.ParseInt(raw, 10, 64); err == nil {
+		return pgtype.Timestamptz{Time: time.UnixMilli(ms).UTC(), Valid: true}, true
+	}
+	return pgtype.Timestamptz{}, false
+}

internal/api/events.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"errors"
 	"net/http"
+	"strings"
 	"time"
 
 	"github.com/jackc/pgx/v5"
@@ -24,6 +25,33 @@ type eventRequest struct {
 	// / "discover" feed the system-playlist rotation dedup (#415);
 	// absent / "" for library, user-playlist, radio, Subsonic.
 	Source *string `json:"source"`
+	// DeviceClass is the client's self-reported device class (#1551),
+	// normalized + stored per play to condition radio on the current device.
+	DeviceClass *string `json:"device_class"`
+}
+
+// knownDeviceClasses whitelists the device classes the context-affinity facet
+// buckets by (#1551). A client sends one; anything unrecognized normalizes to
+// "other", and empty/absent to "" (stored NULL → excluded from the device
+// dimension). Kept permissive (no DB CHECK) so a new client class is one
+// whitelist entry, not a migration.
+var knownDeviceClasses = map[string]bool{
+	"mobile": true, "tablet": true, "desktop": true,
+	"web": true, "tv": true, "watch": true,
+}
+
+func normalizeDeviceClass(dc *string) string {
+	if dc == nil {
+		return ""
+	}
+	s := strings.ToLower(strings.TrimSpace(*dc))
+	if s == "" {
+		return ""
+	}
+	if knownDeviceClasses[s] {
+		return s
+	}
+	return "other"
 }
 
 type playStartedResponse struct {
@@ -31,6 +59,26 @@ type playStartedResponse struct {
 	SessionID   string `json:"session_id"`
 }
 
+// eventFutureSkew is the tolerated client-clock drift into the future
+// before a timestamp is treated as bogus and replaced with now.
+const eventFutureSkew = 5 * time.Minute
+
+// clampEventTime bounds a client-supplied event timestamp to sanity:
+// no earlier than the account's creation (offline replays can
+// legitimately be days old, but no play can predate the user) and no
+// later than now + a small skew allowance. Unbounded client clocks
+// previously let a skewed device write arbitrarily old plays, which
+// poisoned Rediscover's "not played in 6 months" ordering (#1246).
+func clampEventTime(at, userCreatedAt, now time.Time) time.Time {
+	if at.Before(userCreatedAt) {
+		return userCreatedAt
+	}
+	if at.After(now.Add(eventFutureSkew)) {
+		return now
+	}
+	return at
+}
+
 type okResponse struct {
 	OK bool `json:"ok"`
 }
@@ -52,7 +100,7 @@ func (h *handlers) handleEvents(w http.ResponseWriter, r *http.Request) {
 			writeErr(w, apierror.BadRequest("bad_request", "invalid `at` timestamp"))
 			return
 		}
-		at = parsed
+		at = clampEventTime(parsed.UTC(), user.CreatedAt.Time, time.Now().UTC())
 	}
 	clientID := ""
 	if req.ClientID != nil {
@@ -94,7 +142,9 @@ func (h *handlers) handleEventPlayStarted(
 	if req.Source != nil {
 		source = *req.Source
 	}
-	res, err := h.events.RecordPlayStartedWithSource(r.Context(), user.ID, trackID, clientID, source, at)
+	deviceClass := normalizeDeviceClass(req.DeviceClass)
+	res, err := h.events.RecordPlayStartedWithSource(
+		r.Context(), user.ID, trackID, clientID, source, deviceClass, at)
 	if err != nil {
 		h.logger.Error("api: events: play_started", "err", err)
 		writeErr(w, apierror.InternalMsg("record failed", err))
@@ -139,7 +189,8 @@ func (h *handlers) handleEventPlayOffline(
 		source = *req.Source
 	}
 	if err := h.events.RecordOfflinePlay(
-		r.Context(), user.ID, trackID, clientID, source, at, *req.DurationPlayedMs,
+		r.Context(), user.ID, trackID, clientID, source,
+		normalizeDeviceClass(req.DeviceClass), at, *req.DurationPlayedMs,
 	); err != nil {
 		h.logger.Error("api: events: play_offline", "err", err)
 		writeErr(w, apierror.InternalMsg("record failed", err))

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, h.dataDir, nil, eventbus.New(), nil, nil)
+	Mount(r, h.pool, h.logger, w, config.RecommendationConfig{RadioSize: 50, RadioSizeMax: 200, RecentlyPlayedHours: 1}, h.recSettings, h.lidarrCfg, h.lidarrRequests, h.lidarrQuarantine, h.tracks, h.playlists, h.coverart, h.coverSettings, h.tagSettings, h.scanner, h.scanCfg, h.dataDir, nil, eventbus.New(), nil, nil)
 
 	paths := []string{
 		"/api/artists",

internal/api/me_profile.go

@@ -35,6 +35,10 @@ type meProfileResp struct {
 	DisplayName *string `json:"display_name"`
 	Email       *string `json:"email"`
 	IsAdmin     bool    `json:"is_admin"`
+	// DebugModeEnabled is the account's diagnostics opt-in. The client
+	// reads it here to decide whether to run the on-device diagnostics
+	// reporter (M9). Admin-set; the client also has a local OFF switch.
+	DebugModeEnabled bool `json:"debug_mode_enabled"`
 }
 
 func (h *handlers) handleUpdateMyProfile(w http.ResponseWriter, r *http.Request) {
@@ -120,10 +124,11 @@ func (h *handlers) handleUpdateMyProfile(w http.ResponseWriter, r *http.Request)
 
 func profileViewFromUser(u dbq.User) meProfileResp {
 	return meProfileResp{
-		ID:          uuidToString(u.ID),
-		Username:    u.Username,
-		DisplayName: u.DisplayName,
-		Email:       u.Email,
-		IsAdmin:     u.IsAdmin,
+		ID:               uuidToString(u.ID),
+		Username:         u.Username,
+		DisplayName:      u.DisplayName,
+		Email:            u.Email,
+		IsAdmin:          u.IsAdmin,
+		DebugModeEnabled: u.DebugModeEnabled,
 	}
 }

internal/api/me_recommendation_metrics.go

@@ -2,7 +2,9 @@ package api
 
 import (
 	"net/http"
+	"sort"
 	"strconv"
+	"strings"
 
 	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
@@ -11,28 +13,142 @@ import (
 const (
 	recMetricsDefaultDays = 30
 	recMetricsMaxDays     = 365
+
+	// recMetricsLowVolume marks a family as low-confidence rather than
+	// hiding it: with fewer plays than this a skip rate is anecdote, not
+	// signal, but silently dropping the row would misread as "surface
+	// unused". The web renders low-confidence rows dimmed.
+	recMetricsLowVolume = 20
 )
 
-// recommendationMetric is one recommendation surface's outcomes.
-type recommendationMetric struct {
-	Source        string  `json:"source"`         // 'for_you' | 'discover' | mixes
-	Plays         int64   `json:"plays"`          // plays launched from this surface
+// Surface intents (milestone #127): each family is judged against its
+// job, not one global bar — discovery mixes are EXPECTED to run higher
+// skip rates than the go-to surfaces.
+const (
+	intentGoTo      = "go_to"
+	intentDiscovery = "discovery"
+	intentDirect    = "direct"
+)
+
+// surfaceMetric is one bucketed surface family's outcomes.
+type surfaceMetric struct {
+	Key           string  `json:"key"`            // stable family key ("for_you", "radio", …)
+	Label         string  `json:"label"`          // display label
+	Plays         int64   `json:"plays"`          // plays launched from this family
 	Skips         int64   `json:"skips"`          // of those, marked skipped
 	SkipRate      float64 `json:"skip_rate"`      // skips / plays, [0,1]
 	AvgCompletion float64 `json:"avg_completion"` // mean completion ratio, [0,1]
+	LowConfidence bool    `json:"low_confidence"` // plays < recMetricsLowVolume
+	// Breakdown splits the family into the pick-kind populations its
+	// builder stamped (#1249, generalized #1270): For You's taste/fresh,
+	// Discover's buckets, tier1-3 for tiered mixes — plus earlier plays
+	// that predate attribution. Present only when the family has at
+	// least one attributed play; the parent row remains the sum of its
+	// breakdown.
+	Breakdown []surfaceMetric `json:"breakdown,omitempty"`
+}
+
+// surfaceGroup is one intent band of surface families.
+type surfaceGroup struct {
+	Intent   string          `json:"intent"` // go_to | discovery | direct
+	Label    string          `json:"label"`
+	Surfaces []surfaceMetric `json:"surfaces"`
 }
 
 type recommendationMetricsResp struct {
-	WindowDays int                    `json:"window_days"`
-	Sources    []recommendationMetric `json:"sources"`
+	WindowDays int `json:"window_days"`
+	// Baseline is the control group: plays the user picked manually
+	// (source IS NULL). Surfaces are judged as deltas against it; nil
+	// when the window holds no manual plays.
+	Baseline *surfaceMetric `json:"baseline"`
+	Groups   []surfaceGroup `json:"groups"`
+}
+
+// recFamily is the bucketing target for a raw play_events.source value.
+type recFamily struct {
+	key    string
+	label  string
+	intent string
+}
+
+// bucketRecSource maps a raw client-stamped source string to its stable
+// family. One-off sources (album:<uuid>, radio:<uuid>) collapse into
+// their family so the table stays readable at any library size.
+func bucketRecSource(src string) recFamily {
+	switch {
+	case src == "for_you":
+		return recFamily{"for_you", "For You", intentGoTo}
+	case src == "songs_like_artist":
+		return recFamily{"songs_like_artist", "Songs like…", intentGoTo}
+	case src == "radio" || strings.HasPrefix(src, "radio:"):
+		return recFamily{"radio", "Radio", intentGoTo}
+	case src == "discover":
+		return recFamily{"discover", "Discover", intentDiscovery}
+	case src == "deep_cuts":
+		return recFamily{"deep_cuts", "Deep cuts", intentDiscovery}
+	case src == "rediscover":
+		return recFamily{"rediscover", "Rediscover", intentDiscovery}
+	case src == "new_for_you":
+		return recFamily{"new_for_you", "New for you", intentDiscovery}
+	case src == "on_this_day":
+		return recFamily{"on_this_day", "On this day", intentDiscovery}
+	case src == "first_listens":
+		return recFamily{"first_listens", "First listens", intentDiscovery}
+	case strings.HasPrefix(src, "album:"):
+		return recFamily{"direct_album", "Album plays", intentDirect}
+	case strings.HasPrefix(src, "artist:"):
+		return recFamily{"direct_artist", "Artist plays", intentDirect}
+	case strings.HasPrefix(src, "offline:"):
+		return recFamily{"offline", "Offline pools", intentDirect}
+	case strings.HasPrefix(src, "home:"):
+		return recFamily{"home", "Home sections", intentDirect}
+	case src == "history":
+		return recFamily{"history", "History", intentDirect}
+	default:
+		return recFamily{"other", "Other", intentDirect}
+	}
+}
+
+// familyAccum merges raw source rows into one family, carrying the
+// completion sample count so the merged average stays play-weighted.
+type familyAccum struct {
+	fam         recFamily
+	plays       int64
+	skips       int64
+	completionN int64
+	// completionSum is avg*count re-expanded, so merging N raw rows
+	// reduces to a single weighted division at the end.
+	completionSum float64
+}
+
+func (a *familyAccum) add(row dbq.RecommendationSourceMetricsForUserRow) {
+	a.plays += row.Plays
+	a.skips += row.Skips
+	a.completionN += row.CompletionN
+	a.completionSum += row.AvgCompletion * float64(row.CompletionN)
+}
+
+func (a *familyAccum) metric() surfaceMetric {
+	m := surfaceMetric{
+		Key:           a.fam.key,
+		Label:         a.fam.label,
+		Plays:         a.plays,
+		Skips:         a.skips,
+		LowConfidence: a.plays < recMetricsLowVolume,
+	}
+	if a.plays > 0 {
+		m.SkipRate = float64(a.skips) / float64(a.plays)
+	}
+	if a.completionN > 0 {
+		m.AvgCompletion = a.completionSum / float64(a.completionN)
+	}
+	return m
 }
 
 // handleGetRecommendationMetrics implements GET /api/me/recommendation-metrics.
-// Per-source play outcomes (plays / skips / skip-rate / avg-completion) for the
-// caller over the last `days` (default 30, capped at 365), so the operator can
-// see which recommendation surfaces are landing and tune the taste weights.
-// Only plays tagged with a system-playlist source count; library/radio plays
-// (no source) are excluded.
+// Bucketed per-surface-family outcomes for the caller over the last `days`
+// (default 30, capped at 365), grouped by surface intent and anchored by the
+// manual-plays baseline so the numbers are judgeable, not just observable.
 func (h *handlers) handleGetRecommendationMetrics(w http.ResponseWriter, r *http.Request) {
 	caller, ok := requireUser(w, r)
 	if !ok {
@@ -51,28 +167,142 @@ func (h *handlers) handleGetRecommendationMetrics(w http.ResponseWriter, r *http
 		return
 	}
 
-	out := recommendationMetricsResp{
-		WindowDays: days,
-		Sources:    make([]recommendationMetric, 0, len(rows)),
+	writeJSON(w, http.StatusOK, bucketMetricsResponse(days, rows))
+}
+
+// pickKindLabels is the display vocabulary for play_events.pick_kind
+// values (mirrors the CHECK in migration 0041). Every system mix that
+// stamps provenance gets its breakdown from this one map — adding a
+// stamping mix needs no metrics change.
+var pickKindLabels = map[string]string{
+	"taste":         "Taste picks",
+	"fresh":         "Fresh picks",
+	"dormant":       "Dormant artists",
+	"taste_unheard": "Taste-matched",
+	"cross_user":    "Liked by others",
+	"random":        "Random unheard",
+	"tier1":         "Tier 1 (exact)",
+	"tier2":         "Tier 2 (relaxed)",
+	"tier3":         "Tier 3 (stretched)",
+}
+
+// pickKindOrder fixes breakdown row order; unattributed ("", i.e. NULL
+// pick_kind — plays recorded before the mix stamped provenance, or
+// whose track had rotated out of the snapshot at ingestion) renders
+// last, kept visible so the parent row's sums stay transparent instead
+// of silently shrinking. The DB CHECK gates pick_kind to exactly this
+// vocabulary, so iterating the list is exhaustive.
+var pickKindOrder = []string{
+	"taste", "fresh", "dormant", "taste_unheard", "cross_user", "random",
+	"tier1", "tier2", "tier3", "",
+}
+
+// pickKindFamily derives the sub-family for one (family, pick_kind)
+// population, e.g. ("for_you", "taste") → for_you_taste "Taste picks".
+func pickKindFamily(parent recFamily, kind string) recFamily {
+	if kind == "" {
+		return recFamily{parent.key + "_unattributed", "Earlier plays", parent.intent}
 	}
+	label, ok := pickKindLabels[kind]
+	if !ok {
+		label = kind
+	}
+	return recFamily{parent.key + "_" + kind, label, parent.intent}
+}
+
+// pickKindBreakdown folds a family's per-pick-kind accums into its
+// Breakdown rows. Attached only when at least one attributed play
+// exists — an all-unattributed breakdown would just repeat the parent
+// row, and families that never stamp (radio, direct plays) stay flat.
+func pickKindBreakdown(picks map[string]*familyAccum) []surfaceMetric {
+	attributed := int64(0)
+	for kind, acc := range picks {
+		if kind != "" {
+			attributed += acc.plays
+		}
+	}
+	if attributed == 0 {
+		return nil
+	}
+	out := make([]surfaceMetric, 0, len(picks))
+	for _, kind := range pickKindOrder {
+		if acc, ok := picks[kind]; ok && acc.plays > 0 {
+			out = append(out, acc.metric())
+		}
+	}
+	return out
+}
+
+// bucketMetricsResponse folds the raw per-source rows into the grouped,
+// baseline-anchored response shape. Split from the handler for pure-unit
+// testability.
+func bucketMetricsResponse(
+	days int, rows []dbq.RecommendationSourceMetricsForUserRow,
+) recommendationMetricsResp {
+	baseline := &familyAccum{fam: recFamily{"manual", "Manual library plays", ""}}
+	families := map[string]*familyAccum{}
+	picks := map[string]map[string]*familyAccum{}
 	for _, row := range rows {
-		source := ""
-		if row.Source != nil {
-			source = *row.Source
+		if row.Source == nil || *row.Source == "" {
+			baseline.add(row)
+			continue
 		}
-		var skipRate float64
-		if row.Plays > 0 {
-			skipRate = float64(row.Skips) / float64(row.Plays)
+		fam := bucketRecSource(*row.Source)
+		acc, exists := families[fam.key]
+		if !exists {
+			acc = &familyAccum{fam: fam}
+			families[fam.key] = acc
 		}
-		out.Sources = append(out.Sources, recommendationMetric{
-			Source:        source,
-			Plays:         row.Plays,
-			Skips:         row.Skips,
-			SkipRate:      skipRate,
-			AvgCompletion: row.AvgCompletion,
-		})
+		acc.add(row)
+		// Accumulate the pick-kind population unconditionally; families
+		// that never stamp end up all-unattributed and get no breakdown.
+		kind := ""
+		if row.PickKind != nil {
+			kind = *row.PickKind
+		}
+		byKind, ok := picks[fam.key]
+		if !ok {
+			byKind = map[string]*familyAccum{}
+			picks[fam.key] = byKind
+		}
+		pick, ok := byKind[kind]
+		if !ok {
+			pick = &familyAccum{fam: pickKindFamily(fam, kind)}
+			byKind[kind] = pick
+		}
+		pick.add(row)
 	}
-	writeJSON(w, http.StatusOK, out)
+
+	resp := recommendationMetricsResp{WindowDays: days, Groups: []surfaceGroup{}}
+	if baseline.plays > 0 {
+		m := baseline.metric()
+		resp.Baseline = &m
+	}
+	for _, g := range []struct{ intent, label string }{
+		{intentGoTo, "Go-to surfaces"},
+		{intentDiscovery, "Discovery mixes"},
+		{intentDirect, "Direct plays"},
+	} {
+		group := surfaceGroup{Intent: g.intent, Label: g.label}
+		for _, acc := range families {
+			if acc.fam.intent == g.intent {
+				m := acc.metric()
+				m.Breakdown = pickKindBreakdown(picks[acc.fam.key])
+				group.Surfaces = append(group.Surfaces, m)
+			}
+		}
+		if len(group.Surfaces) == 0 {
+			continue
+		}
+		sort.Slice(group.Surfaces, func(i, j int) bool {
+			if group.Surfaces[i].Plays != group.Surfaces[j].Plays {
+				return group.Surfaces[i].Plays > group.Surfaces[j].Plays
+			}
+			return group.Surfaces[i].Key < group.Surfaces[j].Key
+		})
+		resp.Groups = append(resp.Groups, group)
+	}
+	return resp
 }
 
 // parseMetricsDays reads the `days` query param (default 30, capped at 365).

internal/api/me_recommendation_metrics_test.go

@@ -11,6 +11,8 @@ import (
 
 	"github.com/go-chi/chi/v5"
 	"github.com/jackc/pgx/v5/pgtype"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
 )
 
 func newMetricsRouter(h *handlers) chi.Router {
@@ -20,17 +22,19 @@ func newMetricsRouter(h *handlers) chi.Router {
 }
 
 // seedSourcedPlay inserts a play_event with an explicit source + completion +
-// skip flag. A nil source inserts NULL (library/radio play).
+// skip flag. A nil source inserts NULL (manual library play → baseline).
+// pickKind is the For You taste/fresh attribution (#1249); nil everywhere
+// except attributed for_you plays.
 func seedSourcedPlay(
 	t *testing.T, h *handlers, userID, trackID, sessionID pgtype.UUID,
-	source *string, completion float64, skipped bool,
+	source, pickKind *string, completion float64, skipped bool,
 ) {
 	t.Helper()
 	if _, err := h.pool.Exec(context.Background(),
 		`INSERT INTO play_events
-		   (user_id, track_id, session_id, started_at, source, completion_ratio, was_skipped)
-		 VALUES ($1, $2, $3, now(), $4, $5, $6)`,
-		userID, trackID, sessionID, source, completion, skipped); err != nil {
+		   (user_id, track_id, session_id, started_at, source, pick_kind, completion_ratio, was_skipped)
+		 VALUES ($1, $2, $3, now(), $4, $5, $6, $7)`,
+		userID, trackID, sessionID, source, pickKind, completion, skipped); err != nil {
 		t.Fatalf("seed sourced play: %v", err)
 	}
 }
@@ -45,7 +49,168 @@ func TestRecommendationMetrics_NoSession401(t *testing.T) {
 	}
 }
 
-func TestRecommendationMetrics_AggregatesBySourceExcludingNull(t *testing.T) {
+// findSurface returns the named family from any group, or nil.
+func findSurface(resp recommendationMetricsResp, key string) *surfaceMetric {
+	for _, g := range resp.Groups {
+		for i := range g.Surfaces {
+			if g.Surfaces[i].Key == key {
+				return &g.Surfaces[i]
+			}
+		}
+	}
+	return nil
+}
+
+func TestBucketMetricsResponse_FamiliesGroupsBaseline(t *testing.T) {
+	src := func(s string) *string { return &s }
+	rows := []dbq.RecommendationSourceMetricsForUserRow{
+		{Source: src("for_you"), Plays: 3, Skips: 1, CompletionN: 3, AvgCompletion: 2.0 / 3},
+		// Two radio sessions collapse into one "radio" family; weighted
+		// completion = (0.2*1 + 0.8*1) / 2 = 0.5.
+		{Source: src("radio:aaaa"), Plays: 1, Skips: 1, CompletionN: 1, AvgCompletion: 0.2},
+		{Source: src("radio:bbbb"), Plays: 1, Skips: 0, CompletionN: 1, AvgCompletion: 0.8},
+		{Source: src("album:cccc"), Plays: 1, Skips: 0, CompletionN: 0, AvgCompletion: 0},
+		{Source: src("discover"), Plays: 1, Skips: 0, CompletionN: 1, AvgCompletion: 0.8},
+		// NULL source = manual plays → baseline, not a group row.
+		{Source: nil, Plays: 25, Skips: 5, CompletionN: 20, AvgCompletion: 0.9},
+	}
+	resp := bucketMetricsResponse(recMetricsDefaultDays, rows)
+
+	if resp.Baseline == nil {
+		t.Fatal("baseline missing")
+	}
+	if resp.Baseline.Plays != 25 || resp.Baseline.SkipRate != 0.2 {
+		t.Errorf("baseline = %+v, want plays=25 skip_rate=0.2", resp.Baseline)
+	}
+	if resp.Baseline.LowConfidence {
+		t.Error("baseline with 25 plays should not be low-confidence")
+	}
+
+	radio := findSurface(resp, "radio")
+	if radio == nil {
+		t.Fatal("radio family missing")
+	}
+	if radio.Plays != 2 || radio.Skips != 1 {
+		t.Errorf("radio plays/skips = %d/%d, want 2/1", radio.Plays, radio.Skips)
+	}
+	if radio.AvgCompletion < 0.49 || radio.AvgCompletion > 0.51 {
+		t.Errorf("radio avg_completion = %.3f, want 0.5 (play-weighted merge)", radio.AvgCompletion)
+	}
+	if !radio.LowConfidence {
+		t.Error("radio with 2 plays should be low-confidence")
+	}
+
+	if s := findSurface(resp, "direct_album"); s == nil || s.Plays != 1 {
+		t.Errorf("direct_album = %+v, want plays=1", s)
+	}
+	if s := findSurface(resp, ""); s != nil {
+		t.Error("NULL source must not appear as a surface family")
+	}
+
+	// No attributed (taste/fresh) plays in this fixture → no breakdown;
+	// an all-unattributed breakdown would just repeat the parent row.
+	if fy := findSurface(resp, "for_you"); fy == nil || fy.Breakdown != nil {
+		t.Errorf("for_you breakdown = %+v, want nil without attributed plays", fy)
+	}
+
+	// Group ordering is intent-banded: go_to before discovery before direct.
+	wantOrder := []string{intentGoTo, intentDiscovery, intentDirect}
+	if len(resp.Groups) != len(wantOrder) {
+		t.Fatalf("groups = %d, want %d", len(resp.Groups), len(wantOrder))
+	}
+	for i, g := range resp.Groups {
+		if g.Intent != wantOrder[i] {
+			t.Errorf("group[%d].intent = %s, want %s", i, g.Intent, wantOrder[i])
+		}
+	}
+}
+
+func TestBucketMetricsResponse_ForYouBreakdown(t *testing.T) {
+	src := func(s string) *string { return &s }
+	kind := func(s string) *string { return &s }
+	rows := []dbq.RecommendationSourceMetricsForUserRow{
+		{Source: src("for_you"), PickKind: kind("taste"), Plays: 30, Skips: 3,
+			CompletionN: 30, AvgCompletion: 0.9},
+		{Source: src("for_you"), PickKind: kind("fresh"), Plays: 10, Skips: 4,
+			CompletionN: 10, AvgCompletion: 0.5},
+		// NULL pick_kind = plays that predate attribution.
+		{Source: src("for_you"), Plays: 5, Skips: 1, CompletionN: 5, AvgCompletion: 0.7},
+	}
+	resp := bucketMetricsResponse(recMetricsDefaultDays, rows)
+
+	fy := findSurface(resp, "for_you")
+	if fy == nil {
+		t.Fatal("for_you family missing")
+	}
+	// The parent row stays the sum of its breakdown.
+	if fy.Plays != 45 || fy.Skips != 8 {
+		t.Errorf("for_you plays/skips = %d/%d, want 45/8", fy.Plays, fy.Skips)
+	}
+	if len(fy.Breakdown) != 3 {
+		t.Fatalf("breakdown rows = %d, want 3 (taste, fresh, earlier)", len(fy.Breakdown))
+	}
+	wantKeys := []string{"for_you_taste", "for_you_fresh", "for_you_unattributed"}
+	for i, k := range wantKeys {
+		if fy.Breakdown[i].Key != k {
+			t.Errorf("breakdown[%d].key = %s, want %s", i, fy.Breakdown[i].Key, k)
+		}
+	}
+	taste, fresh := fy.Breakdown[0], fy.Breakdown[1]
+	if taste.Plays != 30 || taste.SkipRate != 0.1 || taste.LowConfidence {
+		t.Errorf("taste = %+v, want plays=30 skip_rate=0.1 confident", taste)
+	}
+	if fresh.Plays != 10 || fresh.SkipRate != 0.4 || !fresh.LowConfidence {
+		t.Errorf("fresh = %+v, want plays=10 skip_rate=0.4 low-confidence", fresh)
+	}
+	// Breakdown rows never appear as their own surface families.
+	if s := findSurface(resp, "for_you_taste"); s != nil {
+		t.Error("for_you_taste must not be a top-level surface")
+	}
+}
+
+func TestBucketMetricsResponse_DiscoverBucketBreakdown(t *testing.T) {
+	// Provenance is standard (#1270): Discover's bucket stamps surface as
+	// a breakdown exactly like For You's taste/fresh — this is what makes
+	// the bucket allocation judgeable instead of a guess.
+	src := func(s string) *string { return &s }
+	kind := func(s string) *string { return &s }
+	rows := []dbq.RecommendationSourceMetricsForUserRow{
+		{Source: src("discover"), PickKind: kind("dormant"), Plays: 8, Skips: 2,
+			CompletionN: 8, AvgCompletion: 0.8},
+		{Source: src("discover"), PickKind: kind("cross_user"), Plays: 6, Skips: 3,
+			CompletionN: 6, AvgCompletion: 0.6},
+		{Source: src("discover"), PickKind: kind("random"), Plays: 4, Skips: 3,
+			CompletionN: 4, AvgCompletion: 0.4},
+		// NULL pick_kind = plays that predate bucket stamping.
+		{Source: src("discover"), Plays: 2, Skips: 0, CompletionN: 2, AvgCompletion: 0.9},
+	}
+	resp := bucketMetricsResponse(recMetricsDefaultDays, rows)
+
+	d := findSurface(resp, "discover")
+	if d == nil {
+		t.Fatal("discover family missing")
+	}
+	if d.Plays != 20 || d.Skips != 8 {
+		t.Errorf("discover plays/skips = %d/%d, want 20/8", d.Plays, d.Skips)
+	}
+	wantKeys := []string{
+		"discover_dormant", "discover_cross_user", "discover_random",
+		"discover_unattributed",
+	}
+	if len(d.Breakdown) != len(wantKeys) {
+		t.Fatalf("breakdown rows = %d, want %d", len(d.Breakdown), len(wantKeys))
+	}
+	for i, k := range wantKeys {
+		if d.Breakdown[i].Key != k {
+			t.Errorf("breakdown[%d].key = %s, want %s", i, d.Breakdown[i].Key, k)
+		}
+	}
+	if b := d.Breakdown[0]; b.Label != "Dormant artists" || b.Plays != 8 {
+		t.Errorf("dormant row = %+v, want label=Dormant artists plays=8", b)
+	}
+}
+
+func TestRecommendationMetrics_BucketsWithBaseline(t *testing.T) {
 	if os.Getenv("MINSTREL_TEST_DATABASE_URL") == "" {
 		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
 	}
@@ -57,15 +222,17 @@ func TestRecommendationMetrics_AggregatesBySourceExcludingNull(t *testing.T) {
 	session := seedPlaySession(t, pool, user.ID, time.Now())
 
 	forYou := "for_you"
-	discover := "discover"
+	radioA := "radio:11111111-1111-1111-1111-111111111111"
+	taste, fresh := "taste", "fresh"
 	// for_you: 3 plays, 1 skipped; completions 1.0, 0.95, 0.05 → mean 0.6667.
-	seedSourcedPlay(t, h, user.ID, tk.ID, session, &forYou, 1.0, false)
-	seedSourcedPlay(t, h, user.ID, tk.ID, session, &forYou, 0.95, false)
-	seedSourcedPlay(t, h, user.ID, tk.ID, session, &forYou, 0.05, true)
-	// discover: 1 play.
-	seedSourcedPlay(t, h, user.ID, tk.ID, session, &discover, 0.8, false)
-	// library play (NULL source) — must be excluded.
-	seedSourcedPlay(t, h, user.ID, tk.ID, session, nil, 1.0, false)
+	// Two attributed as taste picks, the skipped one as a fresh pick (#1249).
+	seedSourcedPlay(t, h, user.ID, tk.ID, session, &forYou, &taste, 1.0, false)
+	seedSourcedPlay(t, h, user.ID, tk.ID, session, &forYou, &taste, 0.95, false)
+	seedSourcedPlay(t, h, user.ID, tk.ID, session, &forYou, &fresh, 0.05, true)
+	// A radio session play collapses into the "radio" family.
+	seedSourcedPlay(t, h, user.ID, tk.ID, session, &radioA, nil, 0.8, false)
+	// Manual play (NULL source) — the baseline row.
+	seedSourcedPlay(t, h, user.ID, tk.ID, session, nil, nil, 1.0, false)
 
 	req := httptest.NewRequest(http.MethodGet, "/api/me/recommendation-metrics", nil)
 	req = withUser(req, user)
@@ -82,15 +249,11 @@ func TestRecommendationMetrics_AggregatesBySourceExcludingNull(t *testing.T) {
 	if resp.WindowDays != recMetricsDefaultDays {
 		t.Errorf("window_days = %d, want %d", resp.WindowDays, recMetricsDefaultDays)
 	}
-	bySource := map[string]recommendationMetric{}
-	for _, m := range resp.Sources {
-		bySource[m.Source] = m
+	if resp.Baseline == nil || resp.Baseline.Plays != 1 {
+		t.Fatalf("baseline = %+v, want plays=1", resp.Baseline)
 	}
-	if _, present := bySource[""]; present {
-		t.Error("NULL-source (library) plays should be excluded")
-	}
-	fy, ok := bySource["for_you"]
-	if !ok {
+	fy := findSurface(resp, "for_you")
+	if fy == nil {
 		t.Fatal("for_you metrics missing")
 	}
 	if fy.Plays != 3 || fy.Skips != 1 {
@@ -102,7 +265,17 @@ func TestRecommendationMetrics_AggregatesBySourceExcludingNull(t *testing.T) {
 	if fy.AvgCompletion < 0.66 || fy.AvgCompletion > 0.67 {
 		t.Errorf("for_you avg_completion = %.4f, want ~0.6667", fy.AvgCompletion)
 	}
-	if d, ok := bySource["discover"]; !ok || d.Plays != 1 || d.Skips != 0 {
-		t.Errorf("discover metrics = %+v, want plays=1 skips=0", d)
+	// Pick-kind attribution surfaces as the For You breakdown (#1249).
+	if len(fy.Breakdown) != 2 {
+		t.Fatalf("for_you breakdown rows = %d, want 2 (taste, fresh)", len(fy.Breakdown))
+	}
+	if b := fy.Breakdown[0]; b.Key != "for_you_taste" || b.Plays != 2 || b.Skips != 0 {
+		t.Errorf("breakdown[0] = %+v, want for_you_taste plays=2 skips=0", b)
+	}
+	if b := fy.Breakdown[1]; b.Key != "for_you_fresh" || b.Plays != 1 || b.Skips != 1 {
+		t.Errorf("breakdown[1] = %+v, want for_you_fresh plays=1 skips=1", b)
+	}
+	if radio := findSurface(resp, "radio"); radio == nil || radio.Plays != 1 {
+		t.Errorf("radio family = %+v, want plays=1 (collapsed from radio:<uuid>)", radio)
 	}
 }

internal/api/radio.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	"context"
 	"encoding/json"
 	"errors"
 	"log/slog"
@@ -15,6 +16,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/apierror"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/recommendation"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/recsettings"
 )
 
 // RadioResponse is the body of GET /api/radio.
@@ -80,6 +82,9 @@ func (h *handlers) handleRadio(w http.ResponseWriter, r *http.Request) {
 	}
 
 	currentVec := loadCurrentSessionVector(r, q, user.ID, h.logger)
+	// Condition on the current device (#1551): the latest play's device is a
+	// cheap, request-free proxy for what the user is on right now.
+	currentVec.DeviceClass = latestDeviceClass(r.Context(), q, user.ID, h.logger)
 
 	exclude := parseExcludeParam(r.URL.Query().Get("exclude"))
 	limits := recommendation.DefaultCandidateSourceLimits()
@@ -100,16 +105,9 @@ func (h *handlers) handleRadio(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	weights := recommendation.ScoringWeights{
-		BaseWeight:       h.recCfg.BaseWeight,
-		LikeBoost:        h.recCfg.LikeBoost,
-		RecencyWeight:    h.recCfg.RecencyWeight,
-		SkipPenalty:      h.recCfg.SkipPenalty,
-		JitterMagnitude:  h.recCfg.JitterMagnitude,
-		ContextWeight:    h.recCfg.ContextWeight,
-		SimilarityWeight: h.recCfg.SimilarityWeight,
-		TasteWeight:      h.recCfg.TasteWeight,
-	}
+	// Scoring weights come from the DB-backed tuning lab (#1250) —
+	// read per request so an admin change takes effect live.
+	weights := h.recSettings.Weights(recsettings.ScopeRadio)
 	picks := recommendation.Shuffle(candidates, weights, time.Now().UTC(), h.rng, limit-1)
 
 	out := make([]TrackRef, 0, len(picks)+1)
@@ -156,6 +154,24 @@ func loadCurrentSessionVector(r *http.Request, q *dbq.Queries, userID pgtype.UUI
 	return v
 }
 
+// latestDeviceClass returns the device_class of the user's most recent play as
+// the "current device" for context conditioning (#1551), or "" when unknown
+// (no plays yet, or the latest play predates device capture). Best-effort: a
+// lookup failure yields a device-agnostic ("") affinity cell.
+func latestDeviceClass(ctx context.Context, q *dbq.Queries, userID pgtype.UUID, logger *slog.Logger) string {
+	dc, err := q.GetLatestPlayDeviceClassForUser(ctx, userID)
+	if err != nil {
+		if !errors.Is(err, pgx.ErrNoRows) {
+			logger.Warn("api: radio: latest device class", "err", err)
+		}
+		return ""
+	}
+	if dc == nil {
+		return ""
+	}
+	return *dc
+}
+
 // parseExcludeParam parses a comma-separated list of UUIDs from the
 // `exclude` query string, silently dropping malformed entries. Returns
 // nil for empty or all-malformed input.

internal/config/config.go

@@ -88,20 +88,14 @@ type EventsConfig struct {
 	SkipMaxDurationPlayedMs int     `yaml:"skip_max_duration_played_ms"`
 }
 
-// RecommendationConfig governs the M3 weighted-shuffle scoring (spec §6).
-// All weights are operator-tunable; defaults match the spec recommendations.
+// RecommendationConfig holds the radio path's operational knobs. The
+// scoring WEIGHTS moved to DB-backed admin settings (#1250,
+// internal/recsettings) — YAML is bootstrap-only; anything an operator
+// tunes lives in the UI with live effect.
 type RecommendationConfig struct {
-	BaseWeight          float64 `yaml:"base_weight"`
-	LikeBoost           float64 `yaml:"like_boost"`
-	RecencyWeight       float64 `yaml:"recency_weight"`
-	SkipPenalty         float64 `yaml:"skip_penalty"`
-	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"`
+	RecentlyPlayedHours int `yaml:"recently_played_hours"`
+	RadioSize           int `yaml:"radio_size"`
+	RadioSizeMax        int `yaml:"radio_size_max"`
 }
 
 func Default() Config {
@@ -120,16 +114,6 @@ 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,
-			// 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/coplay/worker.go

@@ -0,0 +1,86 @@
+// Package coplay builds household co-play similarity edges (#1533, milestone
+// #160 Opt 5). Minstrel is a single shared-library, multi-user server (no
+// per-user library ACL), so the "household" is the whole instance's user set.
+// A periodic worker recomputes artist–artist co-occurrence from play_events
+// entirely in SQL (no external API) and stores the edges in artist_similarity
+// under source='user_cooccurrence' — the pre-provisioned co-occurrence source
+// from the 0009 schema — which the radio/mix candidate pool consumes as a
+// collaborative arm. Single-user servers produce no edges (the >= 2 co-player
+// gate), so the feature is a graceful no-op there.
+package coplay
+
+import (
+	"context"
+	"log/slog"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+)
+
+// minJaccard is the co-play edge floor: prune weak pairs and self-limit hub
+// artists, whose large combined-audience denominators pull their Jaccard down.
+// 0.1 keeps only pairs whose co-player overlap is a real fraction of their
+// combined audience.
+const minJaccard = 0.1
+
+// Worker periodically rebuilds the household co-play edge set. Pure local SQL,
+// so there are no rate limits — but the pair self-join is roughly
+// O(users × artists_per_user²), so it ticks slowly: co-listening shifts over
+// days, not minutes, and a frequent rebuild would burn CPU for no fresher
+// signal.
+type Worker struct {
+	pool   *pgxpool.Pool
+	logger *slog.Logger
+	tick   time.Duration
+}
+
+// NewWorker constructs a worker with the production default 6h tick.
+func NewWorker(pool *pgxpool.Pool, logger *slog.Logger) *Worker {
+	return &Worker{pool: pool, logger: logger, tick: 6 * time.Hour}
+}
+
+// Run rebuilds once at startup (so edges exist without waiting a full tick),
+// then every w.tick until ctx is cancelled. Runs in its own goroutine, so a
+// slow initial rebuild never blocks boot.
+func (w *Worker) Run(ctx context.Context) {
+	if err := w.rebuild(ctx); err != nil {
+		w.logger.Error("coplay: initial rebuild failed", "err", err)
+	}
+	t := time.NewTicker(w.tick)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			if err := w.rebuild(ctx); err != nil {
+				w.logger.Error("coplay: rebuild failed", "err", err)
+			}
+		}
+	}
+}
+
+// rebuild atomic-replaces the user_cooccurrence edge set inside one
+// transaction — delete the old edges, recompute from current play history — so
+// the candidate pool never observes a half-built set.
+func (w *Worker) rebuild(ctx context.Context) error {
+	tx, err := w.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+	q := dbq.New(tx)
+	if err := q.DeleteArtistCoplayEdges(ctx); err != nil {
+		return err
+	}
+	if err := q.InsertArtistCoplayEdges(ctx, minJaccard); err != nil {
+		return err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return err
+	}
+	w.logger.Debug("coplay: edges rebuilt")
+	return nil
+}

internal/coplay/worker_integration_test.go

@@ -0,0 +1,162 @@
+package coplay
+
+import (
+	"context"
+	"io"
+	"log/slog"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/db/dbq"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/dbtest"
+)
+
+func testPool(t *testing.T) *pgxpool.Pool {
+	t.Helper()
+	if testing.Short() {
+		t.Skip("skipping in -short mode")
+	}
+	dsn := os.Getenv("MINSTREL_TEST_DATABASE_URL")
+	if dsn == "" {
+		t.Skip("MINSTREL_TEST_DATABASE_URL not set")
+	}
+	if err := db.Migrate(dsn, slog.New(slog.NewTextHandler(io.Discard, nil))); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+	pool, err := pgxpool.New(context.Background(), dsn)
+	if err != nil {
+		t.Fatalf("pool: %v", err)
+	}
+	t.Cleanup(pool.Close)
+	dbtest.ResetDB(t, pool)
+	return pool
+}
+
+func discardLogger() *slog.Logger { return slog.New(slog.NewTextHandler(io.Discard, nil)) }
+
+func seedUser(t *testing.T, q *dbq.Queries, name string) pgtype.UUID {
+	t.Helper()
+	u, err := q.CreateUser(context.Background(), dbq.CreateUserParams{
+		Username: dbtest.TestUserPrefix + name, PasswordHash: "x", ApiToken: name + "-tok", IsAdmin: false,
+	})
+	if err != nil {
+		t.Fatalf("seed user %s: %v", name, err)
+	}
+	return u.ID
+}
+
+// seedArtistTrack creates an artist + album + one track, returning both ids.
+func seedArtistTrack(t *testing.T, q *dbq.Queries, name string) (pgtype.UUID, pgtype.UUID) {
+	t.Helper()
+	ctx := context.Background()
+	a, err := q.UpsertArtist(ctx, dbq.UpsertArtistParams{Name: name, SortName: name})
+	if err != nil {
+		t.Fatalf("seed artist: %v", err)
+	}
+	al, err := q.UpsertAlbum(ctx, dbq.UpsertAlbumParams{Title: name, SortTitle: name, ArtistID: a.ID})
+	if err != nil {
+		t.Fatalf("seed album: %v", err)
+	}
+	tr, err := q.UpsertTrack(ctx, dbq.UpsertTrackParams{
+		Title: name, AlbumID: al.ID, ArtistID: a.ID,
+		DurationMs: 1000, FilePath: "/tmp/coplay-" + name + ".mp3",
+		FileSize: 1, FileFormat: "mp3",
+	})
+	if err != nil {
+		t.Fatalf("seed track: %v", err)
+	}
+	return a.ID, tr.ID
+}
+
+func play(t *testing.T, pool *pgxpool.Pool, userID, trackID pgtype.UUID) {
+	t.Helper()
+	ctx := context.Background()
+	at := time.Now()
+	var sessionID pgtype.UUID
+	if err := pool.QueryRow(ctx,
+		`INSERT INTO play_sessions (user_id, started_at, last_event_at, client_id)
+		 VALUES ($1, $2, $2, 'coplay-test') RETURNING id`,
+		userID, at).Scan(&sessionID); err != nil {
+		t.Fatalf("insert play_session: %v", err)
+	}
+	if _, err := pool.Exec(ctx,
+		`INSERT INTO play_events (user_id, track_id, session_id, started_at, was_skipped)
+		 VALUES ($1, $2, $3, $4, false)`,
+		userID, trackID, sessionID, at); err != nil {
+		t.Fatalf("insert play_event: %v", err)
+	}
+}
+
+func coplayEdgeCount(t *testing.T, pool *pgxpool.Pool) int {
+	t.Helper()
+	var n int
+	if err := pool.QueryRow(context.Background(),
+		`SELECT count(*) FROM artist_similarity WHERE source='user_cooccurrence'`).Scan(&n); err != nil {
+		t.Fatalf("count edges: %v", err)
+	}
+	return n
+}
+
+// TestCoplayWorker_BuildsEdges: two users who both play two artists produce a
+// perfect-overlap co-play edge (Jaccard 1.0) in each direction.
+func TestCoplayWorker_BuildsEdges(t *testing.T) {
+	pool := testPool(t)
+	ctx := context.Background()
+	q := dbq.New(pool)
+
+	u1 := seedUser(t, q, "cop1")
+	u2 := seedUser(t, q, "cop2")
+	aA, tA := seedArtistTrack(t, q, "ArtA")
+	aB, tB := seedArtistTrack(t, q, "ArtB")
+
+	for _, u := range []pgtype.UUID{u1, u2} {
+		play(t, pool, u, tA)
+		play(t, pool, u, tB)
+	}
+
+	if err := NewWorker(pool, discardLogger()).rebuild(ctx); err != nil {
+		t.Fatalf("rebuild: %v", err)
+	}
+
+	var score float64
+	if err := pool.QueryRow(ctx,
+		`SELECT score FROM artist_similarity
+		 WHERE artist_a_id=$1 AND artist_b_id=$2 AND source='user_cooccurrence'`,
+		aA, aB).Scan(&score); err != nil {
+		t.Fatalf("expected co-play edge ArtA→ArtB: %v", err)
+	}
+	// Jaccard of perfectly-overlapping player sets (both users play both):
+	// coplayers=2, players each=2 → 2/(2+2-2) = 1.0.
+	if score != 1.0 {
+		t.Errorf("edge score = %v, want 1.0 (perfect overlap)", score)
+	}
+	if got := coplayEdgeCount(t, pool); got != 2 {
+		t.Errorf("edge count = %d, want 2 (A→B and B→A)", got)
+	}
+}
+
+// TestCoplayWorker_SingleUserNoEdges: one user's own co-listening yields no
+// edges — the >= 2 distinct-co-player gate keeps single-user servers empty.
+func TestCoplayWorker_SingleUserNoEdges(t *testing.T) {
+	pool := testPool(t)
+	ctx := context.Background()
+	q := dbq.New(pool)
+
+	u := seedUser(t, q, "solo")
+	_, tA := seedArtistTrack(t, q, "SoloA")
+	_, tB := seedArtistTrack(t, q, "SoloB")
+	play(t, pool, u, tA)
+	play(t, pool, u, tB)
+
+	if err := NewWorker(pool, discardLogger()).rebuild(ctx); err != nil {
+		t.Fatalf("rebuild: %v", err)
+	}
+	if got := coplayEdgeCount(t, pool); got != 0 {
+		t.Errorf("single-user edge count = %d, want 0 (>= 2 co-player gate)", got)
+	}
+}

internal/db/dbq/coplay.sql.go

@@ -0,0 +1,78 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: coplay.sql
+
+package dbq
+
+import (
+	"context"
+)
+
+const deleteArtistCoplayEdges = `-- name: DeleteArtistCoplayEdges :exec
+
+DELETE FROM artist_similarity WHERE source = 'user_cooccurrence'
+`
+
+// Household co-play similarity (#1533, milestone #160 Opt 5). Minstrel is a
+// single shared-library, multi-user server (no per-user library ACL), so the
+// "household" is the whole instance's user set. These queries recompute
+// artist–artist co-occurrence edges from play_events and store them in
+// artist_similarity under the pre-provisioned source = 'user_cooccurrence'
+// (whitelisted in the 0009 CHECK from day one). A periodic worker DELETEs then
+// re-INSERTs so edges that fall below threshold disappear. Single-user servers
+// produce no edges (the >= 2 co-player gate), so the arm is empty there.
+func (q *Queries) DeleteArtistCoplayEdges(ctx context.Context) error {
+	_, err := q.db.Exec(ctx, deleteArtistCoplayEdges)
+	return err
+}
+
+const insertArtistCoplayEdges = `-- name: InsertArtistCoplayEdges :exec
+WITH user_artists AS (
+    SELECT DISTINCT pe.user_id, t.artist_id
+    FROM play_events pe
+    JOIN tracks t ON t.id = pe.track_id
+    WHERE pe.was_skipped = false
+      AND pe.started_at > now() - interval '365 days'
+),
+artist_players AS (
+    SELECT artist_id, count(*)::float8 AS players
+    FROM user_artists
+    GROUP BY artist_id
+),
+pairs AS (
+    SELECT ua.artist_id AS a_id,
+           ub.artist_id AS b_id,
+           count(*)::float8 AS coplayers
+    FROM user_artists ua
+    JOIN user_artists ub
+      ON ua.user_id = ub.user_id AND ua.artist_id <> ub.artist_id
+    GROUP BY ua.artist_id, ub.artist_id
+    HAVING count(*) >= 2
+),
+scored AS (
+    SELECT p.a_id, p.b_id,
+           p.coplayers / (pa.players + pb.players - p.coplayers) AS score
+    FROM pairs p
+    JOIN artist_players pa ON pa.artist_id = p.a_id
+    JOIN artist_players pb ON pb.artist_id = p.b_id
+)
+INSERT INTO artist_similarity (artist_a_id, artist_b_id, score, source, fetched_at)
+SELECT a_id, b_id, score, 'user_cooccurrence', now()
+FROM scored
+WHERE score >= $1
+ON CONFLICT (artist_a_id, artist_b_id, source)
+DO UPDATE SET score = EXCLUDED.score, fetched_at = EXCLUDED.fetched_at
+`
+
+// Two artists are "co-played" when the same users play both. score is the
+// Jaccard of their distinct-player sets — coplayers / (playersA + playersB −
+// coplayers) in (0,1] — which controls for globally-popular artists (an artist
+// everyone plays would otherwise co-occur with everything). Only pairs with
+// >= 2 distinct co-players AND Jaccard >= $1 (a floor that both prunes weak
+// edges and self-limits hub artists, whose large denominators drag their
+// Jaccard down) are kept. Completed plays only, 365-day window.
+func (q *Queries) InsertArtistCoplayEdges(ctx context.Context, score float64) error {
+	_, err := q.db.Exec(ctx, insertArtistCoplayEdges, score)
+	return err
+}

internal/db/dbq/diagnostics.sql.go

@@ -0,0 +1,221 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: diagnostics.sql
+
+package dbq
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const gcPruneDiagnostics = `-- name: GcPruneDiagnostics :execrows
+DELETE FROM diagnostic_events WHERE received_at < now() - INTERVAL '30 days'
+`
+
+// Retention sweep for the gc worker. Deletes diagnostic_events older
+// than 30 days by server clock (received_at) so a skewed client clock
+// can't keep rows alive. Matches the other gc lifecycle sweeps'
+// hardcoded-threshold style; diagnostics are debug telemetry, not user
+// data, and 30 days is ample to investigate a live incident after the
+// fact. Returns the affected row count for the sweep log line.
+func (q *Queries) GcPruneDiagnostics(ctx context.Context) (int64, error) {
+	result, err := q.db.Exec(ctx, gcPruneDiagnostics)
+	if err != nil {
+		return 0, err
+	}
+	return result.RowsAffected(), nil
+}
+
+const insertDiagnosticEvent = `-- name: InsertDiagnosticEvent :one
+INSERT INTO diagnostic_events (
+    user_id, client_id, app_version, os_version, kind, payload, occurred_at
+)
+VALUES ($1, $2, $3, $4, $5, $6, $7)
+RETURNING id, received_at
+`
+
+type InsertDiagnosticEventParams struct {
+	UserID     pgtype.UUID
+	ClientID   string
+	AppVersion *string
+	OsVersion  *string
+	Kind       string
+	Payload    []byte
+	OccurredAt pgtype.Timestamptz
+}
+
+type InsertDiagnosticEventRow struct {
+	ID         pgtype.UUID
+	ReceivedAt pgtype.Timestamptz
+}
+
+// Records one client-reported diagnostic event. The writer validates the
+// `kind` category against its whitelist before this runs; the CHECK
+// constraint is the belt-and-braces guard. payload carries the finer
+// event discriminator + all event-specific fields. Returns received_at
+// so the caller can confirm ingest.
+func (q *Queries) InsertDiagnosticEvent(ctx context.Context, arg InsertDiagnosticEventParams) (InsertDiagnosticEventRow, error) {
+	row := q.db.QueryRow(ctx, insertDiagnosticEvent,
+		arg.UserID,
+		arg.ClientID,
+		arg.AppVersion,
+		arg.OsVersion,
+		arg.Kind,
+		arg.Payload,
+		arg.OccurredAt,
+	)
+	var i InsertDiagnosticEventRow
+	err := row.Scan(&i.ID, &i.ReceivedAt)
+	return i, err
+}
+
+const listAdminDiagnostics = `-- name: ListAdminDiagnostics :many
+SELECT
+    de.id          AS id,
+    de.user_id     AS user_id,
+    u.username     AS username,
+    de.client_id   AS client_id,
+    de.app_version AS app_version,
+    de.os_version  AS os_version,
+    de.kind        AS kind,
+    de.payload     AS payload,
+    de.occurred_at AS occurred_at,
+    de.received_at AS received_at
+FROM diagnostic_events de
+JOIN users u ON u.id = de.user_id
+WHERE ($1::uuid   IS NULL OR de.user_id   = $1::uuid)
+  AND ($2::text IS NULL OR de.client_id = $2::text)
+  AND ($3::text      IS NULL OR de.kind      = $3::text)
+  AND ($4::timestamptz IS NULL
+       OR de.occurred_at >= $4::timestamptz)
+  AND ($5::timestamptz IS NULL
+       OR de.occurred_at <= $5::timestamptz)
+ORDER BY de.occurred_at DESC
+LIMIT $7::int OFFSET $6::int
+`
+
+type ListAdminDiagnosticsParams struct {
+	UserID   pgtype.UUID
+	ClientID *string
+	Kind     *string
+	FromTs   pgtype.Timestamptz
+	ToTs     pgtype.Timestamptz
+	Off      int32
+	Lim      int32
+}
+
+type ListAdminDiagnosticsRow struct {
+	ID         pgtype.UUID
+	UserID     pgtype.UUID
+	Username   string
+	ClientID   string
+	AppVersion *string
+	OsVersion  *string
+	Kind       string
+	Payload    []byte
+	OccurredAt pgtype.Timestamptz
+	ReceivedAt pgtype.Timestamptz
+}
+
+// Admin timeline query. All filters are optional (NULL = no filter):
+// account (user_id), device (client_id), category (kind), and the
+// occurred_at window (from_ts/to_ts). Newest-first; the SPA reverses for
+// a chronological timeline / export. Joined with users for the username
+// so the view renders without a second round-trip.
+func (q *Queries) ListAdminDiagnostics(ctx context.Context, arg ListAdminDiagnosticsParams) ([]ListAdminDiagnosticsRow, error) {
+	rows, err := q.db.Query(ctx, listAdminDiagnostics,
+		arg.UserID,
+		arg.ClientID,
+		arg.Kind,
+		arg.FromTs,
+		arg.ToTs,
+		arg.Off,
+		arg.Lim,
+	)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListAdminDiagnosticsRow
+	for rows.Next() {
+		var i ListAdminDiagnosticsRow
+		if err := rows.Scan(
+			&i.ID,
+			&i.UserID,
+			&i.Username,
+			&i.ClientID,
+			&i.AppVersion,
+			&i.OsVersion,
+			&i.Kind,
+			&i.Payload,
+			&i.OccurredAt,
+			&i.ReceivedAt,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listDiagnosticDevices = `-- name: ListDiagnosticDevices :many
+SELECT
+    de.client_id            AS client_id,
+    de.user_id              AS user_id,
+    u.username              AS username,
+    max(de.app_version)::text        AS app_version,
+    max(de.os_version)::text         AS os_version,
+    max(de.occurred_at)::timestamptz AS last_seen,
+    count(*)                         AS event_count
+FROM diagnostic_events de
+JOIN users u ON u.id = de.user_id
+WHERE ($1::uuid IS NULL OR de.user_id = $1::uuid)
+GROUP BY de.client_id, de.user_id, u.username
+ORDER BY last_seen DESC
+`
+
+type ListDiagnosticDevicesRow struct {
+	ClientID   string
+	UserID     pgtype.UUID
+	Username   string
+	AppVersion string
+	OsVersion  string
+	LastSeen   pgtype.Timestamptz
+	EventCount int64
+}
+
+// Distinct devices that have reported, for the admin device filter +
+// "who is currently reporting" overview. Optionally scoped to one account.
+func (q *Queries) ListDiagnosticDevices(ctx context.Context, userID pgtype.UUID) ([]ListDiagnosticDevicesRow, error) {
+	rows, err := q.db.Query(ctx, listDiagnosticDevices, userID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListDiagnosticDevicesRow
+	for rows.Next() {
+		var i ListDiagnosticDevicesRow
+		if err := rows.Scan(
+			&i.ClientID,
+			&i.UserID,
+			&i.Username,
+			&i.AppVersion,
+			&i.OsVersion,
+			&i.LastSeen,
+			&i.EventCount,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}

internal/db/dbq/discover.sql.go

@@ -211,3 +211,69 @@ func (q *Queries) ListRandomUnheardTracksForDiscover(ctx context.Context, arg Li
 	}
 	return items, nil
 }
+
+const listTasteUnheardTracksForDiscover = `-- name: ListTasteUnheardTracksForDiscover :many
+SELECT t.id, t.album_id, t.artist_id
+  FROM tracks t
+  JOIN LATERAL regexp_split_to_table(coalesce(t.genre, ''), '[;,]') AS g_split(g) ON true
+  JOIN taste_profile_tags nt ON nt.user_id = $1 AND trim(g_split.g) = nt.tag
+ WHERE nt.weight > 0
+   AND trim(g_split.g) <> ''
+   AND NOT EXISTS (
+       SELECT 1 FROM play_events pe
+        WHERE pe.user_id = $1
+          AND pe.track_id = t.id
+          AND pe.was_skipped = false
+   )
+   AND NOT EXISTS (
+       SELECT 1 FROM general_likes gl
+        WHERE gl.user_id = $1 AND gl.track_id = t.id
+   )
+   AND NOT EXISTS (
+       SELECT 1 FROM lidarr_quarantine q
+        WHERE q.user_id = $1 AND q.track_id = t.id
+   )
+ GROUP BY t.id, t.album_id, t.artist_id
+ ORDER BY SUM(nt.weight) DESC, md5(t.id::text || $2::text)
+ LIMIT 120
+`
+
+type ListTasteUnheardTracksForDiscoverParams struct {
+	UserID  pgtype.UUID
+	Column2 string
+}
+
+type ListTasteUnheardTracksForDiscoverRow struct {
+	ID       pgtype.UUID
+	AlbumID  pgtype.UUID
+	ArtistID pgtype.UUID
+}
+
+// Taste-targeted novelty: unheard tracks whose genres overlap the user's
+// taste-profile tags (taste_profile_tags, #796), ranked by summed tag
+// weight — "new to you, but your vibe" rather than the crude random arm.
+// Genres live inline on tracks.genre as a delimited string, split the
+// same way the radio tag_overlap arm does (regexp_split_to_table on
+// [;,]). Same exclusion filters as the other buckets. Returns nothing
+// when the user has no taste tags yet (cold start), so the caller
+// redistributes its slots to the other buckets. Stamped 'taste_unheard'.
+// $1 = user_id, $2 = date string for md5 tiebreak ordering.
+func (q *Queries) ListTasteUnheardTracksForDiscover(ctx context.Context, arg ListTasteUnheardTracksForDiscoverParams) ([]ListTasteUnheardTracksForDiscoverRow, error) {
+	rows, err := q.db.Query(ctx, listTasteUnheardTracksForDiscover, arg.UserID, arg.Column2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTasteUnheardTracksForDiscoverRow
+	for rows.Next() {
+		var i ListTasteUnheardTracksForDiscoverRow
+		if err := rows.Scan(&i.ID, &i.AlbumID, &i.ArtistID); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}

internal/db/dbq/events.sql.go

@@ -54,7 +54,7 @@ func (q *Queries) GetMostRecentPlaySessionForUser(ctx context.Context, userID pg
 }
 
 const getOpenPlayEventForUser = `-- name: GetOpenPlayEventForUser :one
-SELECT id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source FROM play_events
+SELECT id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind, device_class FROM play_events
 WHERE user_id = $1 AND ended_at IS NULL
 ORDER BY started_at DESC
 LIMIT 1
@@ -79,12 +79,14 @@ func (q *Queries) GetOpenPlayEventForUser(ctx context.Context, userID pgtype.UUI
 		&i.SessionVectorAtPlay,
 		&i.ScrobbledAt,
 		&i.Source,
+		&i.PickKind,
+		&i.DeviceClass,
 	)
 	return i, err
 }
 
 const getPlayEventByID = `-- name: GetPlayEventByID :one
-SELECT id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source FROM play_events WHERE id = $1
+SELECT id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind, device_class FROM play_events WHERE id = $1
 `
 
 func (q *Queries) GetPlayEventByID(ctx context.Context, id pgtype.UUID) (PlayEvent, error) {
@@ -104,26 +106,67 @@ func (q *Queries) GetPlayEventByID(ctx context.Context, id pgtype.UUID) (PlayEve
 		&i.SessionVectorAtPlay,
 		&i.ScrobbledAt,
 		&i.Source,
+		&i.PickKind,
+		&i.DeviceClass,
 	)
 	return i, err
 }
 
+const getSystemPickKindForTrack = `-- name: GetSystemPickKindForTrack :one
+SELECT pt.pick_kind
+FROM playlist_tracks pt
+JOIN playlists p ON p.id = pt.playlist_id
+WHERE p.user_id = $1
+  AND p.system_variant = $2
+  AND pt.track_id = $3
+LIMIT 1
+`
+
+type GetSystemPickKindForTrackParams struct {
+	UserID        pgtype.UUID
+	SystemVariant *string
+	TrackID       pgtype.UUID
+}
+
+// Looks a track up in the user's CURRENT snapshot of the given system
+// variant and returns its pick_kind. Used at play-ingestion time to
+// freeze provenance onto the play_event — snapshots rebuild daily, so
+// attribution can't be reconstructed at read time (#1249/#1270). No
+// row = track not in today's snapshot (caller stores NULL); a row with
+// NULL pick_kind = the variant doesn't stamp (yet). songs_like_artist
+// is non-singleton (up to 3 mixes/user); a track in two of them takes
+// whichever LIMIT 1 hits — acceptable, tier stamps there describe the
+// same eligibility ladder.
+func (q *Queries) GetSystemPickKindForTrack(ctx context.Context, arg GetSystemPickKindForTrackParams) (*string, error) {
+	row := q.db.QueryRow(ctx, getSystemPickKindForTrack, arg.UserID, arg.SystemVariant, arg.TrackID)
+	var pick_kind *string
+	err := row.Scan(&pick_kind)
+	return pick_kind, err
+}
+
 const insertPlayEvent = `-- name: InsertPlayEvent :one
 INSERT INTO play_events (
-    user_id, track_id, session_id, started_at, client_id, source
-) VALUES ($1, $2, $3, $4, $5, $6)
-RETURNING id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source
+    user_id, track_id, session_id, started_at, client_id, source, pick_kind,
+    device_class
+) VALUES ($1, $2, $3, $4, $5, $6, $7::text,
+    $8::text)
+RETURNING id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind, device_class
 `
 
 type InsertPlayEventParams struct {
-	UserID    pgtype.UUID
-	TrackID   pgtype.UUID
-	SessionID pgtype.UUID
-	StartedAt pgtype.Timestamptz
-	ClientID  *string
-	Source    *string
+	UserID      pgtype.UUID
+	TrackID     pgtype.UUID
+	SessionID   pgtype.UUID
+	StartedAt   pgtype.Timestamptz
+	ClientID    *string
+	Source      *string
+	PickKind    *string
+	DeviceClass *string
 }
 
+// pick_kind is non-NULL only for system-playlist plays whose track was
+// found (with a stamped kind) in the user's live snapshot for that
+// variant at ingestion time (#1249, generalized in #1270).
 func (q *Queries) InsertPlayEvent(ctx context.Context, arg InsertPlayEventParams) (PlayEvent, error) {
 	row := q.db.QueryRow(ctx, insertPlayEvent,
 		arg.UserID,
@@ -132,6 +175,8 @@ func (q *Queries) InsertPlayEvent(ctx context.Context, arg InsertPlayEventParams
 		arg.StartedAt,
 		arg.ClientID,
 		arg.Source,
+		arg.PickKind,
+		arg.DeviceClass,
 	)
 	var i PlayEvent
 	err := row.Scan(
@@ -148,6 +193,8 @@ func (q *Queries) InsertPlayEvent(ctx context.Context, arg InsertPlayEventParams
 		&i.SessionVectorAtPlay,
 		&i.ScrobbledAt,
 		&i.Source,
+		&i.PickKind,
+		&i.DeviceClass,
 	)
 	return i, err
 }
@@ -214,7 +261,7 @@ func (q *Queries) InsertSkipEvent(ctx context.Context, arg InsertSkipEventParams
 }
 
 const listRecentSessionTracks = `-- name: ListRecentSessionTracks :many
-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 FROM tracks t
+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, t.tag_source, t.tag_sources_version FROM tracks t
 JOIN play_events pe ON pe.track_id = t.id
 WHERE pe.session_id = $1
   AND pe.started_at < $2
@@ -256,6 +303,8 @@ func (q *Queries) ListRecentSessionTracks(ctx context.Context, arg ListRecentSes
 			&i.Genre,
 			&i.AddedAt,
 			&i.UpdatedAt,
+			&i.TagSource,
+			&i.TagSourcesVersion,
 		); err != nil {
 			return nil, err
 		}
@@ -291,7 +340,7 @@ SET ended_at = $2,
     completion_ratio = $4,
     was_skipped = $5
 WHERE id = $1
-RETURNING id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source
+RETURNING id, user_id, track_id, session_id, started_at, ended_at, duration_played_ms, completion_ratio, was_skipped, client_id, session_vector_at_play, scrobbled_at, source, pick_kind, device_class
 `
 
 type UpdatePlayEventEndedParams struct {
@@ -328,6 +377,8 @@ func (q *Queries) UpdatePlayEventEnded(ctx context.Context, arg UpdatePlayEventE
 		&i.SessionVectorAtPlay,
 		&i.ScrobbledAt,
 		&i.Source,
+		&i.PickKind,
+		&i.DeviceClass,
 	)
 	return i, err
 }

internal/db/dbq/history.sql.go

@@ -14,7 +14,7 @@ import (
 const listUserHistory = `-- name: ListUserHistory :many
 SELECT pe.id           AS event_id,
        pe.started_at,
-       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,
+       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, t.tag_source, t.tag_sources_version,
        albums.title    AS album_title,
        artists.name    AS artist_name
   FROM play_events pe
@@ -77,6 +77,8 @@ func (q *Queries) ListUserHistory(ctx context.Context, arg ListUserHistoryParams
 			&i.Track.Genre,
 			&i.Track.AddedAt,
 			&i.Track.UpdatedAt,
+			&i.Track.TagSource,
+			&i.Track.TagSourcesVersion,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {

internal/db/dbq/likes.sql.go

@@ -259,7 +259,7 @@ func (q *Queries) ListLikedTrackIDs(ctx context.Context, userID pgtype.UUID) ([]
 }
 
 const listLikedTrackRows = `-- name: ListLikedTrackRows :many
-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 FROM tracks t
+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, t.tag_source, t.tag_sources_version FROM tracks t
 JOIN general_likes l ON l.track_id = t.id
 WHERE l.user_id = $1
 ORDER BY l.liked_at DESC
@@ -297,6 +297,8 @@ func (q *Queries) ListLikedTrackRows(ctx context.Context, arg ListLikedTrackRows
 			&i.Genre,
 			&i.AddedAt,
 			&i.UpdatedAt,
+			&i.TagSource,
+			&i.TagSourcesVersion,
 		); err != nil {
 			return nil, err
 		}

internal/db/dbq/models.go

@@ -265,6 +265,18 @@ type CoverArtSourcesMetum struct {
 	LastRegisteredProvidersHash string
 }
 
+type DiagnosticEvent struct {
+	ID         pgtype.UUID
+	UserID     pgtype.UUID
+	ClientID   string
+	AppVersion *string
+	OsVersion  *string
+	Kind       string
+	Payload    []byte
+	OccurredAt pgtype.Timestamptz
+	ReceivedAt pgtype.Timestamptz
+}
+
 type GeneralLike struct {
 	UserID  pgtype.UUID
 	TrackID pgtype.UUID
@@ -371,6 +383,8 @@ type PlayEvent struct {
 	SessionVectorAtPlay []byte
 	ScrobbledAt         pgtype.Timestamptz
 	Source              *string
+	PickKind            *string
+	DeviceClass         *string
 }
 
 type PlaySession struct {
@@ -421,6 +435,29 @@ type PlaylistTrack struct {
 	AlbumTitle  string
 	DurationSec int32
 	AddedAt     pgtype.Timestamptz
+	PickKind    *string
+}
+
+type RecommendationTuningAudit struct {
+	ID        int64
+	ChangedAt pgtype.Timestamptz
+	Scope     string
+	Action    string
+	Changes   []byte
+}
+
+type RecommendationWeightProfile struct {
+	Profile           string
+	BaseWeight        float64
+	LikeBoost         float64
+	RecencyWeight     float64
+	SkipPenalty       float64
+	JitterMagnitude   float64
+	ContextWeight     float64
+	SimilarityWeight  float64
+	TasteWeight       float64
+	UpdatedAt         pgtype.Timestamptz
+	ContextTimeWeight float64
 }
 
 type RegistrationSetting struct {
@@ -497,6 +534,21 @@ type SystemPlaylistRun struct {
 	LastError   *string
 }
 
+type TagProviderSetting struct {
+	ProviderID   string
+	Enabled      bool
+	ApiKey       *string
+	DisplayOrder int32
+	CreatedAt    pgtype.Timestamptz
+	UpdatedAt    pgtype.Timestamptz
+}
+
+type TagSourcesMetum struct {
+	ID                          bool
+	CurrentVersion              int32
+	LastRegisteredProvidersHash string
+}
+
 type TasteProfileArtist struct {
 	UserID    pgtype.UUID
 	ArtistID  pgtype.UUID
@@ -504,6 +556,20 @@ type TasteProfileArtist struct {
 	UpdatedAt pgtype.Timestamptz
 }
 
+type TasteProfileEra struct {
+	UserID    pgtype.UUID
+	Era       string
+	Weight    float64
+	UpdatedAt pgtype.Timestamptz
+}
+
+type TasteProfileMood struct {
+	UserID    pgtype.UUID
+	Mood      string
+	Weight    float64
+	UpdatedAt pgtype.Timestamptz
+}
+
 type TasteProfileTag struct {
 	UserID    pgtype.UUID
 	Tag       string
@@ -511,22 +577,36 @@ type TasteProfileTag struct {
 	UpdatedAt pgtype.Timestamptz
 }
 
+type TasteTuning struct {
+	Singleton          bool
+	HalfLifeDays       float64
+	EngagementHardSkip float64
+	EngagementNeutral  float64
+	EngagementFull     float64
+	UpdatedAt          pgtype.Timestamptz
+	EnrichedTagScale   float64
+	EraScale           float64
+	MoodScale          float64
+}
+
 type Track struct {
-	ID          pgtype.UUID
-	Title       string
-	AlbumID     pgtype.UUID
-	ArtistID    pgtype.UUID
-	TrackNumber *int32
-	DiscNumber  *int32
-	DurationMs  int32
-	FilePath    string
-	FileSize    int64
-	FileFormat  string
-	Bitrate     *int32
-	Mbid        *string
-	Genre       *string
-	AddedAt     pgtype.Timestamptz
-	UpdatedAt   pgtype.Timestamptz
+	ID                pgtype.UUID
+	Title             string
+	AlbumID           pgtype.UUID
+	ArtistID          pgtype.UUID
+	TrackNumber       *int32
+	DiscNumber        *int32
+	DurationMs        int32
+	FilePath          string
+	FileSize          int64
+	FileFormat        string
+	Bitrate           *int32
+	Mbid              *string
+	Genre             *string
+	AddedAt           pgtype.Timestamptz
+	UpdatedAt         pgtype.Timestamptz
+	TagSource         *string
+	TagSourcesVersion int32
 }
 
 type TrackSimilarity struct {
@@ -537,6 +617,12 @@ type TrackSimilarity struct {
 	FetchedAt pgtype.Timestamptz
 }
 
+type TrackTag struct {
+	TrackID pgtype.UUID
+	Tag     string
+	Weight  float64
+}
+
 type User struct {
 	ID                  pgtype.UUID
 	Username            string
@@ -552,6 +638,7 @@ type User struct {
 	Email               *string
 	Timezone            string
 	TimezoneUpdatedAt   pgtype.Timestamptz
+	DebugModeEnabled    bool
 }
 
 type UserInvite struct {

internal/db/dbq/playlists.sql.go

@@ -12,7 +12,7 @@ import (
 )
 
 const appendPlaylistTrack = `-- name: AppendPlaylistTrack :one
-INSERT INTO playlist_tracks (playlist_id, position, track_id, title, artist_name, album_title, duration_sec)
+INSERT INTO playlist_tracks (playlist_id, position, track_id, title, artist_name, album_title, duration_sec, pick_kind)
 SELECT
     $1::uuid,
     COALESCE((SELECT MAX(position) + 1 FROM playlist_tracks WHERE playlist_id = $1::uuid), 0),
@@ -20,24 +20,27 @@ SELECT
     t.title,
     artists.name,
     albums.title,
-    (t.duration_ms / 1000)::integer
+    (t.duration_ms / 1000)::integer,
+    $2::text
 FROM tracks t
 JOIN albums  ON albums.id  = t.album_id
 JOIN artists ON artists.id = t.artist_id
-WHERE t.id = $2::uuid
-RETURNING playlist_id, position, track_id, title, artist_name, album_title, duration_sec, added_at
+WHERE t.id = $3::uuid
+RETURNING playlist_id, position, track_id, title, artist_name, album_title, duration_sec, added_at, pick_kind
 `
 
 type AppendPlaylistTrackParams struct {
 	PlaylistID pgtype.UUID
+	PickKind   *string
 	TrackID    pgtype.UUID
 }
 
 // Inserts at the next available position. Snapshot fields are copied
 // from the tracks/albums/artists join at insert time. tracks.duration_ms
-// is converted to seconds for the snapshot.
+// is converted to seconds for the snapshot. pick_kind is NULL for manual
+// playlists; the For You builder stamps 'taste'/'fresh' (#1249).
 func (q *Queries) AppendPlaylistTrack(ctx context.Context, arg AppendPlaylistTrackParams) (PlaylistTrack, error) {
-	row := q.db.QueryRow(ctx, appendPlaylistTrack, arg.PlaylistID, arg.TrackID)
+	row := q.db.QueryRow(ctx, appendPlaylistTrack, arg.PlaylistID, arg.PickKind, arg.TrackID)
 	var i PlaylistTrack
 	err := row.Scan(
 		&i.PlaylistID,
@@ -48,6 +51,7 @@ func (q *Queries) AppendPlaylistTrack(ctx context.Context, arg AppendPlaylistTra
 		&i.AlbumTitle,
 		&i.DurationSec,
 		&i.AddedAt,
+		&i.PickKind,
 	)
 	return i, err
 }
@@ -257,7 +261,7 @@ func (q *Queries) ListAllPlaylistTracksForCollage(ctx context.Context, arg ListA
 }
 
 const listPlaylistTracks = `-- name: ListPlaylistTracks :many
-SELECT pt.playlist_id, pt.position, pt.track_id, pt.title, pt.artist_name, pt.album_title, pt.duration_sec, pt.added_at,
+SELECT pt.playlist_id, pt.position, pt.track_id, pt.title, pt.artist_name, pt.album_title, pt.duration_sec, pt.added_at, pt.pick_kind,
        t.id           AS live_track_id,
        albums.id      AS album_id,
        artists.id     AS artist_id
@@ -278,6 +282,7 @@ type ListPlaylistTracksRow struct {
 	AlbumTitle  string
 	DurationSec int32
 	AddedAt     pgtype.Timestamptz
+	PickKind    *string
 	LiveTrackID pgtype.UUID
 	AlbumID     pgtype.UUID
 	ArtistID    pgtype.UUID
@@ -305,6 +310,7 @@ func (q *Queries) ListPlaylistTracks(ctx context.Context, playlistID pgtype.UUID
 			&i.AlbumTitle,
 			&i.DurationSec,
 			&i.AddedAt,
+			&i.PickKind,
 			&i.LiveTrackID,
 			&i.AlbumID,
 			&i.ArtistID,

internal/db/dbq/recommendation.sql.go

@@ -11,6 +11,110 @@ import (
 	"github.com/jackc/pgx/v5/pgtype"
 )
 
+const getLatestPlayDeviceClassForUser = `-- name: GetLatestPlayDeviceClassForUser :one
+SELECT device_class
+FROM play_events
+WHERE user_id = $1
+ORDER BY started_at DESC
+LIMIT 1
+`
+
+// The device_class of the user's most recent play (#1551), used as the
+// "current device" for radio context conditioning. NULL when the latest play
+// predates device capture or came from a client that didn't send one.
+func (q *Queries) GetLatestPlayDeviceClassForUser(ctx context.Context, userID pgtype.UUID) (*string, error) {
+	row := q.db.QueryRow(ctx, getLatestPlayDeviceClassForUser, userID)
+	var device_class *string
+	err := row.Scan(&device_class)
+	return device_class, err
+}
+
+const listArtistContextPlayCountsForUser = `-- name: ListArtistContextPlayCountsForUser :many
+WITH tz AS (
+    SELECT COALESCE(NULLIF(u.timezone, ''), 'UTC') AS zone
+    FROM users u WHERE u.id = $1
+),
+now_cell AS (
+    SELECT
+        CASE
+            WHEN EXTRACT(hour FROM now() AT TIME ZONE tz.zone) < 5  THEN 3
+            WHEN EXTRACT(hour FROM now() AT TIME ZONE tz.zone) < 12 THEN 0
+            WHEN EXTRACT(hour FROM now() AT TIME ZONE tz.zone) < 17 THEN 1
+            WHEN EXTRACT(hour FROM now() AT TIME ZONE tz.zone) < 22 THEN 2
+            ELSE 3
+        END AS daypart,
+        (EXTRACT(isodow FROM now() AT TIME ZONE tz.zone) >= 6) AS is_weekend
+    FROM tz
+),
+plays AS (
+    SELECT t.artist_id,
+           pe.device_class,
+           CASE
+               WHEN EXTRACT(hour FROM pe.started_at AT TIME ZONE tz.zone) < 5  THEN 3
+               WHEN EXTRACT(hour FROM pe.started_at AT TIME ZONE tz.zone) < 12 THEN 0
+               WHEN EXTRACT(hour FROM pe.started_at AT TIME ZONE tz.zone) < 17 THEN 1
+               WHEN EXTRACT(hour FROM pe.started_at AT TIME ZONE tz.zone) < 22 THEN 2
+               ELSE 3
+           END AS daypart,
+           (EXTRACT(isodow FROM pe.started_at AT TIME ZONE tz.zone) >= 6) AS is_weekend
+    FROM play_events pe
+    JOIN tracks t ON t.id = pe.track_id
+    CROSS JOIN tz
+    WHERE pe.user_id = $1
+      AND pe.was_skipped = false
+      AND pe.started_at > now() - interval '365 days'
+)
+SELECT p.artist_id,
+       count(*) AS total_plays,
+       count(*) FILTER (
+           WHERE p.daypart = (SELECT daypart FROM now_cell)
+             AND p.is_weekend = (SELECT is_weekend FROM now_cell)
+             AND ($2::text = '' OR p.device_class = $2::text)
+       ) AS cell_plays
+FROM plays p
+GROUP BY p.artist_id
+`
+
+type ListArtistContextPlayCountsForUserParams struct {
+	ID      pgtype.UUID
+	Column2 string
+}
+
+type ListArtistContextPlayCountsForUserRow struct {
+	ArtistID   pgtype.UUID
+	TotalPlays int64
+	CellPlays  int64
+}
+
+// Per-artist completed-play counts split by whether each play falls in the
+// CURRENT context cell, in the user's local timezone (#1531). The cell is
+// daypart × weekday-type, optionally narrowed by device class (#1551): when
+// $2 (the current device) is ”, the device dimension is ignored (identical to
+// the time-only #1531 behaviour, used by the daily mixes which have no device);
+// when $2 is set (radio), a play only counts in the cell if its device_class
+// matches. Feeds the context-affinity scoring term. Skips excluded; a 365-day
+// window bounds cost. Daypart buckets: night [22,5) morning [5,12)
+// afternoon [12,17) evening [17,22). Weekend = ISO days 6–7 (Sat/Sun).
+func (q *Queries) ListArtistContextPlayCountsForUser(ctx context.Context, arg ListArtistContextPlayCountsForUserParams) ([]ListArtistContextPlayCountsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listArtistContextPlayCountsForUser, arg.ID, arg.Column2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListArtistContextPlayCountsForUserRow
+	for rows.Next() {
+		var i ListArtistContextPlayCountsForUserRow
+		if err := rows.Scan(&i.ArtistID, &i.TotalPlays, &i.CellPlays); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
 const listLastPlayedArtistsForUser = `-- name: ListLastPlayedArtistsForUser :many
 WITH user_plays AS (
     SELECT t.artist_id, max(pe.started_at) AS last_started
@@ -104,7 +208,7 @@ WITH plays AS (
     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,
+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, t.tag_source, t.tag_sources_version,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM plays p
@@ -161,6 +265,8 @@ func (q *Queries) ListMostPlayedTracksForArtist(ctx context.Context, arg ListMos
 			&i.Track.Genre,
 			&i.Track.AddedAt,
 			&i.Track.UpdatedAt,
+			&i.Track.TagSource,
+			&i.Track.TagSourcesVersion,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -181,7 +287,7 @@ WITH plays AS (
     WHERE user_id = $1 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,
+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, t.tag_source, t.tag_sources_version,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM plays p
@@ -240,6 +346,8 @@ func (q *Queries) ListMostPlayedTracksForUser(ctx context.Context, arg ListMostP
 			&i.Track.Genre,
 			&i.Track.AddedAt,
 			&i.Track.UpdatedAt,
+			&i.Track.TagSource,
+			&i.Track.TagSourcesVersion,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -577,12 +685,14 @@ func (q *Queries) ListRediscoverArtistsForUser(ctx context.Context, arg ListRedi
 
 const loadRadioCandidates = `-- name: LoadRadioCandidates :many
 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,
+    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, t.tag_source, t.tag_sources_version,
     (l.user_id IS NOT NULL)::bool AS is_liked,
     pe.last_played_at::timestamptz AS last_played_at,
     pe.play_count,
-    pe.skip_count
+    pe.skip_count,
+    al.release_date AS release_date
 FROM tracks t
+JOIN albums al ON al.id = t.album_id
 LEFT JOIN general_likes l ON l.user_id = $1 AND l.track_id = t.id
 LEFT JOIN LATERAL (
     SELECT
@@ -616,6 +726,7 @@ type LoadRadioCandidatesRow struct {
 	LastPlayedAt pgtype.Timestamptz
 	PlayCount    int64
 	SkipCount    int64
+	ReleaseDate  pgtype.Date
 }
 
 // Returns all tracks except the seed and any played by the user within
@@ -650,10 +761,13 @@ func (q *Queries) LoadRadioCandidates(ctx context.Context, arg LoadRadioCandidat
 			&i.Track.Genre,
 			&i.Track.AddedAt,
 			&i.Track.UpdatedAt,
+			&i.Track.TagSource,
+			&i.Track.TagSourcesVersion,
 			&i.IsLiked,
 			&i.LastPlayedAt,
 			&i.PlayCount,
 			&i.SkipCount,
+			&i.ReleaseDate,
 		); err != nil {
 			return nil, err
 		}
@@ -748,6 +862,22 @@ taste_overlap AS (
     ORDER BY tpa.weight DESC, t.id
     LIMIT $10
 ),
+coplay_artists AS (
+    -- Household co-play (#1533): tracks by artists co-played across the
+    -- instance with the seed's artist (source='user_cooccurrence', built by
+    -- the coplay worker). Mirrors similar_artists but from local co-occurrence
+    -- instead of ListenBrainz; empty on single-user servers. Same 0.5 damp as
+    -- similar_artists since it's artist-level.
+    SELECT t.id AS track_id, asim.score * 0.5 AS sim_score
+    FROM artist_similarity asim
+    JOIN tracks t ON t.artist_id = asim.artist_b_id
+    JOIN seed_artist sa ON asim.artist_a_id = sa.artist_id
+    WHERE asim.source = 'user_cooccurrence'
+      AND t.id NOT IN (SELECT id FROM excluded_ids)
+      AND t.id <> $2
+    ORDER BY asim.score DESC, random()
+    LIMIT $11
+),
 random_fill AS (
     SELECT t.id AS track_id, 0.0::float8 AS sim_score
     FROM tracks t
@@ -759,16 +889,18 @@ random_fill AS (
           UNION SELECT track_id FROM tag_overlap
           UNION SELECT track_id FROM likes_overlap
           UNION SELECT track_id FROM taste_overlap
+          UNION SELECT track_id FROM coplay_artists
       )
     ORDER BY random()
     LIMIT $9
 )
 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,
+    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, t.tag_source, t.tag_sources_version,
     (l.user_id IS NOT NULL)::bool AS is_liked,
     pe.last_played_at::timestamptz AS last_played_at,
     pe.play_count,
     pe.skip_count,
+    al.release_date AS release_date,
     COALESCE(max(u.sim_score), 0.0) AS similarity_score
 FROM (
     SELECT track_id, sim_score FROM lb_similar
@@ -776,9 +908,11 @@ FROM (
     UNION ALL SELECT track_id, sim_score FROM tag_overlap
     UNION ALL SELECT track_id, sim_score FROM likes_overlap
     UNION ALL SELECT track_id, sim_score FROM taste_overlap
+    UNION ALL SELECT track_id, sim_score FROM coplay_artists
     UNION ALL SELECT track_id, sim_score FROM random_fill
 ) u
 JOIN tracks t ON t.id = u.track_id
+JOIN albums al ON al.id = t.album_id
 LEFT JOIN general_likes l ON l.user_id = $1 AND l.track_id = t.id
 LEFT JOIN LATERAL (
     SELECT max(started_at) AS last_played_at,
@@ -790,7 +924,8 @@ LEFT JOIN LATERAL (
 GROUP BY t.id, t.title, t.album_id, t.artist_id, t.duration_ms, t.file_path,
          t.file_format, t.file_size, t.bitrate, t.track_number, t.disc_number,
          t.mbid, t.genre, t.added_at, t.updated_at,
-         l.user_id, pe.last_played_at, pe.play_count, pe.skip_count
+         l.user_id, pe.last_played_at, pe.play_count, pe.skip_count,
+         al.release_date
 `
 
 type LoadRadioCandidatesV2Params struct {
@@ -804,6 +939,7 @@ type LoadRadioCandidatesV2Params struct {
 	Limit_4 int32
 	Limit_5 int32
 	Limit_6 int32
+	Limit_7 int32
 }
 
 type LoadRadioCandidatesV2Row struct {
@@ -812,6 +948,7 @@ type LoadRadioCandidatesV2Row struct {
 	LastPlayedAt    pgtype.Timestamptz
 	PlayCount       int64
 	SkipCount       int64
+	ReleaseDate     pgtype.Date
 	SimilarityScore interface{}
 }
 
@@ -823,7 +960,9 @@ type LoadRadioCandidatesV2Row struct {
 //	$10 taste_overlap K (#796 phase 2b — tracks by the user's top
 //	positively-weighted taste-profile artists, so taste-relevant tracks
 //	enter the pool even when the similarity/random arms miss them; scored
-//	in Go via TasteMatch, so sim_score here is 0 pool-inclusion).
+//	in Go via TasteMatch, so sim_score here is 0 pool-inclusion),
+//	$11 coplay_artists K (#1533 — tracks by artists co-played across the
+//	instance with the seed's artist; source='user_cooccurrence').
 //
 // Returns same shape as LoadRadioCandidates plus similarity_score column.
 func (q *Queries) LoadRadioCandidatesV2(ctx context.Context, arg LoadRadioCandidatesV2Params) ([]LoadRadioCandidatesV2Row, error) {
@@ -838,6 +977,7 @@ func (q *Queries) LoadRadioCandidatesV2(ctx context.Context, arg LoadRadioCandid
 		arg.Limit_4,
 		arg.Limit_5,
 		arg.Limit_6,
+		arg.Limit_7,
 	)
 	if err != nil {
 		return nil, err
@@ -862,10 +1002,13 @@ func (q *Queries) LoadRadioCandidatesV2(ctx context.Context, arg LoadRadioCandid
 			&i.Track.Genre,
 			&i.Track.AddedAt,
 			&i.Track.UpdatedAt,
+			&i.Track.TagSource,
+			&i.Track.TagSourcesVersion,
 			&i.IsLiked,
 			&i.LastPlayedAt,
 			&i.PlayCount,
 			&i.SkipCount,
+			&i.ReleaseDate,
 			&i.SimilarityScore,
 		); err != nil {
 			return nil, err

internal/db/dbq/recommendation_metrics.sql.go

@@ -12,19 +12,17 @@ import (
 )
 
 const recommendationSourceMetricsForUser = `-- name: RecommendationSourceMetricsForUser :many
-
 SELECT
     pe.source,
+    pe.pick_kind,
     count(*)::bigint AS plays,
     count(*) FILTER (WHERE pe.was_skipped)::bigint AS skips,
-    COALESCE(
-        avg(pe.completion_ratio) FILTER (WHERE pe.completion_ratio IS NOT NULL),
-        0)::float8 AS avg_completion
+    count(pe.completion_ratio)::bigint AS completion_n,
+    COALESCE(avg(pe.completion_ratio), 0)::float8 AS avg_completion
 FROM play_events pe
 WHERE pe.user_id = $1
-  AND pe.source IS NOT NULL
   AND pe.started_at > now() - ($2::float8 * INTERVAL '1 day')
-GROUP BY pe.source
+GROUP BY pe.source, pe.pick_kind
 ORDER BY plays DESC
 `
 
@@ -35,18 +33,17 @@ type RecommendationSourceMetricsForUserParams struct {
 
 type RecommendationSourceMetricsForUserRow struct {
 	Source        *string
+	PickKind      *string
 	Plays         int64
 	Skips         int64
+	CompletionN   int64
 	AvgCompletion float64
 }
 
-// Recommendation observability (#796 phase 4). Per-source play outcomes so the
-// operator can see whether each recommendation surface is landing and tune the
-// taste weights. Source is stamped on play_events when a play is launched from
-// a system-playlist surface ('for_you' | 'discover' | the discovery mixes);
-// NULL for library / radio / user-playlist plays, which are excluded here.
 // $1 user_id, $2 window_days. plays/skips are counts; avg_completion is the
-// mean completion ratio over plays that recorded one (0 when none did).
+// mean completion ratio over the completion_n plays that recorded one.
+// pick_kind splits For You plays into taste/fresh/unattributed (#1249);
+// it is NULL for every other source, so those still group to one row.
 func (q *Queries) RecommendationSourceMetricsForUser(ctx context.Context, arg RecommendationSourceMetricsForUserParams) ([]RecommendationSourceMetricsForUserRow, error) {
 	rows, err := q.db.Query(ctx, recommendationSourceMetricsForUser, arg.UserID, arg.Column2)
 	if err != nil {
@@ -58,8 +55,10 @@ func (q *Queries) RecommendationSourceMetricsForUser(ctx context.Context, arg Re
 		var i RecommendationSourceMetricsForUserRow
 		if err := rows.Scan(
 			&i.Source,
+			&i.PickKind,
 			&i.Plays,
 			&i.Skips,
+			&i.CompletionN,
 			&i.AvgCompletion,
 		); err != nil {
 			return nil, err
@@ -71,3 +70,83 @@ func (q *Queries) RecommendationSourceMetricsForUser(ctx context.Context, arg Re
 	}
 	return items, nil
 }
+
+const recommendationWeeklyTrends = `-- name: RecommendationWeeklyTrends :many
+
+SELECT
+    date_trunc('week', pe.started_at)::date AS week_start,
+    pe.source,
+    count(*)::bigint AS plays,
+    count(*) FILTER (WHERE pe.was_skipped)::bigint AS skips,
+    count(pe.completion_ratio)::bigint AS completion_n,
+    COALESCE(avg(pe.completion_ratio), 0)::float8 AS avg_completion,
+    count(*) FILTER (WHERE tpa.artist_id IS NOT NULL)::bigint AS taste_hits
+FROM play_events pe
+JOIN tracks t ON t.id = pe.track_id
+LEFT JOIN taste_profile_artists tpa
+       ON tpa.user_id = pe.user_id
+      AND tpa.artist_id = t.artist_id
+      AND tpa.weight > 0
+WHERE pe.started_at > now() - ($1::int * INTERVAL '1 week')
+GROUP BY 1, 2
+ORDER BY 1, 2
+`
+
+type RecommendationWeeklyTrendsRow struct {
+	WeekStart     pgtype.Date
+	Source        *string
+	Plays         int64
+	Skips         int64
+	CompletionN   int64
+	AvgCompletion float64
+	TasteHits     int64
+}
+
+// Recommendation observability (#796 phase 4). Per-source play outcomes so the
+// operator can see whether each recommendation surface is landing and tune the
+// taste weights. Source is stamped on play_events when a play is launched from
+// a recommendation surface; NULL means the user picked the track manually —
+// those rows are INCLUDED here as the baseline control group the surfaces are
+// judged against (milestone #127: delta-vs-baseline is what makes the numbers
+// actionable). Raw source strings are bucketed into stable surface families in
+// the Go handler; completion_n is carried so family merges can weight
+// avg_completion correctly.
+// Weekly per-source outcome series for the tuning lab's trend view
+// (#1251). Aggregated across ALL users: the tuning knobs are global,
+// so judging a knob turn needs global outcomes — rows carry rates
+// only, no track or user identity. NULL-source (manual) rows are
+// included as the baseline family.
+//
+// taste_hits counts plays whose track's artist has a positive weight
+// in that user's CURRENT taste profile — the "cheap recompute" option:
+// retroactive over the whole window, at the cost of drift (the profile
+// is today's, the play may be weeks old). Good enough to read whether
+// a surface is feeding taste-fitting tracks.
+// $1 window in weeks.
+func (q *Queries) RecommendationWeeklyTrends(ctx context.Context, weeks int32) ([]RecommendationWeeklyTrendsRow, error) {
+	rows, err := q.db.Query(ctx, recommendationWeeklyTrends, weeks)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []RecommendationWeeklyTrendsRow
+	for rows.Next() {
+		var i RecommendationWeeklyTrendsRow
+		if err := rows.Scan(
+			&i.WeekStart,
+			&i.Source,
+			&i.Plays,
+			&i.Skips,
+			&i.CompletionN,
+			&i.AvgCompletion,
+			&i.TasteHits,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}

internal/db/dbq/recommendation_tuning.sql.go

@@ -0,0 +1,302 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: recommendation_tuning.sql
+
+package dbq
+
+import (
+	"context"
+)
+
+const getTasteTuning = `-- name: GetTasteTuning :one
+SELECT singleton, half_life_days, engagement_hard_skip, engagement_neutral, engagement_full, updated_at, enriched_tag_scale, era_scale, mood_scale FROM taste_tuning WHERE singleton = true
+`
+
+func (q *Queries) GetTasteTuning(ctx context.Context) (TasteTuning, error) {
+	row := q.db.QueryRow(ctx, getTasteTuning)
+	var i TasteTuning
+	err := row.Scan(
+		&i.Singleton,
+		&i.HalfLifeDays,
+		&i.EngagementHardSkip,
+		&i.EngagementNeutral,
+		&i.EngagementFull,
+		&i.UpdatedAt,
+		&i.EnrichedTagScale,
+		&i.EraScale,
+		&i.MoodScale,
+	)
+	return i, err
+}
+
+const insertTuningAudit = `-- name: InsertTuningAudit :exec
+INSERT INTO recommendation_tuning_audit (scope, action, changes)
+VALUES ($1, $2, $3)
+`
+
+type InsertTuningAuditParams struct {
+	Scope   string
+	Action  string
+	Changes []byte
+}
+
+// changes is a jsonb array of {field, old, new} objects.
+func (q *Queries) InsertTuningAudit(ctx context.Context, arg InsertTuningAuditParams) error {
+	_, err := q.db.Exec(ctx, insertTuningAudit, arg.Scope, arg.Action, arg.Changes)
+	return err
+}
+
+const listTuningAudit = `-- name: ListTuningAudit :many
+SELECT id, changed_at, scope, action, changes
+  FROM recommendation_tuning_audit
+ ORDER BY changed_at DESC, id DESC
+ LIMIT $1
+`
+
+// Newest first; consumed by the metrics trend view (#1251) to annotate
+// knob turns on the timeline.
+func (q *Queries) ListTuningAudit(ctx context.Context, limit int32) ([]RecommendationTuningAudit, error) {
+	rows, err := q.db.Query(ctx, listTuningAudit, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []RecommendationTuningAudit
+	for rows.Next() {
+		var i RecommendationTuningAudit
+		if err := rows.Scan(
+			&i.ID,
+			&i.ChangedAt,
+			&i.Scope,
+			&i.Action,
+			&i.Changes,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listWeightProfiles = `-- name: ListWeightProfiles :many
+SELECT profile, base_weight, like_boost, recency_weight, skip_penalty, jitter_magnitude, context_weight, similarity_weight, taste_weight, updated_at, context_time_weight FROM recommendation_weight_profiles ORDER BY profile
+`
+
+func (q *Queries) ListWeightProfiles(ctx context.Context) ([]RecommendationWeightProfile, error) {
+	rows, err := q.db.Query(ctx, listWeightProfiles)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []RecommendationWeightProfile
+	for rows.Next() {
+		var i RecommendationWeightProfile
+		if err := rows.Scan(
+			&i.Profile,
+			&i.BaseWeight,
+			&i.LikeBoost,
+			&i.RecencyWeight,
+			&i.SkipPenalty,
+			&i.JitterMagnitude,
+			&i.ContextWeight,
+			&i.SimilarityWeight,
+			&i.TasteWeight,
+			&i.UpdatedAt,
+			&i.ContextTimeWeight,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const updateTasteTuning = `-- name: UpdateTasteTuning :one
+UPDATE taste_tuning
+   SET half_life_days       = $1,
+       engagement_hard_skip = $2,
+       engagement_neutral   = $3,
+       engagement_full      = $4,
+       enriched_tag_scale   = $5,
+       era_scale            = $6,
+       mood_scale           = $7,
+       updated_at           = now()
+ WHERE singleton = true
+RETURNING singleton, half_life_days, engagement_hard_skip, engagement_neutral, engagement_full, updated_at, enriched_tag_scale, era_scale, mood_scale
+`
+
+type UpdateTasteTuningParams struct {
+	HalfLifeDays       float64
+	EngagementHardSkip float64
+	EngagementNeutral  float64
+	EngagementFull     float64
+	EnrichedTagScale   float64
+	EraScale           float64
+	MoodScale          float64
+}
+
+func (q *Queries) UpdateTasteTuning(ctx context.Context, arg UpdateTasteTuningParams) (TasteTuning, error) {
+	row := q.db.QueryRow(ctx, updateTasteTuning,
+		arg.HalfLifeDays,
+		arg.EngagementHardSkip,
+		arg.EngagementNeutral,
+		arg.EngagementFull,
+		arg.EnrichedTagScale,
+		arg.EraScale,
+		arg.MoodScale,
+	)
+	var i TasteTuning
+	err := row.Scan(
+		&i.Singleton,
+		&i.HalfLifeDays,
+		&i.EngagementHardSkip,
+		&i.EngagementNeutral,
+		&i.EngagementFull,
+		&i.UpdatedAt,
+		&i.EnrichedTagScale,
+		&i.EraScale,
+		&i.MoodScale,
+	)
+	return i, err
+}
+
+const updateWeightProfile = `-- name: UpdateWeightProfile :one
+UPDATE recommendation_weight_profiles
+   SET base_weight         = $2,
+       like_boost          = $3,
+       recency_weight      = $4,
+       skip_penalty        = $5,
+       jitter_magnitude    = $6,
+       context_weight      = $7,
+       similarity_weight   = $8,
+       taste_weight        = $9,
+       context_time_weight = $10,
+       updated_at          = now()
+ WHERE profile = $1
+RETURNING profile, base_weight, like_boost, recency_weight, skip_penalty, jitter_magnitude, context_weight, similarity_weight, taste_weight, updated_at, context_time_weight
+`
+
+type UpdateWeightProfileParams struct {
+	Profile           string
+	BaseWeight        float64
+	LikeBoost         float64
+	RecencyWeight     float64
+	SkipPenalty       float64
+	JitterMagnitude   float64
+	ContextWeight     float64
+	SimilarityWeight  float64
+	TasteWeight       float64
+	ContextTimeWeight float64
+}
+
+func (q *Queries) UpdateWeightProfile(ctx context.Context, arg UpdateWeightProfileParams) (RecommendationWeightProfile, error) {
+	row := q.db.QueryRow(ctx, updateWeightProfile,
+		arg.Profile,
+		arg.BaseWeight,
+		arg.LikeBoost,
+		arg.RecencyWeight,
+		arg.SkipPenalty,
+		arg.JitterMagnitude,
+		arg.ContextWeight,
+		arg.SimilarityWeight,
+		arg.TasteWeight,
+		arg.ContextTimeWeight,
+	)
+	var i RecommendationWeightProfile
+	err := row.Scan(
+		&i.Profile,
+		&i.BaseWeight,
+		&i.LikeBoost,
+		&i.RecencyWeight,
+		&i.SkipPenalty,
+		&i.JitterMagnitude,
+		&i.ContextWeight,
+		&i.SimilarityWeight,
+		&i.TasteWeight,
+		&i.UpdatedAt,
+		&i.ContextTimeWeight,
+	)
+	return i, err
+}
+
+const upsertTasteTuningDefaults = `-- name: UpsertTasteTuningDefaults :exec
+INSERT INTO taste_tuning (
+    singleton, half_life_days, engagement_hard_skip,
+    engagement_neutral, engagement_full, enriched_tag_scale, era_scale,
+    mood_scale
+) VALUES (true, $1, $2, $3, $4, $5, $6, $7)
+ON CONFLICT (singleton) DO NOTHING
+`
+
+type UpsertTasteTuningDefaultsParams struct {
+	HalfLifeDays       float64
+	EngagementHardSkip float64
+	EngagementNeutral  float64
+	EngagementFull     float64
+	EnrichedTagScale   float64
+	EraScale           float64
+	MoodScale          float64
+}
+
+func (q *Queries) UpsertTasteTuningDefaults(ctx context.Context, arg UpsertTasteTuningDefaultsParams) error {
+	_, err := q.db.Exec(ctx, upsertTasteTuningDefaults,
+		arg.HalfLifeDays,
+		arg.EngagementHardSkip,
+		arg.EngagementNeutral,
+		arg.EngagementFull,
+		arg.EnrichedTagScale,
+		arg.EraScale,
+		arg.MoodScale,
+	)
+	return err
+}
+
+const upsertWeightProfileDefaults = `-- name: UpsertWeightProfileDefaults :exec
+
+INSERT INTO recommendation_weight_profiles (
+    profile, base_weight, like_boost, recency_weight, skip_penalty,
+    jitter_magnitude, context_weight, similarity_weight, taste_weight,
+    context_time_weight
+) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+ON CONFLICT (profile) DO NOTHING
+`
+
+type UpsertWeightProfileDefaultsParams struct {
+	Profile           string
+	BaseWeight        float64
+	LikeBoost         float64
+	RecencyWeight     float64
+	SkipPenalty       float64
+	JitterMagnitude   float64
+	ContextWeight     float64
+	SimilarityWeight  float64
+	TasteWeight       float64
+	ContextTimeWeight float64
+}
+
+// Recommendation tuning lab queries (#1250). Seeding happens via the
+// recsettings boot reconcile; shipped defaults live in Go only.
+// Boot reconcile: insert the shipped defaults for a profile if the row
+// doesn't exist yet. Never overwrites operator-tuned values.
+func (q *Queries) UpsertWeightProfileDefaults(ctx context.Context, arg UpsertWeightProfileDefaultsParams) error {
+	_, err := q.db.Exec(ctx, upsertWeightProfileDefaults,
+		arg.Profile,
+		arg.BaseWeight,
+		arg.LikeBoost,
+		arg.RecencyWeight,
+		arg.SkipPenalty,
+		arg.JitterMagnitude,
+		arg.ContextWeight,
+		arg.SimilarityWeight,
+		arg.TasteWeight,
+		arg.ContextTimeWeight,
+	)
+	return err
+}

internal/db/dbq/system_mixes.sql.go

@@ -27,12 +27,20 @@ play_counts AS (
       FROM play_events
      WHERE user_id = $1 AND was_skipped = false
      GROUP BY track_id
+),
+skip_counts AS (
+    SELECT track_id, COUNT(*) AS c
+      FROM play_events
+     WHERE user_id = $1 AND was_skipped = true
+     GROUP BY track_id
 )
 SELECT t.id, t.album_id, t.artist_id
   FROM tracks t
   JOIN affinity_artists aa ON aa.artist_id = t.artist_id
   LEFT JOIN play_counts pc ON pc.track_id = t.id
+  LEFT JOIN skip_counts sc ON sc.track_id = t.id
  WHERE COALESCE(pc.c, 0) <= 2
+   AND COALESCE(sc.c, 0) < 2
    AND NOT EXISTS (
        SELECT 1 FROM lidarr_quarantine q
         WHERE q.user_id = $1 AND q.track_id = t.id
@@ -60,6 +68,11 @@ type ListDeepCutsTracksRow struct {
 // gives per-play variety on top.
 // #419 Deep Cuts: low-play tracks (<=2 plays) from artists the user
 // has liked OR played heavily (>=5 non-skip plays across the artist).
+// Tracks the user has skipped twice or more don't qualify (#1257):
+// eligibility used to count only unskipped plays, so the most actively
+// rejected tracks read as "barely heard" and kept being re-offered.
+// Threshold 2 so a single accidental skip doesn't banish a track;
+// passive-signal only (no dislike UI, rule #101).
 // $1 user_id, $2 date string.
 func (q *Queries) ListDeepCutsTracks(ctx context.Context, arg ListDeepCutsTracksParams) ([]ListDeepCutsTracksRow, error) {
 	rows, err := q.db.Query(ctx, listDeepCutsTracks, arg.UserID, arg.Column2)
@@ -82,31 +95,49 @@ func (q *Queries) ListDeepCutsTracks(ctx context.Context, arg ListDeepCutsTracks
 }
 
 const listFirstListensTracks = `-- name: ListFirstListensTracks :many
-WITH heard_albums AS (
-    SELECT DISTINCT t.album_id
-      FROM play_events pe JOIN tracks t ON t.id = pe.track_id
-     WHERE pe.user_id = $1
+WITH attempted AS (
+    SELECT DISTINCT pe.track_id
+      FROM play_events pe
+     WHERE pe.user_id = $1 AND pe.duration_played_ms >= 30000
 ),
-played_artists AS (
+album_attempts AS (
+    SELECT t.album_id,
+           COUNT(a.track_id) AS attempted_count,
+           COUNT(*) AS track_count
+      FROM tracks t
+      LEFT JOIN attempted a ON a.track_id = t.id
+     GROUP BY t.album_id
+),
+attempted_artists AS (
     SELECT DISTINCT t.artist_id
-      FROM play_events pe JOIN tracks t ON t.id = pe.track_id
-     WHERE pe.user_id = $1
+      FROM attempted a JOIN tracks t ON t.id = a.track_id
+),
+albums_tiered AS (
+    SELECT aa.album_id,
+           CASE
+             WHEN aa.attempted_count = 0 THEN 1
+             WHEN aa.attempted_count::float / GREATEST(aa.track_count, 1) <= 0.25 THEN 2
+           END AS tier
+      FROM album_attempts aa
 )
-SELECT t.id, t.album_id, t.artist_id
+SELECT t.id, t.album_id, t.artist_id, alt.tier::int AS tier
   FROM tracks t
   JOIN albums al ON al.id = t.album_id
- WHERE NOT EXISTS (SELECT 1 FROM heard_albums h WHERE h.album_id = al.id)
+  JOIN albums_tiered alt ON alt.album_id = al.id
+ WHERE alt.tier IS NOT NULL
+   AND NOT EXISTS (SELECT 1 FROM attempted a WHERE a.track_id = t.id)
    AND NOT EXISTS (
        SELECT 1 FROM lidarr_quarantine q
         WHERE q.user_id = $1 AND q.track_id = t.id
    )
  ORDER BY
+   alt.tier,
    (CASE
       WHEN EXISTS (
         SELECT 1 FROM general_likes_artists gla
          WHERE gla.user_id = $1 AND gla.artist_id = al.artist_id
       ) THEN 0
-      WHEN al.artist_id IN (SELECT artist_id FROM played_artists) THEN 1
+      WHEN al.artist_id IN (SELECT artist_id FROM attempted_artists) THEN 1
       ELSE 2
     END),
    al.id, t.disc_number NULLS FIRST, t.track_number NULLS FIRST
@@ -117,12 +148,25 @@ type ListFirstListensTracksRow struct {
 	ID       pgtype.UUID
 	AlbumID  pgtype.UUID
 	ArtistID pgtype.UUID
+	Tier     int32
 }
 
-// #423 First Listens: albums the user has never played any track of.
-// Tiered: liked-artist albums first, then played-artist albums, then
-// the rest — album-coherent within each tier. Not diversity-capped
-// (whole-album discovery). $1 user_id.
+// #423 First Listens: songs the user has never heard or even
+// attempted. "Attempted" is track-level with a >=30s listen threshold
+// (#1268, operator decision 2026-07-03) — the old version disqualified
+// a whole album on ANY play_event, so a 2-second accidental brush
+// banished it permanently.
+//
+//	tier 1  the exact desire: albums with ZERO attempted tracks
+//	tier 2  step back: barely-attempted albums (<=25% of tracks
+//	        reached 30s) — brushed, never explored. The already-
+//	        attempted tracks themselves are excluded; they're not
+//	        first listens.
+//
+// Within each tier, affinity-ordered as before: liked artist, then
+// attempted-played artist (>=30s — skip-only contact isn't trust),
+// then the rest; album-coherent. The tier lands on
+// playlist_tracks.pick_kind via the producer. $1 user_id.
 func (q *Queries) ListFirstListensTracks(ctx context.Context, userID pgtype.UUID) ([]ListFirstListensTracksRow, error) {
 	rows, err := q.db.Query(ctx, listFirstListensTracks, userID)
 	if err != nil {
@@ -132,7 +176,12 @@ func (q *Queries) ListFirstListensTracks(ctx context.Context, userID pgtype.UUID
 	var items []ListFirstListensTracksRow
 	for rows.Next() {
 		var i ListFirstListensTracksRow
-		if err := rows.Scan(&i.ID, &i.AlbumID, &i.ArtistID); err != nil {
+		if err := rows.Scan(
+			&i.ID,
+			&i.AlbumID,
+			&i.ArtistID,
+			&i.Tier,
+		); err != nil {
 			return nil, err
 		}
 		items = append(items, i)
@@ -144,39 +193,76 @@ func (q *Queries) ListFirstListensTracks(ctx context.Context, userID pgtype.UUID
 }
 
 const listNewForYouTracks = `-- name: ListNewForYouTracks :many
-WITH affinity_artists AS (
-    SELECT artist_id FROM general_likes_artists WHERE user_id = $1
+WITH attempted AS (
+    SELECT DISTINCT pe.track_id
+      FROM play_events pe
+     WHERE pe.user_id = $1 AND pe.duration_played_ms >= 30000
+),
+consumed_albums AS (
+    SELECT DISTINCT t.album_id
+      FROM attempted a JOIN tracks t ON t.id = a.track_id
+),
+affinity_artists AS (
+    SELECT gla.artist_id FROM general_likes_artists gla WHERE gla.user_id = $1
     UNION
     SELECT t.artist_id
-      FROM play_events pe JOIN tracks t ON t.id = pe.track_id
-     WHERE pe.user_id = $1 AND pe.was_skipped = false
+      FROM attempted a JOIN tracks t ON t.id = a.track_id
      GROUP BY t.artist_id
     HAVING COUNT(*) >= 3
+),
+albums_tiered AS (
+    SELECT al.id AS album_id, al.created_at,
+           CASE
+             WHEN al.created_at >= now() - interval '30 days'
+                  AND al.artist_id IN (SELECT artist_id FROM affinity_artists) THEN 1
+             WHEN al.artist_id IN (SELECT artist_id FROM affinity_artists) THEN 2
+             ELSE 3
+           END AS tier
+      FROM albums al
+     WHERE al.created_at >= now() - interval '90 days'
+       AND al.id NOT IN (SELECT album_id FROM consumed_albums)
 )
-SELECT t.id, t.album_id, t.artist_id
+SELECT t.id, t.album_id, t.artist_id, alt.tier::int AS tier
   FROM tracks t
-  JOIN albums al ON al.id = t.album_id
-  JOIN affinity_artists aa ON aa.artist_id = al.artist_id
- WHERE al.created_at >= now() - interval '30 days'
-   AND NOT EXISTS (
+  JOIN albums_tiered alt ON alt.album_id = t.album_id
+ WHERE NOT EXISTS (
        SELECT 1 FROM lidarr_quarantine q
         WHERE q.user_id = $1 AND q.track_id = t.id
    )
- ORDER BY al.created_at DESC, t.disc_number NULLS FIRST, t.track_number NULLS FIRST
- LIMIT 200
+ ORDER BY alt.tier, alt.created_at DESC, t.album_id,
+          t.disc_number NULLS FIRST, t.track_number NULLS FIRST
+ LIMIT 300
 `
 
 type ListNewForYouTracksRow struct {
 	ID       pgtype.UUID
 	AlbumID  pgtype.UUID
 	ArtistID pgtype.UUID
+	Tier     int32
 }
 
-// #421 New for you: tracks from albums added in the last 30 days
-// whose artist the user has liked OR played (>=3 non-skip). Album-
-// coherent (newest album first, then disc/track) — the producer does
-// NOT diversity-cap these; they're meant as whole-album discovery.
-// $1 user_id.
+// #421 New for you, tiered per project rule #131 (#1267). The old
+// single hard rule (added <30d AND direct affinity) had two failure
+// modes with one root: no notion of consumption — the album you
+// devoured in week one crowded the mix for three more weeks, and
+// after a quiet month nothing qualified at all.
+//
+// "Consumed" = any track attempted for >=30s (the First Listens
+// threshold, #1268): once you've meaningfully engaged, the album is
+// no longer news. Applies to every tier — played albums leave the
+// mix the next build.
+//
+//	tier 1  the exact desire: unconsumed albums added <30d by
+//	        direct-affinity artists (liked, or >=3 attempted plays)
+//	tier 2  step back a little: unconsumed affinity albums from the
+//	        wider 30-90d window — added while you weren't looking
+//	tier 3  step back more: any unconsumed album added <90d
+//	        regardless of affinity, newest first
+//
+// Album-coherent within tiers (newest album first, then disc/track);
+// the producer fills top-down and rotates within tier blocks. The
+// tier lands on playlist_tracks.pick_kind so metrics can price what
+// each step-back trades away. $1 user_id.
 func (q *Queries) ListNewForYouTracks(ctx context.Context, userID pgtype.UUID) ([]ListNewForYouTracksRow, error) {
 	rows, err := q.db.Query(ctx, listNewForYouTracks, userID)
 	if err != nil {
@@ -186,7 +272,12 @@ func (q *Queries) ListNewForYouTracks(ctx context.Context, userID pgtype.UUID) (
 	var items []ListNewForYouTracksRow
 	for rows.Next() {
 		var i ListNewForYouTracksRow
-		if err := rows.Scan(&i.ID, &i.AlbumID, &i.ArtistID); err != nil {
+		if err := rows.Scan(
+			&i.ID,
+			&i.AlbumID,
+			&i.ArtistID,
+			&i.Tier,
+		); err != nil {
 			return nil, err
 		}
 		items = append(items, i)
@@ -203,7 +294,10 @@ WITH windowed AS (
       FROM play_events
      WHERE user_id = $1 AND was_skipped = false
        AND started_at < now() - interval '30 days'
-       AND ABS(EXTRACT(DOY FROM started_at) - EXTRACT(DOY FROM now())) <= 10
+       AND LEAST(
+           ABS(EXTRACT(DOY FROM started_at) - EXTRACT(DOY FROM $2::date)),
+           365 - ABS(EXTRACT(DOY FROM started_at) - EXTRACT(DOY FROM $2::date))
+       ) <= 10
      GROUP BY track_id
 )
 SELECT t.id, t.album_id, t.artist_id
@@ -235,6 +329,13 @@ type ListOnThisDayTracksRow struct {
 // and window ±7→±10 so it surfaces on a months-old library instead
 // of needing a full year of history; still skips cleanly (no rows →
 // no playlist) when there's no qualifying history yet.
+// Day-of-year distance is circular (#1256): plain ABS made Dec 28 vs
+// Jan 3 read as 359 days apart, silently gutting the window for ~3
+// weeks around every New Year — precisely when holiday nostalgia is
+// the point. LEAST(d, 365-d) wraps the boundary; leap-year drift of
+// ±1 is absorbed by the ±10 window. The build date ($2, already here
+// for the md5 rotation) anchors "today" instead of now() so the
+// window is testable and consistent with the mix's daily determinism.
 // $1 user_id, $2 date string.
 func (q *Queries) ListOnThisDayTracks(ctx context.Context, arg ListOnThisDayTracksParams) ([]ListOnThisDayTracksRow, error) {
 	rows, err := q.db.Query(ctx, listOnThisDayTracks, arg.UserID, arg.Column2)
@@ -262,37 +363,32 @@ WITH stats AS (
       FROM play_events pe
      WHERE pe.user_id = $1 AND pe.was_skipped = false
      GROUP BY pe.track_id
-),
-deep AS (
-    SELECT t.id, t.album_id, t.artist_id, s.c, 0 AS tier
-      FROM tracks t
-      JOIN stats s ON s.track_id = t.id
-     WHERE s.c >= 5
-       AND s.last_at <= now() - interval '6 months'
-       AND NOT EXISTS (
-           SELECT 1 FROM lidarr_quarantine q
-            WHERE q.user_id = $1 AND q.track_id = t.id
-       )
-),
-shallow AS (
-    SELECT t.id, t.album_id, t.artist_id, s.c, 1 AS tier
-      FROM tracks t
-      JOIN stats s ON s.track_id = t.id
-     WHERE s.c >= 5
-       AND s.last_at <= now() - interval '30 days'
-       AND NOT EXISTS (
-           SELECT 1 FROM lidarr_quarantine q
-            WHERE q.user_id = $1 AND q.track_id = t.id
-       )
 )
-SELECT id, album_id, artist_id
-  FROM (
-    SELECT id, album_id, artist_id, c, tier FROM deep
-    UNION ALL
-    SELECT id, album_id, artist_id, c, tier FROM shallow
-     WHERE NOT EXISTS (SELECT 1 FROM deep)
-  ) u
- ORDER BY tier, c DESC, id
+SELECT t.id, t.album_id, t.artist_id
+  FROM tracks t
+  JOIN stats s ON s.track_id = t.id
+ WHERE s.c >= 3
+   AND s.last_at <= now() - interval '30 days'
+   AND NOT EXISTS (
+       SELECT 1 FROM lidarr_quarantine q
+        WHERE q.user_id = $1 AND q.track_id = t.id
+   )
+   -- Declined-resurfacing cooldown (#1258): a skip on a
+   -- rediscover-sourced play is the user explicitly saying "I've moved
+   -- on" to the exact invitation this mix extends — such tracks sit
+   -- out ~90 days instead of re-qualifying the next day. Passive
+   -- signal only (rule #101).
+   AND NOT EXISTS (
+       SELECT 1 FROM play_events rp
+        WHERE rp.user_id = $1
+          AND rp.track_id = t.id
+          AND rp.source = 'rediscover'
+          AND rp.was_skipped = true
+          AND rp.started_at > now() - interval '90 days'
+   )
+ ORDER BY (s.last_at <= now() - interval '6 months') DESC,
+          (s.c >= 5) DESC,
+          s.c DESC, t.id
  LIMIT 200
 `
 
@@ -302,13 +398,17 @@ type ListRediscoverTracksRow struct {
 	ArtistID pgtype.UUID
 }
 
-// #420 Rediscover: tracks the user played a lot (>=5 non-skip) but
-// has drifted away from. Tiered so a young library still gets a mix:
-//
-//	tier 0  not played in the last 6 months (true rediscovery)
-//	tier 1  (only if tier 0 empty) not played in the last 30 days
-//
-// Ordered by historical affection. $1 user_id.
+// #420 Rediscover: tracks the user played a lot but has drifted away
+// from. One blended pool (issue #1246: the old two-tier UNION was
+// all-or-nothing — a single ">=6 months cold" row suppressed the whole
+// ">=30 days" tier, which is how a one-song playlist shipped; the 6mo
+// tier was also a strict subset of the 30d tier). Eligibility is >=3
+// non-skip plays and >=30 days cold; the bar sits at 3 rather than 5
+// so a weeks-old library still fields a pool — on young histories the
+// >=5-play tracks are precisely the ones still in rotation. Ordering
+// prefers true rediscoveries (>=6 months cold), then strong affection
+// (>=5 plays), then raw play count; the producer's minimum floor
+// decides whether the pool is big enough to ship at all. $1 user_id.
 func (q *Queries) ListRediscoverTracks(ctx context.Context, userID pgtype.UUID) ([]ListRediscoverTracksRow, error) {
 	rows, err := q.db.Query(ctx, listRediscoverTracks, userID)
 	if err != nil {

internal/db/dbq/system_playlists.sql.go

@@ -290,9 +290,13 @@ func (q *Queries) ListPlaylistsByUserAndKind(ctx context.Context, arg ListPlayli
 }
 
 const pickSeedArtists = `-- name: PickSeedArtists :many
-WITH plays AS (
+WITH liked AS (
+    SELECT gla.artist_id FROM general_likes_artists gla WHERE gla.user_id = $1
+),
+recent7 AS (
     SELECT t.artist_id,
-           COUNT(*) FILTER (WHERE pe.was_skipped = false) AS play_count
+           COUNT(*) FILTER (WHERE pe.was_skipped = false) AS play_count,
+           0 AS tier
       FROM play_events pe
       JOIN tracks t ON t.id = pe.track_id
      WHERE pe.user_id = $1
@@ -300,27 +304,80 @@ WITH plays AS (
        AND t.artist_id IS NOT NULL
      GROUP BY t.artist_id
 ),
-liked AS (
-    SELECT artist_id FROM general_likes_artists WHERE user_id = $1
+recent30 AS (
+    SELECT t.artist_id,
+           COUNT(*) FILTER (WHERE pe.was_skipped = false) AS play_count,
+           1 AS tier
+      FROM play_events pe
+      JOIN tracks t ON t.id = pe.track_id
+     WHERE pe.user_id = $1
+       AND pe.started_at > now() - INTERVAL '30 days'
+       AND t.artist_id IS NOT NULL
+     GROUP BY t.artist_id
+),
+alltime AS (
+    SELECT t.artist_id,
+           COUNT(*) FILTER (WHERE pe.was_skipped = false) AS play_count,
+           2 AS tier
+      FROM play_events pe
+      JOIN tracks t ON t.id = pe.track_id
+     WHERE pe.user_id = $1
+       AND t.artist_id IS NOT NULL
+     GROUP BY t.artist_id
+),
+likedonly AS (
+    SELECT l.artist_id, 0::bigint AS play_count, 3 AS tier
+      FROM liked l
+),
+chosen AS (
+    SELECT artist_id, play_count, tier FROM recent7
+    UNION ALL
+    SELECT artist_id, play_count, tier FROM recent30
+     WHERE NOT EXISTS (SELECT 1 FROM recent7)
+    UNION ALL
+    SELECT artist_id, play_count, tier FROM alltime
+     WHERE NOT EXISTS (SELECT 1 FROM recent7)
+       AND NOT EXISTS (SELECT 1 FROM recent30)
+    UNION ALL
+    SELECT artist_id, play_count, tier FROM likedonly
+     WHERE NOT EXISTS (SELECT 1 FROM recent7)
+       AND NOT EXISTS (SELECT 1 FROM recent30)
+       AND NOT EXISTS (SELECT 1 FROM alltime)
 )
-SELECT p.artist_id,
-       (p.play_count + CASE WHEN l.artist_id IS NOT NULL THEN 5 ELSE 0 END)::bigint AS score
-  FROM plays p
-  LEFT JOIN liked l ON l.artist_id = p.artist_id
- ORDER BY score DESC, p.artist_id
- LIMIT 5
+SELECT c.artist_id,
+       (c.play_count + CASE WHEN l.artist_id IS NOT NULL THEN 5 ELSE 0 END)::bigint AS score,
+       c.tier::int AS tier
+  FROM chosen c
+  LEFT JOIN liked l ON l.artist_id = c.artist_id
+ ORDER BY score DESC, c.artist_id
+ LIMIT 12
 `
 
 type PickSeedArtistsRow struct {
 	ArtistID pgtype.UUID
 	Score    int64
+	Tier     int32
 }
 
-// Top-5 most-engaged distinct artist candidates in the user's last 7
-// days. The Go-side picker (pickSeedArtistsForDay) shuffles these
-// daily-deterministically and takes the first 3 so the set of
-// "Songs like X" mixes rotates day-to-day.
-// Score = unskipped-play count + 5 if user has liked the artist.
+// Top-12 most-engaged distinct artist candidates, tiered so the
+// "Songs like X" mixes never silently vanish (#1255): the old hard
+// 7-day window emptied the seed pool after a quiet week, and the
+// daily atomic-replace build then deleted every existing mix until
+// the user played something again. Same fallback shape as
+// PickTopPlayedTracksForUser (For You's seeds):
+//
+//	tier 0  engagement in the last 7 days
+//	tier 1  (only if tier 0 empty) last 30 days
+//	tier 2  (only if tiers 0+1 empty) all-time
+//	tier 3  (only if 0-2 empty) liked artists with no play history
+//
+// All returned rows share one tier; produceSeedMixes maps it onto the
+// rule-#131 pick-kind ladder and stamps the built tracks, so metrics
+// can compare mixes seeded from fresh vs stale engagement.
+// Score = unskipped-play count + 5 if user has liked the artist. The
+// Go-side picker (pickSeedArtistsForDay) shuffles the 12
+// daily-deterministically and takes songsLikeSeedCount (6) so the mix
+// set both rotates day-to-day and fills the dedicated Home row (#1491).
 func (q *Queries) PickSeedArtists(ctx context.Context, userID pgtype.UUID) ([]PickSeedArtistsRow, error) {
 	rows, err := q.db.Query(ctx, pickSeedArtists, userID)
 	if err != nil {
@@ -330,7 +387,7 @@ func (q *Queries) PickSeedArtists(ctx context.Context, userID pgtype.UUID) ([]Pi
 	var items []PickSeedArtistsRow
 	for rows.Next() {
 		var i PickSeedArtistsRow
-		if err := rows.Scan(&i.ArtistID, &i.Score); err != nil {
+		if err := rows.Scan(&i.ArtistID, &i.Score, &i.Tier); err != nil {
 			return nil, err
 		}
 		items = append(items, i)
@@ -457,10 +514,10 @@ SELECT id
 //	tier 2  (only if tiers 0+1 empty) liked tracks
 //
 // Returns up to 5 ids; tie-break by track_id for determinism. The
-// Go-side picker (pickForYouSeedForDay) rotates one per day via
-// userIDHash. Widened from a hard 7-day window, which made For-You
-// disappear after a week of not listening and never recover on a
-// self-hosted library with sparse history.
+// Go-side picker (pickDailySeeds) draws the day's seeds from these.
+// Widened from a hard 7-day window, which made For-You disappear
+// after a week of not listening and never recover on a self-hosted
+// library with sparse history.
 func (q *Queries) PickTopPlayedTracksForUser(ctx context.Context, userID pgtype.UUID) ([]pgtype.UUID, error) {
 	rows, err := q.db.Query(ctx, pickTopPlayedTracksForUser, userID)
 	if err != nil {

internal/db/dbq/tag_settings.sql.go

@@ -0,0 +1,157 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: tag_settings.sql
+
+package dbq
+
+import (
+	"context"
+)
+
+const bumpTagSourcesVersion = `-- name: BumpTagSourcesVersion :one
+UPDATE tag_sources_meta
+   SET current_version = current_version + 1
+ WHERE id = true
+RETURNING current_version
+`
+
+// Increment + return the new version. Called only when the enabled set
+// changes (not on key edits).
+func (q *Queries) BumpTagSourcesVersion(ctx context.Context) (int32, error) {
+	row := q.db.QueryRow(ctx, bumpTagSourcesVersion)
+	var current_version int32
+	err := row.Scan(&current_version)
+	return current_version, err
+}
+
+const bumpTagVersionAndSetProvidersHash = `-- name: BumpTagVersionAndSetProvidersHash :one
+UPDATE tag_sources_meta
+   SET current_version = current_version + 1,
+       last_registered_providers_hash = $1
+ WHERE id = true
+RETURNING current_version
+`
+
+// Atomically increment the version and store the new registered-provider
+// hash. Called at boot when the compiled-in provider set changed, so
+// 'none' rows become eligible for a retry through the new chain.
+func (q *Queries) BumpTagVersionAndSetProvidersHash(ctx context.Context, lastRegisteredProvidersHash string) (int32, error) {
+	row := q.db.QueryRow(ctx, bumpTagVersionAndSetProvidersHash, lastRegisteredProvidersHash)
+	var current_version int32
+	err := row.Scan(&current_version)
+	return current_version, err
+}
+
+const getCurrentTagSourcesVersion = `-- name: GetCurrentTagSourcesVersion :one
+SELECT current_version FROM tag_sources_meta WHERE id = true
+`
+
+func (q *Queries) GetCurrentTagSourcesVersion(ctx context.Context) (int32, error) {
+	row := q.db.QueryRow(ctx, getCurrentTagSourcesVersion)
+	var current_version int32
+	err := row.Scan(&current_version)
+	return current_version, err
+}
+
+const getTagProvidersHash = `-- name: GetTagProvidersHash :one
+SELECT last_registered_providers_hash
+  FROM tag_sources_meta
+ WHERE id = true
+`
+
+func (q *Queries) GetTagProvidersHash(ctx context.Context) (string, error) {
+	row := q.db.QueryRow(ctx, getTagProvidersHash)
+	var last_registered_providers_hash string
+	err := row.Scan(&last_registered_providers_hash)
+	return last_registered_providers_hash, err
+}
+
+const listTagProviderSettings = `-- name: ListTagProviderSettings :many
+
+SELECT provider_id, enabled, api_key, display_order, created_at, updated_at
+  FROM tag_provider_settings
+ ORDER BY display_order, provider_id
+`
+
+// Tag-enrichment provider settings queries (milestone #160, #1490 Step 2).
+// The tags.SettingsService consumes these — parallel to the cover-art
+// SettingsService (coverart_settings.sql). Keeping the two independent
+// means a new tag source is added without touching the art settings.
+// All rows, for boot reconciliation and the admin GET handler.
+func (q *Queries) ListTagProviderSettings(ctx context.Context) ([]TagProviderSetting, error) {
+	rows, err := q.db.Query(ctx, listTagProviderSettings)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []TagProviderSetting
+	for rows.Next() {
+		var i TagProviderSetting
+		if err := rows.Scan(
+			&i.ProviderID,
+			&i.Enabled,
+			&i.ApiKey,
+			&i.DisplayOrder,
+			&i.CreatedAt,
+			&i.UpdatedAt,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const updateTagProviderSettings = `-- name: UpdateTagProviderSettings :exec
+UPDATE tag_provider_settings
+   SET enabled    = COALESCE($2, enabled),
+       api_key    = CASE WHEN $3::boolean THEN $4 ELSE api_key END,
+       updated_at = now()
+ WHERE provider_id = $1
+`
+
+type UpdateTagProviderSettingsParams struct {
+	ProviderID string
+	Enabled    bool
+	Column3    bool
+	ApiKey     *string
+}
+
+// Admin PATCH. $2 sets enabled. Pass FALSE for the $3 apiKeyChanged flag
+// to leave api_key untouched; TRUE with empty string clears it, TRUE with
+// a value sets it.
+func (q *Queries) UpdateTagProviderSettings(ctx context.Context, arg UpdateTagProviderSettingsParams) error {
+	_, err := q.db.Exec(ctx, updateTagProviderSettings,
+		arg.ProviderID,
+		arg.Enabled,
+		arg.Column3,
+		arg.ApiKey,
+	)
+	return err
+}
+
+const upsertTagProviderSettings = `-- name: UpsertTagProviderSettings :exec
+INSERT INTO tag_provider_settings (provider_id, enabled, display_order)
+VALUES ($1, $2, $3)
+ON CONFLICT (provider_id) DO UPDATE
+   SET display_order = EXCLUDED.display_order,
+       updated_at    = now()
+`
+
+type UpsertTagProviderSettingsParams struct {
+	ProviderID   string
+	Enabled      bool
+	DisplayOrder int32
+}
+
+// INSERT a default row for a newly-registered provider, or refresh an
+// existing row's display_order on boot. Does NOT overwrite enabled /
+// api_key on conflict — the operator's settings persist across restarts.
+func (q *Queries) UpsertTagProviderSettings(ctx context.Context, arg UpsertTagProviderSettingsParams) error {
+	_, err := q.db.Exec(ctx, upsertTagProviderSettings, arg.ProviderID, arg.Enabled, arg.DisplayOrder)
+	return err
+}

internal/db/dbq/taste_profile.sql.go

@@ -20,6 +20,24 @@ func (q *Queries) DeleteTasteProfileArtistsForUser(ctx context.Context, userID p
 	return err
 }
 
+const deleteTasteProfileErasForUser = `-- name: DeleteTasteProfileErasForUser :exec
+DELETE FROM taste_profile_eras WHERE user_id = $1
+`
+
+func (q *Queries) DeleteTasteProfileErasForUser(ctx context.Context, userID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteTasteProfileErasForUser, userID)
+	return err
+}
+
+const deleteTasteProfileMoodsForUser = `-- name: DeleteTasteProfileMoodsForUser :exec
+DELETE FROM taste_profile_moods WHERE user_id = $1
+`
+
+func (q *Queries) DeleteTasteProfileMoodsForUser(ctx context.Context, userID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteTasteProfileMoodsForUser, userID)
+	return err
+}
+
 const deleteTasteProfileTagsForUser = `-- name: DeleteTasteProfileTagsForUser :exec
 DELETE FROM taste_profile_tags WHERE user_id = $1
 `
@@ -45,6 +63,38 @@ func (q *Queries) InsertTasteProfileArtist(ctx context.Context, arg InsertTasteP
 	return err
 }
 
+const insertTasteProfileEra = `-- name: InsertTasteProfileEra :exec
+INSERT INTO taste_profile_eras (user_id, era, weight)
+VALUES ($1, $2, $3)
+`
+
+type InsertTasteProfileEraParams struct {
+	UserID pgtype.UUID
+	Era    string
+	Weight float64
+}
+
+func (q *Queries) InsertTasteProfileEra(ctx context.Context, arg InsertTasteProfileEraParams) error {
+	_, err := q.db.Exec(ctx, insertTasteProfileEra, arg.UserID, arg.Era, arg.Weight)
+	return err
+}
+
+const insertTasteProfileMood = `-- name: InsertTasteProfileMood :exec
+INSERT INTO taste_profile_moods (user_id, mood, weight)
+VALUES ($1, $2, $3)
+`
+
+type InsertTasteProfileMoodParams struct {
+	UserID pgtype.UUID
+	Mood   string
+	Weight float64
+}
+
+func (q *Queries) InsertTasteProfileMood(ctx context.Context, arg InsertTasteProfileMoodParams) error {
+	_, err := q.db.Exec(ctx, insertTasteProfileMood, arg.UserID, arg.Mood, arg.Weight)
+	return err
+}
+
 const insertTasteProfileTag = `-- name: InsertTasteProfileTag :exec
 INSERT INTO taste_profile_tags (user_id, tag, weight)
 VALUES ($1, $2, $3)
@@ -87,19 +137,23 @@ func (q *Queries) ListLikedArtistIDsForUser(ctx context.Context, userID pgtype.U
 }
 
 const listLikedTrackTasteInputsForUser = `-- name: ListLikedTrackTasteInputsForUser :many
-SELECT t.artist_id, t.genre
+SELECT t.id AS track_id, t.artist_id, t.genre, a.release_date
 FROM general_likes gl
 JOIN tracks t ON t.id = gl.track_id
+JOIN albums a ON a.id = t.album_id
 WHERE gl.user_id = $1
 `
 
 type ListLikedTrackTasteInputsForUserRow struct {
-	ArtistID pgtype.UUID
-	Genre    *string
+	TrackID     pgtype.UUID
+	ArtistID    pgtype.UUID
+	Genre       *string
+	ReleaseDate pgtype.Date
 }
 
-// (artist_id, genre) for each track the user has explicitly liked. Feeds the
-// track-like bonus into the liked track's artist and tags.
+// (track_id, artist_id, genre, release_date) for each track the user has
+// explicitly liked. Feeds the track-like bonus into the liked track's artist,
+// tags, and era (#1530); track_id keys the enriched track_tags lookup (#1490).
 func (q *Queries) ListLikedTrackTasteInputsForUser(ctx context.Context, userID pgtype.UUID) ([]ListLikedTrackTasteInputsForUserRow, error) {
 	rows, err := q.db.Query(ctx, listLikedTrackTasteInputsForUser, userID)
 	if err != nil {
@@ -109,7 +163,12 @@ func (q *Queries) ListLikedTrackTasteInputsForUser(ctx context.Context, userID p
 	var items []ListLikedTrackTasteInputsForUserRow
 	for rows.Next() {
 		var i ListLikedTrackTasteInputsForUserRow
-		if err := rows.Scan(&i.ArtistID, &i.Genre); err != nil {
+		if err := rows.Scan(
+			&i.TrackID,
+			&i.ArtistID,
+			&i.Genre,
+			&i.ReleaseDate,
+		); err != nil {
 			return nil, err
 		}
 		items = append(items, i)
@@ -123,8 +182,10 @@ func (q *Queries) ListLikedTrackTasteInputsForUser(ctx context.Context, userID p
 const listPlayEngagementInputsForUser = `-- name: ListPlayEngagementInputsForUser :many
 
 SELECT
+    t.id AS track_id,
     t.artist_id,
     t.genre,
+    a.release_date,
     LEAST(GREATEST(
         COALESCE(pe.completion_ratio,
                  pe.duration_played_ms::float8 / NULLIF(t.duration_ms, 0),
@@ -132,6 +193,7 @@ SELECT
     (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
+JOIN albums a ON a.id = t.album_id
 WHERE pe.user_id = $1
   AND pe.started_at > now() - ($2::float8 * INTERVAL '1 day')
   AND NOT EXISTS (
@@ -146,10 +208,12 @@ type ListPlayEngagementInputsForUserParams struct {
 }
 
 type ListPlayEngagementInputsForUserRow struct {
-	ArtistID   pgtype.UUID
-	Genre      *string
-	Completion float64
-	AgeDays    float64
+	TrackID     pgtype.UUID
+	ArtistID    pgtype.UUID
+	Genre       *string
+	ReleaseDate pgtype.Date
+	Completion  float64
+	AgeDays     float64
 }
 
 // Taste profile (#796 phase 1). The daily build computes signed artist/tag
@@ -158,7 +222,8 @@ type ListPlayEngagementInputsForUserRow struct {
 // 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.
+// is split into tags in Go; release_date derives the decade for the era
+// facet (#1530). 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 {
@@ -169,8 +234,10 @@ func (q *Queries) ListPlayEngagementInputsForUser(ctx context.Context, arg ListP
 	for rows.Next() {
 		var i ListPlayEngagementInputsForUserRow
 		if err := rows.Scan(
+			&i.TrackID,
 			&i.ArtistID,
 			&i.Genre,
+			&i.ReleaseDate,
 			&i.Completion,
 			&i.AgeDays,
 		); err != nil {
@@ -223,6 +290,84 @@ func (q *Queries) ListTasteProfileArtistsForUser(ctx context.Context, arg ListTa
 	return items, nil
 }
 
+const listTasteProfileErasForUser = `-- name: ListTasteProfileErasForUser :many
+SELECT era, weight
+FROM taste_profile_eras
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2
+`
+
+type ListTasteProfileErasForUserParams struct {
+	UserID pgtype.UUID
+	Limit  int32
+}
+
+type ListTasteProfileErasForUserRow struct {
+	Era    string
+	Weight float64
+}
+
+// Top-weighted taste eras (#1530); consumed by the scorer's era term.
+func (q *Queries) ListTasteProfileErasForUser(ctx context.Context, arg ListTasteProfileErasForUserParams) ([]ListTasteProfileErasForUserRow, error) {
+	rows, err := q.db.Query(ctx, listTasteProfileErasForUser, arg.UserID, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTasteProfileErasForUserRow
+	for rows.Next() {
+		var i ListTasteProfileErasForUserRow
+		if err := rows.Scan(&i.Era, &i.Weight); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listTasteProfileMoodsForUser = `-- name: ListTasteProfileMoodsForUser :many
+SELECT mood, weight
+FROM taste_profile_moods
+WHERE user_id = $1
+ORDER BY weight DESC
+LIMIT $2
+`
+
+type ListTasteProfileMoodsForUserParams struct {
+	UserID pgtype.UUID
+	Limit  int32
+}
+
+type ListTasteProfileMoodsForUserRow struct {
+	Mood   string
+	Weight float64
+}
+
+// Top-weighted taste moods (#1534); consumed by the scorer's mood term.
+func (q *Queries) ListTasteProfileMoodsForUser(ctx context.Context, arg ListTasteProfileMoodsForUserParams) ([]ListTasteProfileMoodsForUserRow, error) {
+	rows, err := q.db.Query(ctx, listTasteProfileMoodsForUser, arg.UserID, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTasteProfileMoodsForUserRow
+	for rows.Next() {
+		var i ListTasteProfileMoodsForUserRow
+		if err := rows.Scan(&i.Mood, &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

internal/db/dbq/track_tags.sql.go

@@ -0,0 +1,222 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: track_tags.sql
+
+package dbq
+
+import (
+	"context"
+
+	"github.com/jackc/pgx/v5/pgtype"
+)
+
+const deleteTrackTags = `-- name: DeleteTrackTags :exec
+DELETE FROM track_tags WHERE track_id = $1
+`
+
+// Clear a track's cached tags before rewriting (atomic replace by the caller).
+func (q *Queries) DeleteTrackTags(ctx context.Context, trackID pgtype.UUID) error {
+	_, err := q.db.Exec(ctx, deleteTrackTags, trackID)
+	return err
+}
+
+const insertTrackTag = `-- name: InsertTrackTag :exec
+INSERT INTO track_tags (track_id, tag, weight)
+VALUES ($1, $2, $3)
+ON CONFLICT (track_id, tag)
+    DO UPDATE SET weight = GREATEST(track_tags.weight, EXCLUDED.weight)
+`
+
+type InsertTrackTagParams struct {
+	TrackID pgtype.UUID
+	Tag     string
+	Weight  float64
+}
+
+// Upsert one (track, tag); keep the stronger weight when two providers
+// agree on a tag with different folksonomy strengths.
+func (q *Queries) InsertTrackTag(ctx context.Context, arg InsertTrackTagParams) error {
+	_, err := q.db.Exec(ctx, insertTrackTag, arg.TrackID, arg.Tag, arg.Weight)
+	return err
+}
+
+const listLikedTrackTagsForUser = `-- name: ListLikedTrackTagsForUser :many
+SELECT tt.track_id, tt.tag, tt.weight
+  FROM track_tags tt
+  JOIN general_likes gl ON gl.track_id = tt.track_id
+ WHERE gl.user_id = $1
+`
+
+// Enriched tags for the user's liked tracks — the like-bonus path in the
+// recompute mirrors the play path, so it needs the same tag lookup.
+func (q *Queries) ListLikedTrackTagsForUser(ctx context.Context, userID pgtype.UUID) ([]TrackTag, error) {
+	rows, err := q.db.Query(ctx, listLikedTrackTagsForUser, userID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []TrackTag
+	for rows.Next() {
+		var i TrackTag
+		if err := rows.Scan(&i.TrackID, &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
+}
+
+const listPlayedTrackTagsForUser = `-- name: ListPlayedTrackTagsForUser :many
+SELECT tt.track_id, tt.tag, tt.weight
+  FROM track_tags tt
+ WHERE tt.track_id IN (
+       SELECT DISTINCT pe.track_id
+         FROM play_events pe
+        WHERE pe.user_id = $1
+          AND pe.was_skipped = false
+          AND pe.started_at > now() - make_interval(days => $2::int)
+   )
+`
+
+type ListPlayedTrackTagsForUserParams struct {
+	UserID  pgtype.UUID
+	Column2 int32
+}
+
+// The enriched tags for every track this user played inside the taste
+// window, so the recompute can union them into the tag facet alongside
+// ID3 genre. $1 = user_id, $2 = window_days. One row per (track, tag).
+func (q *Queries) ListPlayedTrackTagsForUser(ctx context.Context, arg ListPlayedTrackTagsForUserParams) ([]TrackTag, error) {
+	rows, err := q.db.Query(ctx, listPlayedTrackTagsForUser, arg.UserID, arg.Column2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []TrackTag
+	for rows.Next() {
+		var i TrackTag
+		if err := rows.Scan(&i.TrackID, &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
+}
+
+const listTrackTagsForTracks = `-- name: ListTrackTagsForTracks :many
+SELECT tt.track_id, tt.tag
+  FROM track_tags tt
+ WHERE tt.track_id = ANY($1::uuid[])
+`
+
+type ListTrackTagsForTracksRow struct {
+	TrackID pgtype.UUID
+	Tag     string
+}
+
+// Enriched tags for a set of candidate tracks (#1534), so the scorer can
+// derive each candidate's mood buckets at scoring time. One row per (track,
+// tag); the caller filters to mood words via the internal/mood vocabulary.
+func (q *Queries) ListTrackTagsForTracks(ctx context.Context, dollar_1 []pgtype.UUID) ([]ListTrackTagsForTracksRow, error) {
+	rows, err := q.db.Query(ctx, listTrackTagsForTracks, dollar_1)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTrackTagsForTracksRow
+	for rows.Next() {
+		var i ListTrackTagsForTracksRow
+		if err := rows.Scan(&i.TrackID, &i.Tag); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const listTracksMissingTags = `-- name: ListTracksMissingTags :many
+
+SELECT t.id, t.mbid, t.title, a.name AS artist_name, a.mbid AS artist_mbid
+  FROM tracks t
+  JOIN artists a ON a.id = t.artist_id
+ WHERE t.tag_source IS NULL
+    OR (t.tag_source = 'none' AND t.tag_sources_version < $1)
+ ORDER BY t.id
+ LIMIT $2
+`
+
+type ListTracksMissingTagsParams struct {
+	TagSourcesVersion int32
+	Limit             int32
+}
+
+type ListTracksMissingTagsRow struct {
+	ID         pgtype.UUID
+	Mbid       *string
+	Title      string
+	ArtistName string
+	ArtistMbid *string
+}
+
+// Track-tag enrichment queries (milestone #160, #1490). The tag enricher
+// drains ListTracksMissingTags, fetches from the provider chain, and
+// writes the merged top-K via DeleteTrackTags + InsertTrackTag, then
+// stamps SetTrackTagSource. Mirrors the coverart artist-enricher shape.
+// Tracks eligible for tag enrichment: never processed (tag_source NULL)
+// or previously settled 'none' under an older provider version. Returns
+// the fields the provider chain needs — recording MBID (nullable) for
+// keyed lookups, title + artist name for name-based fallback, and the
+// artist MBID (nullable) for MusicBrainz's artist-tag fallback (#1519).
+// $1 = current tag_sources_version, $2 = limit.
+func (q *Queries) ListTracksMissingTags(ctx context.Context, arg ListTracksMissingTagsParams) ([]ListTracksMissingTagsRow, error) {
+	rows, err := q.db.Query(ctx, listTracksMissingTags, arg.TagSourcesVersion, arg.Limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var items []ListTracksMissingTagsRow
+	for rows.Next() {
+		var i ListTracksMissingTagsRow
+		if err := rows.Scan(
+			&i.ID,
+			&i.Mbid,
+			&i.Title,
+			&i.ArtistName,
+			&i.ArtistMbid,
+		); err != nil {
+			return nil, err
+		}
+		items = append(items, i)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+const setTrackTagSource = `-- name: SetTrackTagSource :exec
+UPDATE tracks SET tag_source = $2, tag_sources_version = $3 WHERE id = $1
+`
+
+type SetTrackTagSourceParams struct {
+	ID                pgtype.UUID
+	TagSource         *string
+	TagSourcesVersion int32
+}
+
+// Stamp the enrichment outcome so the batch drainer skips settled rows.
+// $2 = 'lastfm' | 'musicbrainz' | 'mixed' | 'none', $3 = current version.
+func (q *Queries) SetTrackTagSource(ctx context.Context, arg SetTrackTagSourceParams) error {
+	_, err := q.db.Exec(ctx, setTrackTagSource, arg.ID, arg.TagSource, arg.TagSourcesVersion)
+	return err
+}

internal/db/dbq/tracks.sql.go

@@ -90,7 +90,7 @@ func (q *Queries) DeleteTrack(ctx context.Context, id pgtype.UUID) (DeleteTrackR
 }
 
 const getTrackByID = `-- name: GetTrackByID :one
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at FROM tracks WHERE id = $1
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version FROM tracks WHERE id = $1
 `
 
 func (q *Queries) GetTrackByID(ctx context.Context, id pgtype.UUID) (Track, error) {
@@ -112,12 +112,14 @@ func (q *Queries) GetTrackByID(ctx context.Context, id pgtype.UUID) (Track, erro
 		&i.Genre,
 		&i.AddedAt,
 		&i.UpdatedAt,
+		&i.TagSource,
+		&i.TagSourcesVersion,
 	)
 	return i, err
 }
 
 const getTrackByPath = `-- name: GetTrackByPath :one
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at FROM tracks WHERE file_path = $1
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version FROM tracks WHERE file_path = $1
 `
 
 func (q *Queries) GetTrackByPath(ctx context.Context, filePath string) (Track, error) {
@@ -139,12 +141,14 @@ func (q *Queries) GetTrackByPath(ctx context.Context, filePath string) (Track, e
 		&i.Genre,
 		&i.AddedAt,
 		&i.UpdatedAt,
+		&i.TagSource,
+		&i.TagSourcesVersion,
 	)
 	return i, err
 }
 
 const getTracksByIDs = `-- name: GetTracksByIDs :many
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at FROM tracks WHERE id = ANY($1::uuid[])
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version FROM tracks WHERE id = ANY($1::uuid[])
 `
 
 // Batched lookup used by /api/library/sync to hydrate upsert payloads
@@ -174,6 +178,8 @@ func (q *Queries) GetTracksByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([
 			&i.Genre,
 			&i.AddedAt,
 			&i.UpdatedAt,
+			&i.TagSource,
+			&i.TagSourcesVersion,
 		); err != nil {
 			return nil, err
 		}
@@ -186,7 +192,7 @@ func (q *Queries) GetTracksByIDs(ctx context.Context, dollar_1 []pgtype.UUID) ([
 }
 
 const listArtistTracksForUser = `-- name: ListArtistTracksForUser :many
-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,
+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, t.tag_source, t.tag_sources_version,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM tracks t
@@ -242,6 +248,8 @@ func (q *Queries) ListArtistTracksForUser(ctx context.Context, arg ListArtistTra
 			&i.Track.Genre,
 			&i.Track.AddedAt,
 			&i.Track.UpdatedAt,
+			&i.Track.TagSource,
+			&i.Track.TagSourcesVersion,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -256,7 +264,7 @@ func (q *Queries) ListArtistTracksForUser(ctx context.Context, arg ListArtistTra
 }
 
 const listRandomTracksForUser = `-- name: ListRandomTracksForUser :many
-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,
+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, t.tag_source, t.tag_sources_version,
        albums.title AS album_title,
        artists.name AS artist_name
 FROM tracks t
@@ -309,6 +317,8 @@ func (q *Queries) ListRandomTracksForUser(ctx context.Context, arg ListRandomTra
 			&i.Track.Genre,
 			&i.Track.AddedAt,
 			&i.Track.UpdatedAt,
+			&i.Track.TagSource,
+			&i.Track.TagSourcesVersion,
 			&i.AlbumTitle,
 			&i.ArtistName,
 		); err != nil {
@@ -323,7 +333,7 @@ func (q *Queries) ListRandomTracksForUser(ctx context.Context, arg ListRandomTra
 }
 
 const listTracksByAlbum = `-- name: ListTracksByAlbum :many
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at FROM tracks
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version FROM tracks
 WHERE album_id = $1
   AND NOT EXISTS (
     SELECT 1 FROM lidarr_quarantine q
@@ -365,6 +375,8 @@ func (q *Queries) ListTracksByAlbum(ctx context.Context, arg ListTracksByAlbumPa
 			&i.Genre,
 			&i.AddedAt,
 			&i.UpdatedAt,
+			&i.TagSource,
+			&i.TagSourcesVersion,
 		); err != nil {
 			return nil, err
 		}
@@ -412,7 +424,7 @@ func (q *Queries) ListTracksMissingMbidWithPath(ctx context.Context, limit int32
 }
 
 const searchTracks = `-- name: SearchTracks :many
-SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at FROM tracks
+SELECT id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version FROM tracks
 WHERE title ILIKE '%' || $1::text || '%'
   AND NOT EXISTS (
     SELECT 1 FROM lidarr_quarantine q
@@ -461,6 +473,8 @@ func (q *Queries) SearchTracks(ctx context.Context, arg SearchTracksParams) ([]T
 			&i.Genre,
 			&i.AddedAt,
 			&i.UpdatedAt,
+			&i.TagSource,
+			&i.TagSourcesVersion,
 		); err != nil {
 			return nil, err
 		}
@@ -508,7 +522,7 @@ ON CONFLICT (file_path) DO UPDATE SET
     mbid = EXCLUDED.mbid,
     genre = EXCLUDED.genre,
     updated_at = now()
-RETURNING id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at
+RETURNING id, title, album_id, artist_id, track_number, disc_number, duration_ms, file_path, file_size, file_format, bitrate, mbid, genre, added_at, updated_at, tag_source, tag_sources_version
 `
 
 type UpsertTrackParams struct {
@@ -559,6 +573,8 @@ func (q *Queries) UpsertTrack(ctx context.Context, arg UpsertTrackParams) (Track
 		&i.Genre,
 		&i.AddedAt,
 		&i.UpdatedAt,
+		&i.TagSource,
+		&i.TagSourcesVersion,
 	)
 	return i, err
 }

internal/db/dbq/users.sql.go

@@ -54,7 +54,7 @@ func (q *Queries) CountUsers(ctx context.Context) (int64, error) {
 const createUser = `-- name: CreateUser :one
 INSERT INTO users (username, password_hash, api_token, is_admin, display_name)
 VALUES ($1, $2, $3, $4, $5)
-RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at
+RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled
 `
 
 type CreateUserParams struct {
@@ -89,6 +89,7 @@ func (q *Queries) CreateUser(ctx context.Context, arg CreateUserParams) (User, e
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
@@ -96,7 +97,7 @@ func (q *Queries) CreateUser(ctx context.Context, arg CreateUserParams) (User, e
 const createUserAdmin = `-- name: CreateUserAdmin :one
 INSERT INTO users (username, password_hash, api_token, is_admin, display_name)
 VALUES ($1, $2, $3, $4, $5)
-RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at
+RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled
 `
 
 type CreateUserAdminParams struct {
@@ -134,6 +135,7 @@ func (q *Queries) CreateUserAdmin(ctx context.Context, arg CreateUserAdminParams
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
@@ -145,7 +147,7 @@ VALUES (
     (SELECT NOT EXISTS (SELECT 1 FROM users)),
     $4
 )
-RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at
+RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled
 `
 
 type CreateUserFirstAdminRaceParams struct {
@@ -191,6 +193,7 @@ func (q *Queries) CreateUserFirstAdminRace(ctx context.Context, arg CreateUserFi
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
@@ -237,7 +240,7 @@ func (q *Queries) GetListenBrainzConfig(ctx context.Context, id pgtype.UUID) (Ge
 }
 
 const getUserByAPIToken = `-- name: GetUserByAPIToken :one
-SELECT id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at FROM users WHERE api_token = $1
+SELECT id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled FROM users WHERE api_token = $1
 `
 
 func (q *Queries) GetUserByAPIToken(ctx context.Context, apiToken string) (User, error) {
@@ -258,12 +261,13 @@ func (q *Queries) GetUserByAPIToken(ctx context.Context, apiToken string) (User,
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
 
 const getUserByEmail = `-- name: GetUserByEmail :one
-SELECT id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at FROM users WHERE lower(email) = lower($1)
+SELECT id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled FROM users WHERE lower(email) = lower($1)
 `
 
 // Used by forgot-password lookup. Lowercase comparison both sides
@@ -287,12 +291,13 @@ func (q *Queries) GetUserByEmail(ctx context.Context, lower string) (User, error
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
 
 const getUserByID = `-- name: GetUserByID :one
-SELECT id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at FROM users WHERE id = $1
+SELECT id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled FROM users WHERE id = $1
 `
 
 func (q *Queries) GetUserByID(ctx context.Context, id pgtype.UUID) (User, error) {
@@ -313,12 +318,13 @@ func (q *Queries) GetUserByID(ctx context.Context, id pgtype.UUID) (User, error)
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
 
 const getUserByUsername = `-- name: GetUserByUsername :one
-SELECT id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at FROM users WHERE username = $1
+SELECT id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled FROM users WHERE username = $1
 `
 
 func (q *Queries) GetUserByUsername(ctx context.Context, username string) (User, error) {
@@ -339,6 +345,7 @@ func (q *Queries) GetUserByUsername(ctx context.Context, username string) (User,
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
@@ -382,7 +389,8 @@ func (q *Queries) ListActiveUsersWithTimezones(ctx context.Context) ([]ListActiv
 }
 
 const listUsers = `-- name: ListUsers :many
-SELECT id, username, display_name, is_admin, auto_approve_requests, created_at
+SELECT id, username, display_name, is_admin, auto_approve_requests,
+       debug_mode_enabled, created_at
   FROM users
  ORDER BY created_at DESC
 `
@@ -393,6 +401,7 @@ type ListUsersRow struct {
 	DisplayName         *string
 	IsAdmin             bool
 	AutoApproveRequests bool
+	DebugModeEnabled    bool
 	CreatedAt           pgtype.Timestamptz
 }
 
@@ -412,6 +421,7 @@ func (q *Queries) ListUsers(ctx context.Context) ([]ListUsersRow, error) {
 			&i.DisplayName,
 			&i.IsAdmin,
 			&i.AutoApproveRequests,
+			&i.DebugModeEnabled,
 			&i.CreatedAt,
 		); err != nil {
 			return nil, err
@@ -426,7 +436,7 @@ func (q *Queries) ListUsers(ctx context.Context) ([]ListUsersRow, error) {
 
 const regenerateApiToken = `-- name: RegenerateApiToken :one
 UPDATE users SET api_token = $2 WHERE id = $1
-RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at
+RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled
 `
 
 type RegenerateApiTokenParams struct {
@@ -454,6 +464,7 @@ func (q *Queries) RegenerateApiToken(ctx context.Context, arg RegenerateApiToken
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
@@ -478,6 +489,44 @@ func (q *Queries) ResetUserPassword(ctx context.Context, arg ResetUserPasswordPa
 	return err
 }
 
+const setDebugMode = `-- name: SetDebugMode :one
+UPDATE users
+   SET debug_mode_enabled = $2
+ WHERE id = $1
+RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled
+`
+
+type SetDebugModeParams struct {
+	ID               pgtype.UUID
+	DebugModeEnabled bool
+}
+
+// Toggle the per-account diagnostics/debug-reporting opt-in. Admin-driven
+// from /admin (flip remotely while a bug is live) or self-driven OFF from
+// the client. Returns the updated row so the handler can echo it.
+func (q *Queries) SetDebugMode(ctx context.Context, arg SetDebugModeParams) (User, error) {
+	row := q.db.QueryRow(ctx, setDebugMode, arg.ID, arg.DebugModeEnabled)
+	var i User
+	err := row.Scan(
+		&i.ID,
+		&i.Username,
+		&i.PasswordHash,
+		&i.ApiToken,
+		&i.IsAdmin,
+		&i.CreatedAt,
+		&i.SubsonicPassword,
+		&i.ListenbrainzToken,
+		&i.ListenbrainzEnabled,
+		&i.DisplayName,
+		&i.AutoApproveRequests,
+		&i.Email,
+		&i.Timezone,
+		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
+	)
+	return i, err
+}
+
 const setListenBrainzEnabled = `-- name: SetListenBrainzEnabled :exec
 UPDATE users
 SET listenbrainz_enabled = $2
@@ -531,7 +580,7 @@ const updateUserAdmin = `-- name: UpdateUserAdmin :one
 UPDATE users
    SET is_admin = $2
  WHERE id = $1
-RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at
+RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled
 `
 
 type UpdateUserAdminParams struct {
@@ -559,6 +608,7 @@ func (q *Queries) UpdateUserAdmin(ctx context.Context, arg UpdateUserAdminParams
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
@@ -567,7 +617,7 @@ const updateUserAutoApprove = `-- name: UpdateUserAutoApprove :one
 UPDATE users
    SET auto_approve_requests = $2
  WHERE id = $1
-RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at
+RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled
 `
 
 type UpdateUserAutoApproveParams struct {
@@ -594,6 +644,7 @@ func (q *Queries) UpdateUserAutoApprove(ctx context.Context, arg UpdateUserAutoA
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }
@@ -603,7 +654,7 @@ UPDATE users
    SET display_name = $2,
        email        = $3
  WHERE id = $1
-RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at
+RETURNING id, username, password_hash, api_token, is_admin, created_at, subsonic_password, listenbrainz_token, listenbrainz_enabled, display_name, auto_approve_requests, email, timezone, timezone_updated_at, debug_mode_enabled
 `
 
 type UpdateUserProfileParams struct {
@@ -632,6 +683,7 @@ func (q *Queries) UpdateUserProfile(ctx context.Context, arg UpdateUserProfilePa
 		&i.Email,
 		&i.Timezone,
 		&i.TimezoneUpdatedAt,
+		&i.DebugModeEnabled,
 	)
 	return i, err
 }

internal/db/migrations/0036_diagnostics.down.sql

@@ -0,0 +1,2 @@
+ALTER TABLE users DROP COLUMN IF EXISTS debug_mode_enabled;
+DROP TABLE IF EXISTS diagnostic_events;