From ae7e05c579219a46e462954355213cd9d391fd70 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Fri, 23 Oct 2026 12:59:07 -0400
Subject: [PATCH] docs: Android comments say what the app does, not how it came
 to be (#6277)

Every flagged comment block in the Android app, its tests and its XML/TOML
config, rewritten with the cited issue in view: the constraint is kept, the
story behind it dropped, and issue, milestone, rule, phase and drift ids,
dates and operator quotes removed. "Mirrors the Flutter client's X"
pointers are gone; that client is no longer in the repo.

Comments that no longer matched the code, corrected:
- SyncController: a 410 resets the cursor and re-pulls; it never dropped
  the three local caches.
- PlayerFactory, PlayerModule, AudioCacheIndexEntity, CacheConfig,
  CacheSource: there is no eviction worker and no liked-track bucket;
  SimpleCache evicts by plain LRU over the rolling cap, and the liked cap
  is stored but unenforced.
- CacheSettings, StorageCard: the prefetcher exists (AudioPrefetcher);
  pin-on-like still does not.
- LibraryApi, LibraryRepository, BrowseViewModel: the cache now carries
  the missing-file mark; the browse indexes stay server-backed for one
  source of grouping.
- OutputRoute: UPnP routes exist; only CAST and SONOS are reserved.
- PlayerFactory, RemotePlayerState, OutputPickerController: a failed
  transport command does not drop the UPnP route.
- LibraryScreen: History, Liked and Hidden are real tabs, not placeholders.
- AVTransportClient: the extend loop lives in SonosQueueLoader.
- "the operator" meaning the listener now says "the user".

Verified with a Kotlin lexer comparing every file's non-comment tokens
against HEAD: 394 files, 0 differences.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 android/app/build.gradle.kts                  | 23 ++---
 android/app/src/main/AndroidManifest.xml      |  9 +-
 .../com/fabledsword/minstrel/MainActivity.kt  |  2 +-
 .../minstrel/MinstrelApplication.kt           | 13 ++-
 .../admin/data/AdminQuarantineRepository.kt   |  7 +-
 .../admin/data/AdminRequestsRepository.kt     |  2 +-
 .../admin/data/AdminTagSourcesRepository.kt   |  2 +-
 .../admin/data/AdminUsersRepository.kt        |  4 +-
 .../admin/ui/AdminInvitesViewModel.kt         |  2 +-
 .../admin/ui/AdminQuarantineViewModel.kt      |  6 +-
 .../admin/ui/AdminRequestsViewModel.kt        |  2 +-
 .../admin/ui/AdminTagSourcesViewModel.kt      |  2 +-
 .../minstrel/admin/ui/AdminUsersViewModel.kt  |  2 +-
 .../minstrel/api/AuthCookieInterceptor.kt     | 16 +---
 .../minstrel/api/BaseUrlInterceptor.kt        |  9 +-
 .../minstrel/api/CleartextGuard.kt            |  5 +-
 .../com/fabledsword/minstrel/api/ErrorCopy.kt |  4 +-
 .../fabledsword/minstrel/api/NetworkModule.kt | 17 ++--
 .../minstrel/api/endpoints/AdminInvitesApi.kt |  5 +-
 .../api/endpoints/AdminTagSourcesApi.kt       |  6 +-
 .../minstrel/api/endpoints/CastApi.kt         |  2 +-
 .../minstrel/api/endpoints/DiagnosticsApi.kt  |  2 +-
 .../minstrel/api/endpoints/DiscoverApi.kt     |  3 +-
 .../minstrel/api/endpoints/LibraryApi.kt      | 13 ++-
 .../minstrel/api/endpoints/MeApi.kt           |  4 +-
 .../api/endpoints/NotificationsApi.kt         |  2 +-
 .../minstrel/api/endpoints/PlaylistsApi.kt    |  6 +-
 .../minstrel/api/endpoints/QuarantineApi.kt   |  2 +-
 .../minstrel/api/endpoints/ReplayGainApi.kt   |  2 +-
 .../minstrel/api/endpoints/RequestsApi.kt     |  2 +-
 .../minstrel/api/endpoints/SyncApi.kt         |  2 +-
 .../minstrel/auth/AuthController.kt           |  2 +-
 .../fabledsword/minstrel/auth/AuthStore.kt    | 20 ++--
 .../fabledsword/minstrel/auth/SessionVault.kt | 13 ++-
 .../minstrel/auth/ui/AuthGateViewModel.kt     |  4 +-
 .../minstrel/cache/CacheIndexer.kt            | 16 ++--
 .../minstrel/cache/ShuffleSource.kt           | 11 +--
 .../minstrel/cache/audiocache/CacheConfig.kt  | 16 ++--
 .../cache/audiocache/CacheSettings.kt         | 18 ++--
 .../minstrel/cache/db/AppDatabase.kt          | 45 ++++-----
 .../minstrel/cache/db/DatabaseModule.kt       |  9 +-
 .../minstrel/cache/db/TypeConverters.kt       | 15 ++-
 .../minstrel/cache/db/dao/CachedLikeDao.kt    |  7 +-
 .../cache/db/dao/CachedPlaylistTrackDao.kt    | 10 +-
 .../cache/db/dao/CachedQuarantineDao.kt       |  3 +-
 .../minstrel/cache/db/dao/CachedTrackDao.kt   |  2 +-
 .../db/entities/AudioCacheIndexEntity.kt      | 12 +--
 .../cache/db/entities/AuthSessionEntity.kt    |  6 +-
 .../cache/db/entities/CachedAlbumEntity.kt    |  7 +-
 .../cache/db/entities/CachedArtistEntity.kt   | 10 +-
 .../entities/CachedHistorySnapshotEntity.kt   |  3 +-
 .../db/entities/CachedHomeIndexEntity.kt      |  3 +-
 .../cache/db/entities/CachedLikeEntity.kt     |  7 +-
 .../cache/db/entities/CachedMutationEntity.kt |  5 +-
 .../db/entities/CachedNotificationEntity.kt   |  2 +-
 .../CachedNotificationSettingsEntity.kt       |  2 +-
 .../cache/db/entities/CachedPlaylistEntity.kt |  3 +-
 .../db/entities/CachedPlaylistTrackEntity.kt  |  3 +-
 .../db/entities/CachedQuarantineEntity.kt     |  4 +-
 .../db/entities/CachedResumeStateEntity.kt    | 11 +--
 .../cache/db/entities/CachedTrackEntity.kt    |  7 +-
 .../db/entities/DiagnosticEventEntity.kt      |  4 +-
 .../cache/db/entities/SyncMetadataEntity.kt   |  8 +-
 .../minstrel/cache/mutations/MutationQueue.kt | 40 ++++----
 .../cache/mutations/MutationReplayer.kt       |  8 +-
 .../minstrel/cache/sync/SyncController.kt     | 24 +++--
 .../connectivity/NetworkStatusController.kt   | 26 +++---
 .../connectivity/ReachabilityMachine.kt       | 11 +--
 .../diagnostics/DiagnosticsReporter.kt        | 14 ++-
 .../diagnostics/DiagnosticsUploader.kt        |  2 +-
 .../diagnostics/TransportFlapDetector.kt      |  7 +-
 .../discover/data/DiscoverRepository.kt       | 15 +--
 .../minstrel/discover/ui/DiscoverScreen.kt    | 10 +-
 .../minstrel/discover/ui/DiscoverTiles.kt     |  6 +-
 .../minstrel/discover/ui/DiscoverViewModel.kt |  2 +-
 .../minstrel/events/EventsStream.kt           |  2 +-
 .../fabledsword/minstrel/events/LiveEvent.kt  |  3 +-
 .../minstrel/events/LiveEventsDispatcher.kt   |  2 +-
 .../minstrel/events/ReconnectBackoff.kt       | 10 +-
 .../history/data/HistoryRepository.kt         |  8 +-
 .../minstrel/history/ui/HistoryTab.kt         |  4 +-
 .../minstrel/home/data/HomeRepository.kt      |  9 +-
 .../minstrel/home/ui/HomeScreen.kt            | 93 ++++++++-----------
 .../library/data/LibraryRepository.kt         | 21 ++---
 .../library/ui/AlbumDetailViewModel.kt        |  2 +-
 .../minstrel/library/ui/ArtistDetailScreen.kt |  6 +-
 .../library/ui/ArtistDetailViewModel.kt       |  9 +-
 .../minstrel/library/ui/BrowseViewModel.kt    | 13 +--
 .../minstrel/library/ui/GenresTab.kt          |  2 +-
 .../minstrel/library/ui/LibraryScreen.kt      | 16 +---
 .../minstrel/library/ui/YearsTab.kt           |  2 +-
 .../minstrel/library/widgets/AlbumCard.kt     | 11 +--
 .../minstrel/library/widgets/ArtistCard.kt    | 12 +--
 .../minstrel/likes/data/LikesRepository.kt    | 70 ++++++--------
 .../fabledsword/minstrel/likes/ui/LikedTab.kt |  6 +-
 .../minstrel/metadata/HomeArtistPrewarmer.kt  | 10 +-
 .../minstrel/metadata/MetadataProvider.kt     | 13 +--
 .../minstrel/models/AdminQuarantineItem.kt    |  2 +-
 .../minstrel/models/AdminTagSourceRef.kt      |  2 +-
 .../minstrel/models/AdminUserRef.kt           |  2 +-
 .../fabledsword/minstrel/models/AlbumRef.kt   |  3 +-
 .../fabledsword/minstrel/models/ArtistRef.kt  |  8 +-
 .../fabledsword/minstrel/models/Discover.kt   | 15 ++-
 .../com/fabledsword/minstrel/models/Invite.kt |  5 +-
 .../minstrel/models/ListenBrainzStatus.kt     |  5 +-
 .../fabledsword/minstrel/models/MyProfile.kt  |  4 +-
 .../fabledsword/minstrel/models/Playlist.kt   | 18 ++--
 .../minstrel/models/QuarantineRef.kt          |  3 +-
 .../fabledsword/minstrel/models/Request.kt    |  7 +-
 .../fabledsword/minstrel/models/TrackRef.kt   | 11 +--
 .../fabledsword/minstrel/models/UserRef.kt    |  2 +-
 .../models/wire/AdminQuarantineWire.kt        |  5 +-
 .../models/wire/AdminTagSourceWire.kt         |  2 +-
 .../minstrel/models/wire/BrowseWire.kt        |  2 +-
 .../minstrel/models/wire/DiscoverWire.kt      | 16 ++--
 .../minstrel/models/wire/EventsWire.kt        |  4 +-
 .../minstrel/models/wire/PlaylistWire.kt      |  8 +-
 .../models/wire/QuarantineMineWire.kt         |  9 +-
 .../minstrel/models/wire/RadioResponseWire.kt |  3 +-
 .../minstrel/models/wire/ReplayGainWire.kt    |  2 +-
 .../minstrel/models/wire/RequestWire.kt       |  3 +-
 .../minstrel/models/wire/SyncResponseWire.kt  | 13 +--
 .../minstrel/models/wire/TrackWire.kt         | 15 ++-
 .../minstrel/nav/DetailSeedCache.kt           |  3 +-
 .../minstrel/nav/MinstrelNavGraph.kt          |  8 +-
 .../data/NotificationSettingsRepository.kt    |  6 +-
 .../data/NotificationsRepository.kt           |  8 +-
 .../notifications/delivery/BootReceiver.kt    |  4 +-
 .../delivery/DeliveryLauncher.kt              |  2 +-
 .../notifications/delivery/DeliveryPlan.kt    |  6 +-
 .../notifications/delivery/DeliveryService.kt |  4 +-
 .../delivery/NotificationPoster.kt            |  2 +-
 .../delivery/NotificationSync.kt              |  4 +-
 .../notifications/ui/NotificationLinks.kt     |  2 +-
 .../ui/NotificationSettingsScreen.kt          |  6 +-
 .../ui/NotificationSettingsViewModel.kt       |  2 +-
 .../ui/NotificationsViewModel.kt              |  2 +-
 .../minstrel/player/LikeMediaCallback.kt      |  3 +-
 .../player/MinstrelForwardingPlayer.kt        |  6 +-
 .../minstrel/player/MinstrelPlayerService.kt  |  6 +-
 .../minstrel/player/PlayEventsReporter.kt     | 33 +++----
 .../minstrel/player/PlaybackErrorReporter.kt  |  5 +-
 .../minstrel/player/PlayerController.kt       | 72 ++++++--------
 .../minstrel/player/PlayerFactory.kt          | 28 +++---
 .../minstrel/player/PlayerModule.kt           | 11 +--
 .../minstrel/player/RemotePlayerState.kt      |  4 +-
 .../minstrel/player/RemoteStallWatchdog.kt    | 13 +--
 .../minstrel/player/ResumeController.kt       |  4 +-
 .../minstrel/player/StreamTokenProvider.kt    |  2 +-
 .../minstrel/player/TransportObservation.kt   | 13 ++-
 .../player/gain/GainAudioProcessor.kt         |  4 +-
 .../minstrel/player/gain/GainMath.kt          |  4 +-
 .../minstrel/player/gain/ReplayGainStore.kt   |  2 +-
 .../player/output/OutputPickerController.kt   | 23 ++---
 .../minstrel/player/output/OutputRoute.kt     |  8 +-
 .../player/output/SonosQueueLoader.kt         | 33 +++----
 .../player/output/upnp/AVTransportClient.kt   | 18 ++--
 .../minstrel/player/ui/MiniPlayer.kt          |  5 +-
 .../minstrel/player/ui/NowPlayingScreen.kt    | 13 ++-
 .../minstrel/player/ui/QueueDragMath.kt       |  2 +-
 .../minstrel/player/ui/QueueRow.kt            | 26 +++---
 .../playlists/data/PlaylistPlayback.kt        |  2 +-
 .../playlists/data/PlaylistsRepository.kt     | 16 ++--
 .../playlists/ui/PlaylistDetailScreen.kt      | 16 ++--
 .../playlists/ui/PlaylistsListScreen.kt       |  2 +-
 .../playlists/widgets/OfflinePoolCard.kt      |  2 +-
 .../quarantine/data/QuarantineRepository.kt   |  6 +-
 .../quarantine/ui/HiddenTabViewModel.kt       |  9 +-
 .../requests/data/RequestsRepository.kt       |  5 +-
 .../minstrel/requests/ui/RequestsScreen.kt    |  5 +-
 .../minstrel/requests/ui/RequestsViewModel.kt | 10 +-
 .../minstrel/search/ui/SearchViewModel.kt     |  4 +-
 .../settings/data/NormalizationPrefs.kt       |  2 +-
 .../settings/data/NormalizationRepository.kt  |  4 +-
 .../settings/ui/AboutCardViewModel.kt         |  4 +-
 .../minstrel/settings/ui/NormalizationCard.kt |  2 +-
 .../minstrel/settings/ui/SettingsViewModel.kt |  2 +-
 .../minstrel/settings/ui/StorageCard.kt       | 14 +--
 .../fabledsword/minstrel/shared/ServerUrls.kt |  3 +-
 .../minstrel/shared/UpdateVeilController.kt   | 15 ++-
 .../shared/widgets/AppBarActionsViewModel.kt  |  2 +-
 .../minstrel/shared/widgets/CachedDot.kt      | 11 +--
 .../minstrel/shared/widgets/EmptyState.kt     |  2 +-
 .../minstrel/shared/widgets/LikeButton.kt     |  2 +-
 .../shared/widgets/MainAppBarActions.kt       |  6 +-
 .../shared/widgets/PullToRefreshScaffold.kt   |  4 -
 .../minstrel/shared/widgets/ServerImage.kt    |  4 +-
 .../minstrel/shared/widgets/ShellScaffold.kt  |  7 +-
 .../minstrel/shared/widgets/Skeletons.kt      |  7 +-
 .../minstrel/shared/widgets/TrackRow.kt       | 17 ++--
 .../trackactions/AddToPlaylistSheet.kt        |  4 +-
 .../widgets/trackactions/HideTrackSheet.kt    |  2 +-
 .../widgets/trackactions/TrackActionsSheet.kt |  4 +-
 .../minstrel/theme/FabledSwordTheme.kt        |  8 +-
 .../minstrel/theme/FabledSwordTokens.kt       | 12 +--
 .../minstrel/theme/MinstrelTheme.kt           |  8 +-
 .../fabledsword/minstrel/theme/Typography.kt  | 11 +--
 .../minstrel/update/api/ClientVersionApi.kt   |  3 +-
 .../minstrel/update/data/InstallOutcome.kt    | 16 ++--
 .../minstrel/update/data/SelfUpdateSession.kt | 10 +-
 .../update/data/UpdateBannerController.kt     |  8 +-
 .../minstrel/update/data/UpdateRepository.kt  | 17 ++--
 .../minstrel/update/ui/UpdateBanner.kt        | 14 +--
 .../src/main/res/drawable/ic_notification.xml |  2 +-
 .../main/res/xml/network_security_config.xml  | 11 +--
 .../admin/data/AdminRequestsRepositoryTest.kt |  2 +-
 .../minstrel/api/AuthCookieInterceptorTest.kt | 17 ++--
 .../minstrel/api/CleartextGuardTest.kt        |  2 +-
 .../auth/AuthStoreSessionVaultTest.kt         |  8 +-
 .../mutations/SupersededToggleIdsTest.kt      |  2 +-
 .../minstrel/cache/sync/SyncControllerTest.kt |  7 +-
 .../connectivity/ReachabilityMachineTest.kt   | 13 ++-
 .../diagnostics/TransportFlapDetectorTest.kt  |  2 +-
 .../minstrel/metadata/MetadataProviderTest.kt |  2 +-
 .../models/ArtistSuggestionReasonTest.kt      |  4 +-
 .../models/SuggestionSnoozeRefTest.kt         |  2 +-
 .../NotificationSettingsRepositoryTest.kt     |  2 +-
 .../data/NotificationsRepositoryTest.kt       |  2 +-
 .../minstrel/player/DropUnavailableTest.kt    |  2 +-
 .../minstrel/player/RemotePlayerStateTest.kt  |  2 +-
 .../player/output/SonosAlbumPlayTest.kt       |  2 +-
 .../player/output/upnp/SoapClientTest.kt      |  2 +-
 .../minstrel/player/ui/QueueDragMathTest.kt   |  2 +-
 .../data/PlaylistTrackAvailabilityTest.kt     |  2 +-
 .../data/NormalizationRepositoryTest.kt       |  2 +-
 .../shared/UpdateVeilControllerTest.kt        |  5 +-
 .../minstrel/theme/BundledFontsTest.kt        | 10 +-
 android/gradle/libs.versions.toml             |  2 +-
 228 files changed, 844 insertions(+), 1088 deletions(-)

diff --git a/android/app/build.gradle.kts b/android/app/build.gradle.kts
index e185e97e..0b0cf2a7 100644
--- a/android/app/build.gradle.kts
+++ b/android/app/build.gradle.kts
@@ -1,9 +1,9 @@
 plugins {
     alias(libs.plugins.android.application)
     // kotlin-android NOT applied: AGP 9 enables built-in Kotlin by default,
-    // and KSP 2.3.x supports it (PR #2674, merged Oct 2025). serialization
-    // + compose-compiler are language-level Kotlin compiler plugins and
-    // still need explicit application.
+    // and KSP 2.3.x supports it. serialization + compose-compiler are
+    // language-level Kotlin compiler plugins and still need explicit
+    // application.
     alias(libs.plugins.kotlin.serialization)
     alias(libs.plugins.compose.compiler)
     alias(libs.plugins.ksp)
@@ -31,14 +31,9 @@ android {
         //
         // versionCode is minutes since 2020-01-01 at BUILD time. It is the
         // value the platform decides installs by, so it must be monotonic by
-        // construction.
-        //
-        // This comment used to say versionCode was a commit count and that it
-        // was "monotonic forever". It was neither — a commit count runs ahead
-        // on `dev`, so a dev build outranked the `main` release meant to
-        // replace it and Android refused the install as a downgrade. Worth
-        // knowing the claim was here, stated as a reassurance, while the bug
-        // it denied was live.
+        // construction. Not a commit count: that runs ahead on `dev`, so a dev
+        // build would outrank the `main` release meant to replace it and
+        // Android would refuse the install as a downgrade.
         val versionNameOverride =
             (project.findProperty("MINSTREL_VERSION_NAME") as String?)?.takeIf { it.isNotBlank() }
         val versionCodeOverride =
@@ -73,9 +68,9 @@ android {
                 "proguard-rules.pro",
             )
             // Signed with the release key or not at all. Falling back to the
-            // debug key made a missing secret into a published APK that no
-            // install could ever update (family idea #5103, practice 2). An
-            // unsigned build installs nowhere, so the gap shows at once.
+            // debug key would turn a missing secret into a published APK that no
+            // install could ever update. An unsigned build installs nowhere, so
+            // the gap shows at once.
             signingConfig =
                 if (System.getenv("ANDROID_KEYSTORE_PATH").isNullOrEmpty()) {
                     null
diff --git a/android/app/src/main/AndroidManifest.xml b/android/app/src/main/AndroidManifest.xml
index a23ca32d..cd8f9563 100644
--- a/android/app/src/main/AndroidManifest.xml
+++ b/android/app/src/main/AndroidManifest.xml
@@ -8,7 +8,7 @@
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
-    <!-- Notifications when the app is closed (M489 #5347): the delivery
+    <!-- Notifications when the app is closed: the delivery
          service, and starting it again after a reboot or an update. -->
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
     <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
@@ -84,11 +84,8 @@
             </intent-filter>
         </receiver>
 
-        <!-- The FileProvider that used to live here existed solely to expose the
-             downloaded update APK as a content:// URI for the old ACTION_VIEW
-             install intent. A PackageInstaller session takes a stream instead,
-             so both the provider and res/xml/file_paths.xml are gone — nothing
-             else in the app ever used that authority. -->
+        <!-- No FileProvider: the self-update streams the downloaded APK into a
+             PackageInstaller session, so nothing needs a content:// URI. -->
 
         <!-- On-demand WorkManager initialization: MinstrelApplication
              implements Configuration.Provider and supplies the
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/MainActivity.kt b/android/app/src/main/java/com/fabledsword/minstrel/MainActivity.kt
index b21e12dc..cb90f2e4 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/MainActivity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/MainActivity.kt
@@ -106,7 +106,7 @@ class MainActivity : ComponentActivity() {
     }
 
     /**
-     * Android 13+ asks before an app may post notifications (M489 #5347).
+     * Android 13+ asks before an app may post notifications.
      * Asked once delivery is wanted (signed in, background delivery on),
      * each launch until answered: after a second "no" the system stops
      * showing the prompt by itself, and Settings → Notifications links to
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/MinstrelApplication.kt b/android/app/src/main/java/com/fabledsword/minstrel/MinstrelApplication.kt
index 9c1c0f89..8229d0e8 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/MinstrelApplication.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/MinstrelApplication.kt
@@ -79,7 +79,7 @@ class MinstrelApplication :
     /**
      * Same construct-the-singleton trick — DeliveryLauncher starts and stops
      * the background-delivery service and runs the notification catch-up on
-     * every nudge and reconnect (M489 #5347). Without this @Inject no phone
+     * every nudge and reconnect. Without this @Inject no phone
      * notification would ever be posted.
      */
     @Suppress("unused") @Inject lateinit var deliveryLauncher: DeliveryLauncher
@@ -171,7 +171,7 @@ class MinstrelApplication :
      */
     @Suppress("unused") @Inject lateinit var liveEventsDispatcher: LiveEventsDispatcher
 
-    // Device diagnostics (M9). The reporter gates itself on the account's
+    // Device diagnostics. The reporter gates itself on the account's
     // debug flag; the uploader drains its buffer on a tick / recovery.
     @Suppress("unused") @Inject lateinit var diagnosticsReporter: DiagnosticsReporter
     @Suppress("unused") @Inject lateinit var diagnosticsUploader: DiagnosticsUploader
@@ -181,7 +181,7 @@ class MinstrelApplication :
     override fun onCreate() {
         super.onCreate()
         // Debug builds get the full DebugTree (verbose). Release builds
-        // get a WARN+ tree so operator-driven diagnosis via `adb logcat`
+        // get a WARN+ tree so diagnosis via `adb logcat`
         // still surfaces UPnP / cast failures, OkHttp errors, and our
         // own Timber.w / Timber.e calls — without the chatty DEBUG /
         // INFO traffic flooding the buffer in production.
@@ -229,10 +229,9 @@ class MinstrelApplication :
      * before Coil makes its first request.
      *
      * Crossfade is set here rather than per-call so every cover surface
-     * in the app fades its artwork in instead of snapping it. Art
-     * landing a beat after its tile was the most visible pop-in on Home
-     * (issue #2327); `ServerImage` fades its placeholder out over the
-     * same window so the two read as one cross-dissolve.
+     * in the app fades its artwork in instead of snapping it, and
+     * `ServerImage` fades its placeholder out over the same window so the
+     * two read as one cross-dissolve.
      */
     override fun newImageLoader(context: android.content.Context): ImageLoader =
         ImageLoader.Builder(context)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminQuarantineRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminQuarantineRepository.kt
index 523d5dad..b1bea272 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminQuarantineRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminQuarantineRepository.kt
@@ -11,10 +11,9 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Read-through accessor for the admin quarantine queue. Mirrors the
- * Flutter `AdminQuarantineController`. No Room cache — same rationale
- * as AdminRequests. Three resolution actions all delete the row from
- * the queue once the server accepts them.
+ * Read-through accessor for the admin quarantine queue. No Room cache —
+ * same rationale as AdminRequests. Three resolution actions all delete
+ * the row from the queue once the server accepts them.
  */
 @Singleton
 class AdminQuarantineRepository @Inject constructor(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminRequestsRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminRequestsRepository.kt
index 2d0afb55..9c4c94cc 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminRequestsRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminRequestsRepository.kt
@@ -14,7 +14,7 @@ import javax.inject.Singleton
  *
  * No Room caching — admin actions are infrequent and don't benefit
  * from offline scrollback. `approve` and `reject` fire direct REST
- * (no mutation queue) because operator confirmation is point-and-shoot;
+ * (no mutation queue) because admin confirmation is point-and-shoot;
  * if the request fails the UI surfaces the error and rolls back.
  */
 @Singleton
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminTagSourcesRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminTagSourcesRepository.kt
index 9a6e9416..ddd115a1 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminTagSourcesRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminTagSourcesRepository.kt
@@ -12,7 +12,7 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Read-through accessor for the tag-enrichment provider settings (#1521).
+ * Read-through accessor for the tag-enrichment provider settings.
  * No Room caching — admin settings are infrequent point-and-shoot edits;
  * mutations fire direct REST and the ViewModel reconciles on failure.
  * Exceptions propagate to the ViewModel (which maps them via ErrorCopy).
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminUsersRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminUsersRepository.kt
index 02d609e7..b45a2dbe 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminUsersRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/admin/data/AdminUsersRepository.kt
@@ -13,8 +13,8 @@ import javax.inject.Singleton
 
 /**
  * Read-through accessor for the admin users list + the four per-user
- * mutations. Mirrors Flutter's `AdminUsersController`. Same
- * no-Room-cache, no-MutationQueue pattern as the other admin slices.
+ * mutations. Same no-Room-cache, no-MutationQueue pattern as the other
+ * admin repositories.
  */
 @Singleton
 class AdminUsersRepository @Inject constructor(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminInvitesViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminInvitesViewModel.kt
index e1f6a956..ab7ddaec 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminInvitesViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminInvitesViewModel.kt
@@ -39,7 +39,7 @@ class AdminInvitesViewModel @Inject constructor(
 
     init {
         refresh()
-        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // Screen-level auto-recovery: reload a failed list
         // when server health returns instead of waiting for a manual pull.
         viewModelScope.launch {
             networkStatus.recoveries().collect {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminQuarantineViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminQuarantineViewModel.kt
index 510c9c83..b233a459 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminQuarantineViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminQuarantineViewModel.kt
@@ -40,8 +40,8 @@ class AdminQuarantineViewModel @Inject constructor(
     /**
      * One-shot messages for the screen's snackbar. A failed action has to say
      * why: the row quietly reappearing reads as a glitch, and for a Delete
-     * file refused by a read-only library it hides the one thing the
-     * operator can fix (#3918).
+     * file refused by a read-only library it hides the one thing an
+     * admin can fix.
      */
     private val transientMessagesChannel = Channel<String>(Channel.BUFFERED)
     val transientMessages: Flow<String> = transientMessagesChannel.receiveAsFlow()
@@ -53,7 +53,7 @@ class AdminQuarantineViewModel @Inject constructor(
                 .filter { it.kind.startsWith("quarantine.") }
                 .collect { refresh() }
         }
-        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // Screen-level auto-recovery: reload a failed list
         // when server health returns instead of waiting for a manual pull.
         viewModelScope.launch {
             networkStatus.recoveries().collect {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminRequestsViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminRequestsViewModel.kt
index c265924a..a01a9509 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminRequestsViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminRequestsViewModel.kt
@@ -43,7 +43,7 @@ class AdminRequestsViewModel @Inject constructor(
                 .filter { it.kind in RELEVANT_EVENT_KINDS }
                 .collect { refresh() }
         }
-        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // Screen-level auto-recovery: reload a failed list
         // when server health returns instead of waiting for a manual pull.
         viewModelScope.launch {
             networkStatus.recoveries().collect {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminTagSourcesViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminTagSourcesViewModel.kt
index 53cbdfaa..f56039b3 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminTagSourcesViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminTagSourcesViewModel.kt
@@ -38,7 +38,7 @@ class AdminTagSourcesViewModel @Inject constructor(
     init {
         refresh()
         // Screen-level auto-recovery: reload a failed list when server
-        // health returns instead of waiting for a manual pull (issue #1245).
+        // health returns instead of waiting for a manual pull.
         viewModelScope.launch {
             networkStatus.recoveries().collect {
                 if (internal.value is AdminTagSourcesUiState.Error) refresh()
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminUsersViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminUsersViewModel.kt
index 029c0a34..000d86c7 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminUsersViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/admin/ui/AdminUsersViewModel.kt
@@ -33,7 +33,7 @@ class AdminUsersViewModel @Inject constructor(
 
     init {
         refresh()
-        // Screen-level auto-recovery (issue #1245): reload a failed list
+        // Screen-level auto-recovery: reload a failed list
         // when server health returns instead of waiting for a manual pull.
         viewModelScope.launch {
             networkStatus.recoveries().collect {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/AuthCookieInterceptor.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/AuthCookieInterceptor.kt
index 3365e5cf..b31d21ef 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/AuthCookieInterceptor.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/AuthCookieInterceptor.kt
@@ -12,18 +12,12 @@ import javax.inject.Singleton
  * flow), and clears the store on 401 so downstream code can react
  * to logout.
  *
- * Mirrors the Flutter Dio interceptor pattern.
- *
  * Scoped to the [BaseUrlInterceptor.PLACEHOLDER_HOST] sentinel host
- * the same way BaseUrlInterceptor is. Drift #568 / #569 caught two
- * leaks here: (1) the session cookie was being attached to every
- * external request the shared OkHttpClient services — including
- * Coil image fetches to artwork.musicbrainz.org / coverartarchive.org
- * — exposing the session
- * identifier to third-party logging; (2) a 401 from any of those
- * external hosts silently wiped the user's Minstrel session.
- * Restricting both attach + clear to placeholder-host requests
- * closes both gaps.
+ * the same way BaseUrlInterceptor is. The shared OkHttpClient also
+ * serves Coil's image fetches to external hosts such as
+ * artwork.musicbrainz.org and coverartarchive.org; unscoped, this
+ * would hand the session identifier to third-party logging, and a 401
+ * from any of those hosts would sign the user out of Minstrel.
  */
 @Singleton
 class AuthCookieInterceptor @Inject constructor(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/BaseUrlInterceptor.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/BaseUrlInterceptor.kt
index 7269cd2a..1c4be42d 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/BaseUrlInterceptor.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/BaseUrlInterceptor.kt
@@ -17,15 +17,14 @@ import javax.inject.Singleton
  *
  * This interceptor closes the gap: Retrofit can stay built with the
  * placeholder forever, and every actual Minstrel-bound request gets
- * retargeted at the live AuthStore value. Lets the user change
- * server URL in Settings without an app relaunch (Phase 11 wiring).
+ * retargeted at the live AuthStore value, so the user can change the
+ * server URL in Settings without an app relaunch.
  *
  * Only requests whose host is the [PLACEHOLDER_HOST] sentinel are
  * rewritten. Absolute external URLs — artwork from
  * artwork.musicbrainz.org / coverartarchive.org, for example — must
- * reach their authored host unchanged; rewriting them to the
- * Minstrel host produced 404s the user saw as missing Discover
- * suggestion covers.
+ * reach their authored host unchanged: rewritten to the Minstrel host
+ * they 404, and Discover suggestions show no covers.
  *
  * No-op when the stored base URL is unparseable (falls through to
  * whatever Retrofit had) — that case shows up as a transport-level
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/CleartextGuard.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/CleartextGuard.kt
index e60857c2..83dd29ce 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/CleartextGuard.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/CleartextGuard.kt
@@ -16,11 +16,10 @@ object MinstrelServerRequest
 
 /**
  * Plain `http://` to the Minstrel server is allowed only when the connection
- * actually lands on a private address (family security baseline #5105,
- * practice 13).
+ * actually lands on a private address.
  *
  * Cleartext stays permitted app-wide for LAN servers and UPnP
- * (network_security_config.xml, #2439), but a password or session cookie sent
+ * (network_security_config.xml), but a password or session cookie sent
  * over plain HTTP to a public address can be read by anyone on the path.
  *
  * Checked per connection, on the address the socket really reached, not on
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/ErrorCopy.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/ErrorCopy.kt
index 7cdc8cf4..19cd5771 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/ErrorCopy.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/ErrorCopy.kt
@@ -44,9 +44,9 @@ object ErrorCopy {
     }
 
     /**
-     * Codes whose server message carries specifics the operator needs in
+     * Codes whose server message carries specifics an admin needs in
      * order to act — which directory, which uid — that fixed copy cannot say.
-     * For these the message follows the copy (#3918). Kept to a named set on
+     * For these the message follows the copy. Kept to a named set on
      * purpose: most server messages are internal detail. Mirrors web's
      * errors.ts.
      */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/NetworkModule.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/NetworkModule.kt
index 475b2842..aa8eef2d 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/NetworkModule.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/NetworkModule.kt
@@ -57,16 +57,15 @@ object NetworkModule {
             .addInterceptor(reachability)
             // AuthCookieInterceptor MUST run before BaseUrlInterceptor.
             // Both scope on `host == PLACEHOLDER_HOST` to distinguish
-            // Minstrel-server requests from external image fetches
-            // (drift #568 / #569). If BaseUrlInterceptor runs first it
-            // rewrites the host to the real server before auth sees the
-            // request, auth's placeholder check fails, and the session
-            // cookie is neither attached on outgoing requests nor
-            // captured from Set-Cookie on login — fresh installs get
-            // stuck at the Welcome screen. Auth first means it sees
+            // Minstrel-server requests from external image fetches. If
+            // BaseUrlInterceptor runs first it rewrites the host to the real
+            // server before auth sees the request, auth's placeholder check
+            // fails, and the session cookie is neither attached on outgoing
+            // requests nor captured from Set-Cookie on login — fresh installs
+            // get stuck at the Welcome screen. Auth first means it sees
             // placeholder.invalid, attaches/captures correctly, then
-            // BaseUrlInterceptor retargets to the live AuthStore host
-            // for transport.
+            // BaseUrlInterceptor retargets to the live AuthStore host for
+            // transport.
             .addInterceptor(auth)
             .addInterceptor(baseUrl)
             .addInterceptor(logging)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminInvitesApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminInvitesApi.kt
index b0af65c1..dd64bc8c 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminInvitesApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminInvitesApi.kt
@@ -27,9 +27,8 @@ interface AdminInvitesApi {
 }
 
 /**
- * Body for `POST /api/admin/invites`. The Flutter client omits the
- * field when note is empty; Kotlin/serialization just serializes
- * null which the server treats identically.
+ * Body for `POST /api/admin/invites`. An empty note is sent as null,
+ * which the server treats the same as an absent field.
  */
 @Serializable
 data class CreateInviteBody(val note: String? = null)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminTagSourcesApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminTagSourcesApi.kt
index e02ebeec..b7f0a96a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminTagSourcesApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/AdminTagSourcesApi.kt
@@ -12,9 +12,9 @@ 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
+ * Retrofit interface for `/api/admin/tag-sources` — the admin surface
+ * for the tag-enrichment provider settings. 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.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/CastApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/CastApi.kt
index 0e2fb3d6..736cfbb8 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/CastApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/CastApi.kt
@@ -30,7 +30,7 @@ interface CastApi {
  * the 21_600 default (6h) is long enough to play through any typical
  * track without re-minting mid-playback.
  *
- * [level] asks for the leveled stream (M464 #5001): the track rendered at
+ * [level] asks for the leveled stream: the track rendered at
  * the user's loudness gain, which the server works out from their setting.
  * [asAlbum] says the track plays among its album in order, which picks
  * album gain in auto mode. [prerender] says the speaker will fetch it
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiagnosticsApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiagnosticsApi.kt
index b6edd751..38e91dd7 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiagnosticsApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiagnosticsApi.kt
@@ -7,7 +7,7 @@ import retrofit2.http.Body
 import retrofit2.http.POST
 
 /**
- * Retrofit interface for device diagnostics ingest (M9). One call
+ * Retrofit interface for device diagnostics ingest. One call
  * uploads a batch of buffered events. The server stores them only when
  * the account's debug_mode_enabled flag is on (it returns 204 otherwise,
  * which the uploader treats as success so it can drop the batch).
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiscoverApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiscoverApi.kt
index 6e4bddc6..899b9bd0 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiscoverApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/DiscoverApi.kt
@@ -19,8 +19,7 @@ import retrofit2.http.Query
  * second, so the Discover screen searches when the query is submitted,
  * not on every keystroke.
  *
- * Cancel + my-requests-list endpoints live on RequestsApi (Phase 10
- * Commit B), not here.
+ * Cancel + my-requests-list endpoints live on RequestsApi, not here.
  */
 interface DiscoverApi {
     @GET("api/discover/suggestions")
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/LibraryApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/LibraryApi.kt
index 5f16721f..4bccddfc 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/LibraryApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/LibraryApi.kt
@@ -56,16 +56,15 @@ interface LibraryApi {
     @GET("api/library/shuffle")
     suspend fun shuffleLibrary(@Query("limit") limit: Int = 100): List<TrackWire>
 
-    // Browse axes (#367). Both indexes are unpaged by design: the client needs
+    // Browse axes. Both indexes are unpaged by design: the client needs
     // the whole set to render a browsable picker, and even a messy library
     // yields hundreds of rows, not thousands.
     //
-    // These read the server rather than the local cache on purpose. The cache
-    // is a full mirror of the library, but /api/library/sync ships tracks whose
-    // files are missing and carries no flag for it (#2704), while the browse
-    // index filters them out -- so a locally-computed index would disagree with
-    // the server's and with the web client. One source of truth wins over
-    // offline capability here until #2704 is resolved.
+    // These read the server rather than the local cache on purpose: the
+    // server's index leaves out tracks whose files are missing and is the
+    // one the web client shows, so the two clients agree. The cache carries
+    // the same mark (cached_tracks.missing), but an index built from it
+    // would be a second copy of the server's grouping that could drift.
     @GET("api/library/genres")
     suspend fun getGenres(): List<GenreCountWire>
 
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/MeApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/MeApi.kt
index 3962bd2c..ce6d6589 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/MeApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/MeApi.kt
@@ -92,9 +92,7 @@ data class ChangePasswordRequest(
 
 /**
  * Body for `PUT /api/me/listenbrainz`. Either `token` or `enabled`
- * is set; the server treats other fields as untouched. Mirrors
- * Flutter's `setListenBrainzToken` / `setListenBrainzEnabled` split
- * over a single endpoint shape.
+ * is set; the server treats other fields as untouched.
  */
 @Serializable
 data class ListenBrainzPutBody(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/NotificationsApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/NotificationsApi.kt
index 74e48aa7..942817fe 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/NotificationsApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/NotificationsApi.kt
@@ -10,7 +10,7 @@ import retrofit2.http.Path
 import retrofit2.http.Query
 
 /**
- * The notifications inbox and its per-user settings (M489). The server
+ * The notifications inbox and its per-user settings. The server
  * renders each notice's title, body and link, so the app shows them as given.
  */
 interface NotificationsApi {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/PlaylistsApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/PlaylistsApi.kt
index 6844baa1..5bb8a9a5 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/PlaylistsApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/PlaylistsApi.kt
@@ -49,7 +49,7 @@ interface PlaylistsApi {
     suspend fun refreshSystem(@Path("kind") variant: String): RefreshSystemResponse
 
     /**
-     * GET /api/playlists/system/{kind}/shuffle (#415 / #411 R2). Returns
+     * GET /api/playlists/system/{kind}/shuffle. Returns
      * the system playlist's tracks in rotation-aware order without
      * rebuilding — used by the Home play-button overlay so taps on For
      * You / Discover / Today's mix advance rotation rather than picking
@@ -60,8 +60,8 @@ interface PlaylistsApi {
 }
 
 /**
- * POST /api/playlists/{id}/tracks body. Server expects snake_case
- * `track_ids` per the Flutter wire shape.
+ * POST /api/playlists/{id}/tracks body. The server expects snake_case
+ * `track_ids`.
  */
 @Serializable
 data class AppendTracksRequest(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/QuarantineApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/QuarantineApi.kt
index 91f40d4b..fbc6314d 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/QuarantineApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/QuarantineApi.kt
@@ -13,7 +13,7 @@ import retrofit2.http.Path
  *
  * Both flag and unflag are user-scoped — callers act on their own
  * quarantine entries. The cross-user admin surface is a separate
- * `/api/admin/quarantine` route (Phase 10 Commit D).
+ * `/api/admin/quarantine` route.
  */
 interface QuarantineApi {
     @GET("api/quarantine/mine")
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/ReplayGainApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/ReplayGainApi.kt
index d6356c87..4e83ea27 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/ReplayGainApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/ReplayGainApi.kt
@@ -4,7 +4,7 @@ import com.fabledsword.minstrel.models.wire.ReplayGainResponseWire
 import retrofit2.http.GET
 import retrofit2.http.Query
 
-/** The player's loudness lookup (#4997), kept apart from the browse surface in [LibraryApi]. */
+/** The player's loudness lookup, kept apart from the browse surface in [LibraryApi]. */
 interface ReplayGainApi {
     /**
      * ReplayGain values for up to 200 comma-separated track ids. An id
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/RequestsApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/RequestsApi.kt
index dd24e0b5..700b92a8 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/RequestsApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/RequestsApi.kt
@@ -10,7 +10,7 @@ import retrofit2.http.Path
  *
  * Server scopes results to the caller — admins see only their own
  * requests through this endpoint. The cross-user admin view lives on
- * a separate `/api/admin/requests` route (Phase 10 Commit D).
+ * a separate `/api/admin/requests` route.
  *
  * The DELETE endpoint returns the cancelled row (not 204) so the UI
  * can patch local state without a refetch.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/SyncApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/SyncApi.kt
index 4baf1783..4020a649 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/SyncApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/api/endpoints/SyncApi.kt
@@ -6,7 +6,7 @@ import retrofit2.http.GET
 import retrofit2.http.Query
 
 /**
- * Retrofit interface for `/api/library/sync` (#357). The endpoint
+ * Retrofit interface for `/api/library/sync`. The endpoint
  * returns three possible status codes that the SyncController
  * branches on:
  *   - 200: parsed body with cursor + upserts + deletes
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/auth/AuthController.kt b/android/app/src/main/java/com/fabledsword/minstrel/auth/AuthController.kt
index 440efd8c..eb70e0a9 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/auth/AuthController.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/auth/AuthController.kt
@@ -57,7 +57,7 @@ class AuthController @Inject constructor(
             }
         }
         // Refresh from /api/me on startup so a remotely-changed account
-        // flag (e.g. admin enabling debug mode, M9) reaches the device
+        // flag (e.g. an admin enabling debug mode) reaches the device
         // without a re-login. Best-effort; failures keep the cached value.
         scope.launch { refreshProfile() }
     }
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/auth/AuthStore.kt b/android/app/src/main/java/com/fabledsword/minstrel/auth/AuthStore.kt
index d043018f..e4fb4c4f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/auth/AuthStore.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/auth/AuthStore.kt
@@ -35,13 +35,13 @@ import javax.inject.Singleton
  * sees the new value immediately; the DAO write coroutine catches up
  * shortly after.
  *
- * **The session cookie is the exception** (M462 #4985): it is persisted
- * through [SessionVault] (Keystore-encrypted), not the Room row. On the
- * first launch after the upgrade, a cookie still in the row is moved into
- * the vault and the column cleared, so nobody is signed out by the change.
- * If the Keystore cannot be used on a device, the cookie stays in the row
- * as before rather than being lost. [awaitSessionHydrated] lets a caller
- * that needs a definitive answer (the auth gate) wait for this.
+ * **The session cookie is the exception**: it is persisted through
+ * [SessionVault] (Keystore-encrypted), not the Room row. A cookie still
+ * in the row is moved into the vault on launch and the column cleared,
+ * so nobody is signed out by the move. If the Keystore cannot be used
+ * on a device, the cookie stays in the row rather than being lost.
+ * [awaitSessionHydrated] lets a caller that needs a definitive answer
+ * (the auth gate) wait for this.
  */
 // AuthStore is the single-row facade over auth_session (de-facto
 // app_preferences — see entity comment). It legitimately owns one
@@ -81,7 +81,7 @@ class AuthStore @Inject constructor(
     private val normalizationState = MutableStateFlow(NormalizationPrefs.DEFAULT)
     val normalization: StateFlow<NormalizationPrefs> = normalizationState.asStateFlow()
 
-    // Background delivery (M489 #5347): the device's choice, on by default.
+    // Background delivery: the device's choice, on by default.
     // The shade's high-water mark lives in the same row but is read and
     // written through the DAO by NotificationSync, awaited, never cached here.
     private val backgroundDeliveryState = MutableStateFlow(true)
@@ -131,8 +131,8 @@ class AuthStore @Inject constructor(
 
     /**
      * Suspends until the stored session cookie has been loaded into
-     * [sessionCookie], or [HYDRATION_DEADLINE_MS] passes (rule 156: a wedged
-     * Keystore must not leave the start screen spinning). Returns false on
+     * [sessionCookie], or [HYDRATION_DEADLINE_MS] passes, so a wedged
+     * Keystore cannot leave the start screen spinning. Returns false on
      * the deadline; the caller then decides from whatever has loaded, and a
      * late hydration still lands in [sessionCookie].
      */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/auth/SessionVault.kt b/android/app/src/main/java/com/fabledsword/minstrel/auth/SessionVault.kt
index 72e7a236..25ab5c44 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/auth/SessionVault.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/auth/SessionVault.kt
@@ -19,15 +19,14 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Where the session cookie lives at rest (M462 #4985).
+ * Where the session cookie lives at rest.
  *
  * The cookie is a bearer credential: anyone holding it is signed in as the
- * user until the server expires or revokes it. It used to sit in plain text
- * in the Room `auth_session` row, readable from any copy of the app's data
- * directory (a rooted device, an adb backup of a debuggable build, a
- * forensic image). Now only ciphertext is stored, under an AES key that
- * lives in the Android Keystore and never leaves it, so a copy of the
- * files alone yields nothing usable.
+ * user until the server expires or revokes it. In plain text it would be
+ * readable from any copy of the app's data directory (a rooted device, an
+ * adb backup of a debuggable build, a forensic image). Only ciphertext is
+ * stored, under an AES key that lives in the Android Keystore and never
+ * leaves it, so a copy of the files alone yields nothing usable.
  */
 interface SessionVault {
     /** The stored cookie, or null when none is stored or it can't be decrypted. */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/auth/ui/AuthGateViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/auth/ui/AuthGateViewModel.kt
index 0ccd82d5..39d228bb 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/auth/ui/AuthGateViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/auth/ui/AuthGateViewModel.kt
@@ -19,8 +19,8 @@ import javax.inject.Inject
  * persisted auth state. Reads the row from AuthSessionDao directly, and
  * the session cookie only after [AuthStore.awaitSessionHydrated]: both
  * StateFlows default to null until their async load lands, and we need a
- * definitive answer before drawing any nav graph. The cookie is no longer
- * in the row (it lives in the Keystore-backed SessionVault, #4985).
+ * definitive answer before drawing any nav graph. The cookie lives in the
+ * Keystore-backed SessionVault, not the row.
  *
  *   - no row at all          → ServerUrl   (first launch)
  *   - row with baseUrl, no cookie → Login   (URL configured, not yet signed in)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/CacheIndexer.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/CacheIndexer.kt
index f8168f2a..e7ace5ed 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/CacheIndexer.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/CacheIndexer.kt
@@ -18,15 +18,13 @@ import javax.inject.Singleton
  * Populates `audio_cache_index` from playback so the offline pools
  * ([ShuffleSource]) and the cached indicator have a data source.
  *
- * Mirrors the user-visible behavior of Flutter's `AudioCacheManager`
- * (`registerStreamCache` + `touch`): a track you play gets cached as a
- * side effect of streaming, and playing it bumps its recency. The
- * Android idiom differs intentionally — Media3's `SimpleCache` is the
- * real byte store (span-based, keyed by trackId via the MediaItem's
- * custom cache key), so this index is a lightweight *play-recency*
- * record (source = INCIDENTAL) rather than Flutter's file-per-track
- * table. SimpleCache stays the source of truth for "is it actually on
- * disk"; this index orders "recently played" for the offline pools.
+ * A track you play gets cached as a side effect of streaming, and
+ * playing it bumps its recency. Media3's `SimpleCache` is the real byte
+ * store (span-based, keyed by trackId via the MediaItem's custom cache
+ * key), so this index is a lightweight *play-recency* record
+ * (source = INCIDENTAL), not a file-per-track table. SimpleCache stays
+ * the source of truth for "is it actually on disk"; this index orders
+ * "recently played" for the offline pools.
  *
  * State observed against [PlayerController.uiState], deduped by track
  * id so each entry into the player records once. Eager-constructed via
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/ShuffleSource.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/ShuffleSource.kt
index d64a3f0a..1f742912 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/ShuffleSource.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/ShuffleSource.kt
@@ -19,11 +19,10 @@ private const val POOL_LIMIT = 100
  * storage/eviction-only and never filters playback — exactly what
  * this relies on.
  *
- * Divergence note: Flutter's `audioCacheIndex` only holds fully-cached
- * tracks, so its pools are inherently resident. Android's index records
- * plays (see `CacheIndexer`), so the recency list is intersected with
- * true Media3 SimpleCache residency here — the pool never offers a
- * played-then-evicted track that would fail to play offline.
+ * The index records plays (see `CacheIndexer`), not residency, so the
+ * recency list is intersected with true Media3 SimpleCache residency
+ * here — the pool never offers a played-then-evicted track that would
+ * fail to play offline.
  *
  * Surfaced on Home's Playlists row only when offline; tap shuffles +
  * plays the pool from the cache.
@@ -58,7 +57,7 @@ class ShuffleSource @Inject constructor(
         if (orderedIds.isEmpty()) return emptyList()
         val byId = trackDao.getByIds(orderedIds).associateBy { it.id }
         return orderedIds.mapNotNull { id ->
-            // Clear the server's missing mark (#2704). Every id reaching here
+            // Clear the server's missing mark. Every id reaching here
             // came through residentIdsByRecency, which already proved the
             // AUDIO is in the local cache — so these play regardless of what
             // the server has lost, and the queue filter in PlayerController
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheConfig.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheConfig.kt
index 6b20c669..b082bf65 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheConfig.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheConfig.kt
@@ -1,16 +1,16 @@
 package com.fabledsword.minstrel.cache.audiocache
 
 /**
- * Defaults for the 2-bucket audio cache.
+ * Defaults for the audio cache; the user's Storage settings override them.
  *
- *  - `likedCapBytes`: cap for the protected bucket — cached files for
- *    tracks the user has liked. Evicted only after the rolling bucket
- *    is fully drained (almost never under normal use).
- *  - `rollingCapBytes`: cap for the unprotected bucket — incidental /
- *    auto-prefetch downloads. LRU within this bucket.
+ *  - `likedCapBytes`: cap meant for a protected bucket of liked tracks'
+ *    files. Nothing enforces it yet; SimpleCache evicts by the rolling
+ *    cap alone.
+ *  - `rollingCapBytes`: cap for incidental / auto-prefetch downloads,
+ *    evicted least-recently-used first.
  *
- * Phase 11 (Settings) will allow user overrides; the values are kept
- * generous so first-time installs work well without configuration.
+ * The values are generous so first-time installs work well without
+ * configuration.
  */
 data class CacheConfig(
     val likedCapBytes: Long = DEFAULT_LIKED_CAP_BYTES,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheSettings.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheSettings.kt
index 4e576cf9..32db9ce7 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheSettings.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/audiocache/CacheSettings.kt
@@ -10,18 +10,18 @@ private const val DEFAULT_PREFETCH_WINDOW = 5
  * blob on the auth_session single-row table via [AuthStore].
  *
  * - [likedCapBytes]: budget for cached files of liked tracks. 0 means
- *   unlimited. Effective at next app start (SimpleCache is built once
- *   per process).
+ *   unlimited. Nothing enforces it yet: SimpleCache evicts by
+ *   [rollingCapBytes] alone, and the Storage card hides this control.
  * - [rollingCapBytes]: budget for incidental / auto-prefetch downloads.
- *   Same 0=unlimited / restart-to-apply caveat.
- * - [prefetchWindow]: 1..10. Number of next-tracks the prefetcher
- *   pre-downloads. Has no effect until the prefetcher lands (separate
- *   audit follow-up) — persisted now so the user can pre-configure.
+ *   0 means unlimited. Effective at next app start (SimpleCache is
+ *   built once per process).
+ * - [prefetchWindow]: 1..10. Number of next-tracks `AudioPrefetcher`
+ *   pre-downloads.
  * - [cacheLikedTracks]: when true, liking a track should also pin its
- *   audio to the liked-cache bucket. Has no effect until pin-on-like
- *   lands (separate follow-up).
+ *   audio to the liked-cache bucket. Nothing reads it yet, and the
+ *   Storage card hides this control.
  *
- * Defaults match Flutter: 5 GiB per bucket, prefetch=5, cache-liked=true.
+ * Defaults: 5 GiB per bucket, prefetch=5, cache-liked=true.
  */
 @Serializable
 data class CacheSettings(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/AppDatabase.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/AppDatabase.kt
index 9a4b2cac..90433c9d 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/AppDatabase.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/AppDatabase.kt
@@ -40,17 +40,12 @@ import com.fabledsword.minstrel.cache.db.entities.DiagnosticEventEntity
 import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity
 
 /**
- * Single Room database for the whole app. Mirrors the Flutter client's
- * Drift `AppDb` — same logical schema, one entity-family per @Entity.
+ * Single Room database for the whole app, one entity family per @Entity.
  *
- * Native v1 starts at schema version 1 (the Flutter Drift schemaVersion 11
- * is an internal client detail; the server is the source of truth and the
- * sync controller refills on first launch). Future schema bumps land per
- * change with explicit `Migration` entries; `fallbackToDestructiveMigration`
- * in `DatabaseModule` is the safety net while we're pre-v1.
- *
- * Entity families land in Task 4.2 slices. The set will grow until the
- * whole Drift schema is mirrored.
+ * The server is the source of truth: the sync controller refills the
+ * cache on first launch. Schema bumps land with explicit `Migration`
+ * entries; `fallbackToDestructiveMigration` in `DatabaseModule` rebuilds
+ * the database from a version that has no migration path.
  */
 @Database(
     entities = [
@@ -73,25 +68,25 @@ import com.fabledsword.minstrel.cache.db.entities.SyncMetadataEntity
         CachedNotificationSettingsEntity::class,
     ],
     // v12: + auth_session.backgroundDelivery and notifiedUpTo, the device's
-    // background-delivery choice and its shade high-water mark (M489 #5347).
+    // background-delivery choice and its shade high-water mark.
     // v11: + cached_notifications and cached_notification_settings, the
-    // notifications inbox and its settings (M489). MIGRATION_10_11 creates
+    // notifications inbox and its settings. MIGRATION_10_11 creates
     // both; nothing to backfill, the first refresh fills them.
     // v10: + cached_tracks.trackGain/trackPeak and cached_albums.albumGain/
-    // albumPeak, the ReplayGain values the player levels by (M464 #5000).
+    // albumPeak, the ReplayGain values the player levels by.
     // MIGRATION_9_10 also rewinds the sync cursor, so the next sync re-sends
     // every row and an existing cache gains its values.
     // v9: + auth_session.normalizationJson, the loudness-normalization
-    // preference (M464 #4998). The first schema step with an explicit
-    // Migration (MIGRATION_8_9): a destructive rebuild would also wipe this
-    // row — the server address and theme — and the queued offline writes,
+    // preference. The first schema step with an explicit Migration
+    // (MIGRATION_8_9): a destructive rebuild would also wipe this row —
+    // the server address and theme — and the queued offline writes,
     // which is too much to lose for one added column.
-    // v8: + cached_tracks.missing, the server's missing-file mark (#2704),
+    // v8: + cached_tracks.missing, the server's missing-file mark,
     // so cache-first surfaces stop offering files that cannot stream.
-    // v7: + diagnostic_events table (M9) and the diagnosticsOptOut column
-    // on auth_session. Pre-v1 destructive fallback rebuilds on mismatch —
-    // which is exactly right here: the next sync refills every row with the
-    // new column populated, so there is nothing to migrate by hand.
+    // v7: + diagnostic_events table and the diagnosticsOptOut column
+    // on auth_session. Versions before v8 rebuild destructively, which is
+    // right for them: the next sync refills every row with the new
+    // columns populated, so there is nothing to migrate by hand.
     version = 12,
     exportSchema = true,
 )
@@ -115,7 +110,7 @@ abstract class AppDatabase : RoomDatabase() {
     abstract fun cachedNotificationDao(): CachedNotificationDao
 }
 
-/** v8 → v9: add the nullable normalization preference column (#4998). */
+/** v8 → v9: add the nullable normalization preference column. */
 val MIGRATION_8_9: Migration = object : Migration(8, 9) {
     override fun migrate(db: SupportSQLiteDatabase) {
         db.execSQL("ALTER TABLE auth_session ADD COLUMN normalizationJson TEXT")
@@ -123,7 +118,7 @@ val MIGRATION_8_9: Migration = object : Migration(8, 9) {
 }
 
 /**
- * v9 → v10: the gain columns (#5000). Rows synced before this carry no gains,
+ * v9 → v10: the gain columns. Rows synced before this carry no gains,
  * and the sync is incremental, so it would never re-send them: the cursor goes
  * back to 0 and the next sync is a full one, upserting every row in place.
  */
@@ -138,7 +133,7 @@ val MIGRATION_9_10: Migration = object : Migration(9, 10) {
 }
 
 /**
- * v10 → v11: the notifications inbox cache and its settings (M489). The SQL
+ * v10 → v11: the notifications inbox cache and its settings. The SQL
  * matches what Room generates for the two entities; Room checks it on open.
  */
 val MIGRATION_10_11: Migration = object : Migration(10, 11) {
@@ -157,7 +152,7 @@ val MIGRATION_10_11: Migration = object : Migration(10, 11) {
 }
 
 /**
- * v11 → v12: background delivery (M489 #5347). The device choice defaults on,
+ * v11 → v12: background delivery. The device choice defaults on,
  * as the entity's column default says; the high-water mark starts empty, so
  * the first catch-up sets it without announcing anything.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/DatabaseModule.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/DatabaseModule.kt
index 80bad40e..8e04a44c 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/DatabaseModule.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/DatabaseModule.kt
@@ -33,11 +33,10 @@ object DatabaseModule {
     @Singleton
     fun provideDatabase(@ApplicationContext context: Context): AppDatabase =
         Room.databaseBuilder(context, AppDatabase::class.java, DATABASE_NAME)
-            // Pre-v1 safety net: rebuild on any schema mismatch. The sync
-            // controller refills the cache from the server on first
-            // launch, so users lose only the unsynced mutation queue
-            // (acceptable while we're iterating). Replace with explicit
-            // Migration entries before the first tagged release.
+            // Explicit migrations from v8 onward; an older schema has no path
+            // and rebuilds. The sync controller refills the cache from the
+            // server on first launch, so a rebuild loses only the unsynced
+            // mutation queue.
             .addMigrations(MIGRATION_8_9, MIGRATION_9_10, MIGRATION_10_11, MIGRATION_11_12)
             .fallbackToDestructiveMigration(dropAllTables = true)
             .build()
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/TypeConverters.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/TypeConverters.kt
index 2ac1e6a7..0f868f55 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/TypeConverters.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/TypeConverters.kt
@@ -4,8 +4,7 @@ import androidx.room.TypeConverter
 import kotlinx.datetime.Instant
 
 /**
- * Source category for a cached audio file. Mirrors the Drift `CacheSource`
- * enum used by the Flutter client's `audio_cache_index` table 1:1.
+ * Source category for a cached audio file in `audio_cache_index`.
  *
  * - `MANUAL`: user explicitly pinned (e.g. "save for offline")
  * - `AUTO_LIKED`: auto-cached because the track is liked
@@ -13,8 +12,10 @@ import kotlinx.datetime.Instant
  * - `AUTO_PREFETCH`: pre-warmed by background prefetch heuristics
  * - `INCIDENTAL`: cached as a side effect of playback streaming
  *
- * Eviction priority order (first to evict): INCIDENTAL → AUTO_PREFETCH
- * → AUTO_PLAYLIST → AUTO_LIKED → MANUAL.
+ * Eviction priority (first to evict): INCIDENTAL → AUTO_PREFETCH
+ * → AUTO_PLAYLIST → AUTO_LIKED → MANUAL. Only INCIDENTAL is written
+ * today, and SimpleCache evicts by plain LRU, so nothing applies the
+ * order yet.
  */
 enum class CacheSource { MANUAL, AUTO_LIKED, AUTO_PLAYLIST, AUTO_PREFETCH, INCIDENTAL }
 
@@ -22,10 +23,8 @@ enum class CacheSource { MANUAL, AUTO_LIKED, AUTO_PLAYLIST, AUTO_PREFETCH, INCID
  * Cross-cutting Room type converters. Registered on `@Database` via
  * `@TypeConverters(MinstrelTypeConverters::class)`.
  *
- * `kotlinx.datetime.Instant` ↔ `Long` epoch millis: the same convention the
- * Flutter client uses (Drift `text()` column with ISO-8601 strings would
- * also work but Long is leaner; we don't need human-readable rows in the
- * SQLite file).
+ * `kotlinx.datetime.Instant` ↔ `Long` epoch millis: leaner than ISO-8601
+ * text, and nothing needs human-readable rows in the SQLite file.
  */
 class MinstrelTypeConverters {
     @TypeConverter fun instantToLong(i: Instant?): Long? = i?.toEpochMilliseconds()
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedLikeDao.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedLikeDao.kt
index a958ba15..68e43ad1 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedLikeDao.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedLikeDao.kt
@@ -44,10 +44,9 @@ interface CachedLikeDao {
     /**
      * Atomically replaces the user's entire cached_likes set with
      * [rows]. Used by [com.fabledsword.minstrel.likes.data.LikesRepository.refreshIds]
-     * so cross-device unlikes (a row that the server no longer
-     * surfaces) get removed from the local cache — drift #570
-     * caught the missing delete pass that left stale Liked tab
-     * entries pointing at tracks the user had unliked elsewhere.
+     * so an unlike made on another device (a row the server no longer
+     * surfaces) leaves the local cache too; upserts alone would keep a
+     * stale Liked tab entry forever.
      */
     @Transaction
     suspend fun replaceAllForUser(userId: String, rows: List<CachedLikeEntity>) {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedPlaylistTrackDao.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedPlaylistTrackDao.kt
index 072cc11b..23e4341b 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedPlaylistTrackDao.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedPlaylistTrackDao.kt
@@ -46,13 +46,13 @@ interface CachedPlaylistTrackDao {
      * Atomic on purpose. Room's InvalidationTracker only notifies observers
      * after the transaction commits, so [observeByPlaylist] never sees the
      * empty gap between the delete and the re-insert. Un-transacted, that
-     * gap is a real observed state — it's what made every Home row visibly
-     * collapse to empty and refill before issue #2327 fixed the equivalent
-     * write in `CachedHomeIndexDao`.
+     * gap is a real observed state: the list visibly collapses to empty
+     * and refills, which is why `CachedHomeIndexDao` transacts its writes
+     * too.
      *
      * Nothing observes [observeByPlaylist] live today, so this is
-     * pre-emptive: it means making playlist detail cache-first later can't
-     * silently reintroduce that flicker.
+     * pre-emptive: making playlist detail cache-first later can't
+     * silently bring that flicker in.
      */
     @Transaction
     suspend fun replacePlaylistTracks(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedQuarantineDao.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedQuarantineDao.kt
index 302c97f9..2a618314 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedQuarantineDao.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedQuarantineDao.kt
@@ -41,8 +41,7 @@ interface CachedQuarantineDao {
     /**
      * Atomic full-replace from the server snapshot — one transaction so
      * the `observeAll()` watcher sees a single merged emission, not a
-     * delete-then-insert flicker. Mirrors Flutter's MyQuarantineController
-     * `_refreshFromServer` transaction.
+     * delete-then-insert flicker.
      */
     @Transaction
     suspend fun replaceAll(rows: List<CachedQuarantineEntity>) {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedTrackDao.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedTrackDao.kt
index da1894dc..acd69f89 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedTrackDao.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/dao/CachedTrackDao.kt
@@ -39,7 +39,7 @@ interface CachedTrackDao {
     suspend fun upsertAll(rows: List<CachedTrackEntity>)
 
     /**
-     * ReplayGain values for [ids] (M464 #5000): the track's own from its row,
+     * ReplayGain values for [ids]: the track's own from its row,
      * the album's from its album row. A track not in the cache has no row.
      */
     @Query(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AudioCacheIndexEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AudioCacheIndexEntity.kt
index 07ead191..49e391c2 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AudioCacheIndexEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AudioCacheIndexEntity.kt
@@ -7,14 +7,12 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * One row per fully-downloaded audio file. Mirrors
- * the Flutter client's `AudioCacheIndex` Drift table.
- *
- * Drives the 2-bucket LRU eviction (Phase 12 AudioCacheEvictionWorker):
- *   - `incidental` files (streamed-and-cached side effect) evict first
- *   - `autoPrefetch` second
- *   - `manual` (user explicitly pinned) evict last
+ * One row per track that has played through the audio cache (see
+ * `CacheIndexer`); SimpleCache, not this table, says what is on disk.
  *
+ * The `source` column is meant to drive a 2-bucket eviction
+ * (incidental first, then auto-prefetch, manual last). Nothing evicts
+ * by it yet: SimpleCache evicts by plain LRU over the rolling cap.
  * `cachedAt` = when we downloaded. `lastPlayedAt` = when the user last
  * played it; drives the offline "recently played" ordering and is the
  * tiebreaker for LRU eviction within a source bucket. Nullable on
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AuthSessionEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AuthSessionEntity.kt
index 43e120eb..f769d926 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AuthSessionEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/AuthSessionEntity.kt
@@ -39,7 +39,7 @@ data class AuthSessionEntity(
      */
     val cacheSettingsJson: String? = null,
     /**
-     * Per-device opt-out of diagnostics reporting (M9). When the
+     * Per-device opt-out of diagnostics reporting. When the
      * account's debug mode is enabled by an admin, the user can still
      * turn reporting OFF on this device (battery/privacy) — that local
      * choice lives here. Default false = honor the account flag.
@@ -47,12 +47,12 @@ data class AuthSessionEntity(
     val diagnosticsOptOut: Boolean = false,
     /**
      * JSON-encoded NormalizationPrefs (settings/data), the last value seen
-     * from the server or set here (M464 #4998). Null = never fetched; the
+     * from the server or set here. Null = never fetched; the
      * defaults apply. Kept so offline playback still levels.
      */
     val normalizationJson: String? = null,
     /**
-     * "Notifications when the app is closed" (M489 #5347): keep the
+     * "Notifications when the app is closed": keep the
      * delivery foreground service running. A device choice, on by default.
      * The column default matches MIGRATION_11_12's, which Room checks.
      */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedAlbumEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedAlbumEntity.kt
index b2a22dfa..8406e6a6 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedAlbumEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedAlbumEntity.kt
@@ -5,10 +5,7 @@ import androidx.room.PrimaryKey
 import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
-/**
- * Cache row for one album. Mirrors the Flutter client's
- * `CachedAlbums` Drift table.
- */
+/** Cache row for one album. */
 @Entity(tableName = "cached_albums")
 data class CachedAlbumEntity(
     @PrimaryKey val id: String,
@@ -18,7 +15,7 @@ data class CachedAlbumEntity(
     val releaseDate: String? = null,
     val coverPath: String? = null,
     val mbid: String? = null,
-    // ReplayGain 2.0 album values (M464); null until every track is measured.
+    // ReplayGain 2.0 album values; null until every track is measured.
     val albumGain: Float? = null,
     val albumPeak: Float? = null,
     val fetchedAt: Instant = Clock.System.now(),
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedArtistEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedArtistEntity.kt
index 7ba15a50..fa8d13d3 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedArtistEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedArtistEntity.kt
@@ -6,13 +6,11 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * Cache row for one artist. Mirrors the Flutter client's
- * `CachedArtists` Drift table.
+ * Cache row for one artist.
  *
- * Column names follow Kotlin idiom (camelCase) rather than Drift's
- * snake_case — the schema is purely internal to the native client; the
- * sync controller exchanges snake_case JSON with the server and our
- * mappers translate at the boundary.
+ * Column names follow Kotlin idiom (camelCase) — the schema is purely
+ * internal to the app; the sync controller exchanges snake_case JSON
+ * with the server and our mappers translate at the boundary.
  */
 @Entity(tableName = "cached_artists")
 data class CachedArtistEntity(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedHistorySnapshotEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedHistorySnapshotEntity.kt
index f6d68747..657866c6 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedHistorySnapshotEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedHistorySnapshotEntity.kt
@@ -8,8 +8,7 @@ import kotlinx.datetime.Instant
 /**
  * Single-row snapshot of the `/api/me/history` response, stored as the
  * raw wire JSON so the History tab paints instantly from disk on cold
- * open and survives connectivity loss. Mirrors the Flutter Drift
- * `CachedHistorySnapshot` table (id defaults to 1; one row total).
+ * open and survives connectivity loss. One row total; id defaults to 1.
  *
  * Cache-first + SWR: the tab observes this row and a background refresh
  * overwrites it, so the freshest plays land without a blocking spinner.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedHomeIndexEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedHomeIndexEntity.kt
index 914bccd4..f06a7ebb 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedHomeIndexEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedHomeIndexEntity.kt
@@ -5,8 +5,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * Per-item row driving the Home screen sections. Mirrors
- * the Flutter client's `CachedHomeIndex` Drift table.
+ * Per-item row driving the Home screen sections.
  *
  * `section` is one of (matching /api/home keys):
  *   - "recently_added_albums"
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedLikeEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedLikeEntity.kt
index 34050fdc..55d2e09e 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedLikeEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedLikeEntity.kt
@@ -5,14 +5,13 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * Like membership row. Mirrors the Flutter client's
- * `CachedLikes` Drift table. Composite primary key — one user may
+ * Like membership row. Composite primary key — one user may
  * independently like a track AND its album AND its artist; rows are
  * disambiguated by the (userId, entityType, entityId) triple.
  *
  * `entityType` is one of "track" | "album" | "artist". Stored as a
- * plain string for parity with the Drift schema and the server's wire
- * format; an enum doesn't earn its keep here.
+ * plain string to match the server's wire format; an enum doesn't
+ * earn its keep here.
  */
 @Entity(
     tableName = "cached_likes",
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedMutationEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedMutationEntity.kt
index bed65edb..e57be15f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedMutationEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedMutationEntity.kt
@@ -6,12 +6,11 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * One row per pending offline-write. Mirrors
- * the Flutter client's `CachedMutations` Drift table.
+ * One row per pending offline write.
  *
  * MutationQueue.enqueue() inserts a row when a server-write fails with
  * an IOException; MutationReplayer.drain() pops and re-attempts each
- * row when connectivity returns (Phase 12.2).
+ * row when connectivity returns.
  *
  * `kind` is a stable string registered in `MutationKind` — the replayer
  * looks up the handler in a kind→suspend-function map. Unknown kinds
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationEntity.kt
index 642e588e..7a8e1791 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationEntity.kt
@@ -5,7 +5,7 @@ import androidx.room.PrimaryKey
 import kotlinx.datetime.Instant
 
 /**
- * One notice from the user's inbox (M489), kept so the Notifications screen
+ * One notice from the user's inbox, kept so the Notifications screen
  * and the bell's badge work offline, and so a read made offline shows at once.
  * The newest page is cached; older notices are the server's to keep.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationSettingsEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationSettingsEntity.kt
index 272abf30..b77db920 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationSettingsEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedNotificationSettingsEntity.kt
@@ -4,7 +4,7 @@ import androidx.room.Entity
 import androidx.room.PrimaryKey
 
 /**
- * Single-row copy of the user's notification settings (M489), stored as the
+ * Single-row copy of the user's notification settings, stored as the
  * wire JSON, so the settings screen opens offline and a toggle shows at once.
  */
 @Entity(tableName = "cached_notification_settings")
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistEntity.kt
index 82701d62..7730fa4a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistEntity.kt
@@ -6,8 +6,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * Cache row for one playlist (user or system). Mirrors
- * the Flutter client's `CachedPlaylists` Drift table.
+ * Cache row for one playlist (user or system).
  *
  * `systemVariant` is null for user playlists and one of
  * "for_you" / "songs_like_artist" / "discover" / "todays_mix" / etc.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistTrackEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistTrackEntity.kt
index d70acbb6..7a245bbc 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistTrackEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedPlaylistTrackEntity.kt
@@ -3,8 +3,7 @@ package com.fabledsword.minstrel.cache.db.entities
 import androidx.room.Entity
 
 /**
- * Ordered membership of tracks within a playlist. Mirrors
- * the Flutter client's `CachedPlaylistTracks` Drift table.
+ * Ordered membership of tracks within a playlist.
  * Composite PK so the same track can only appear once per playlist;
  * `position` carries the ordering.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedQuarantineEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedQuarantineEntity.kt
index f3ccc73f..9254d5a2 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedQuarantineEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedQuarantineEntity.kt
@@ -6,9 +6,7 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * The current user's quarantine flag for one track. Mirrors
- * the Flutter client's `CachedQuarantineMine` Drift
- * table.
+ * The current user's quarantine flag for one track.
  *
  * The flat denormalized track/album/artist columns let the Quarantine
  * screen render off this single table without a join — the server
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedResumeStateEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedResumeStateEntity.kt
index 64cbf588..8ed10e34 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedResumeStateEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedResumeStateEntity.kt
@@ -7,18 +7,15 @@ import kotlinx.datetime.Instant
 
 /**
  * Single-row snapshot of the last playback session — queue (as JSON),
- * current index, position, and source tag. Mirrors
- * the Flutter client's `CachedResumeState` Drift table.
+ * current index, position, and source tag.
  *
  * Lets a torn-down session (the player's idle/dismissed teardown)
  * resume on next launch; without it the headset / lock-screen play
- * button has nothing to act on. The Flutter codebase persists this on
- * every queue change and reads on cold start.
+ * button has nothing to act on.
  *
  * The `json` field carries the entire ResumeState shape (queue trackrefs,
- * currentIndex, positionMs, sourceTag). Kotlin-side deserialization
- * happens in the ResumeController (Phase 6.5) so the schema stays
- * stable across resume-shape changes.
+ * currentIndex, positionMs, sourceTag). The ResumeController decodes it,
+ * so the schema stays stable across resume-shape changes.
  */
 @Entity(tableName = "cached_resume_state")
 data class CachedResumeStateEntity(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedTrackEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedTrackEntity.kt
index f3cff52d..124c883a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedTrackEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/CachedTrackEntity.kt
@@ -6,10 +6,9 @@ import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 
 /**
- * Cache row for one track. Mirrors the Flutter client's
- * `CachedTracks` Drift table.
+ * Cache row for one track.
  *
- * [missing] carries the server's missing-file mark (#2704). Every read that
+ * [missing] carries the server's missing-file mark. Every read that
  * can put a track in front of the user — or in a queue — must exclude it, and
  * the DAO queries do that rather than each call site remembering to.
  */
@@ -26,7 +25,7 @@ data class CachedTrackEntity(
     val fileFormat: String? = null,
     val genre: String? = null,
     val missing: Boolean = false,
-    // ReplayGain 2.0 track values (M464), kept so cached audio levels
+    // ReplayGain 2.0 track values, kept so cached audio levels
     // offline. Null until the server has measured the track.
     val trackGain: Float? = null,
     val trackPeak: Float? = null,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/DiagnosticEventEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/DiagnosticEventEntity.kt
index 7e5f2868..9eb124e5 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/DiagnosticEventEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/DiagnosticEventEntity.kt
@@ -4,14 +4,14 @@ import androidx.room.Entity
 import androidx.room.PrimaryKey
 
 /**
- * One buffered device-diagnostics event (M9). The DiagnosticsReporter
+ * One buffered device-diagnostics event. The DiagnosticsReporter
  * writes rows here when the account's debug mode is on; the
  * DiagnosticsUploader drains them to POST /api/diagnostics and deletes
  * on success.
  *
  * This is a deliberate ring buffer that is NOT routed through the offline
  * MutationQueue: diagnostics are high-volume, best-effort telemetry, and
- * the bug we're chasing (roaming / dead-zone recovery) happens WHILE
+ * the failures they record (roaming / dead-zone recovery) happen WHILE
  * offline — so events must persist locally through the dead zone and
  * upload on recovery, without clogging the user-data mutation replay.
  *
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/SyncMetadataEntity.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/SyncMetadataEntity.kt
index 6cb775d7..ceafc677 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/SyncMetadataEntity.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/db/entities/SyncMetadataEntity.kt
@@ -7,12 +7,8 @@ import kotlinx.datetime.Instant
 /**
  * Single-row table that tracks where the SyncController left off.
  *
- * Mirrors the Flutter Drift `sync_metadata` table. There is only ever
- * one row at `id = 0`; the SyncController upserts on every successful
- * `/api/sync` call.
- *
- * Pulled into Task 4.1 to give Room a compileable @Database (it needs
- * at least one entity); the SyncController itself lands in Phase 12.4.
+ * There is only ever one row at `id = 0`; the SyncController upserts it
+ * on every successful `/api/library/sync` call.
  */
 @Entity(tableName = "sync_metadata")
 data class SyncMetadataEntity(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationQueue.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationQueue.kt
index a19c7cb2..a78a61cc 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationQueue.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationQueue.kt
@@ -33,30 +33,29 @@ object MutationKind {
 
     // Durable close-by-id for a play whose server row is already open
     // (play_started succeeded). Distinct from PLAY_OFFLINE, which records
-    // a *whole* play when no server row exists. Using close-by-id on
-    // background avoids the duplicate + orphan row the old offline-on-stop
-    // path produced (see 2026-06-11 contract audit).
+    // a *whole* play when no server row exists. Recording a whole play on
+    // background would duplicate the open row and leave it orphaned.
     const val PLAY_ENDED: String = "play_ended"
 
-    // #2374 suggestion snooze. ONE toggle kind rather than separate
+    // Suggestion snooze. ONE toggle kind rather than separate
     // snooze/unsnooze kinds, mirroring LIKE_TOGGLE, so a snooze followed by
     // an undo collapses to the latest intent instead of replaying as two
     // opposed calls whose order decides the outcome.
     const val SUGGESTION_SNOOZE_TOGGLE: String = "suggestion_snooze_toggle"
 
-    // M464 #4998 loudness-normalization preference. The payload is the whole
+    // Loudness-normalization preference. The payload is the whole
     // preference, a target state like the toggles above, so queued changes
     // collapse to the last one and an older one can never be replayed last.
     const val NORMALIZATION_SET: String = "normalization_set"
 
-    // M489 notifications inbox. A read is a one-way action (read never goes
+    // Notifications inbox. A read is a one-way action (read never goes
     // back to unread), so neither read kind needs collapsing. Read-all
     // carries the moment the user asked, so a late replay leaves newer
     // notices unread.
     const val NOTIFICATION_READ: String = "notification_read"
     const val NOTIFICATIONS_READ_ALL: String = "notifications_read_all"
 
-    // M489 per-kind channel setting. One row per (kind, channel) target
+    // Per-kind notification channel. One row per (kind, channel) target
     // state, collapsed on that pair, so the newest choice is the one sent.
     const val NOTIFICATION_SETTING_SET: String = "notification_setting_set"
 }
@@ -92,16 +91,13 @@ data class RequestCreatePayload(
 )
 
 /**
- * Minimal write-side of the offline mutation queue. Phase 8 v1 only
- * enqueues — the connectivity-aware replayer that drains the queue
- * lands with Phase 12.2's SyncController.
+ * Write side of the offline mutation queue; [MutationReplayer] drains it.
  *
  * Callers (LikesRepository et al.) follow the optimistic-write
  * pattern: mutate Room first so the UI reflects the change
  * immediately, fire the REST call as a best-effort attempt, and on
  * failure enqueue here so the replayer eventually pushes it through.
- * This matches `feedback_offline_first_for_server_writes` — writes
- * never go fire-and-forget.
+ * Writes never go fire-and-forget.
  */
 @Suppress("TooManyFunctions") // one enqueue per mutation kind, like the replayer's dispatchers
 @Singleton
@@ -262,7 +258,7 @@ class MutationQueue @Inject constructor(
 }
 
 /**
- * Persisted payload for `MutationKind.SUGGESTION_SNOOZE_TOGGLE` (#2374).
+ * Persisted payload for `MutationKind.SUGGESTION_SNOOZE_TOGGLE`.
  * `desiredSnoozed` is the *target* state, matching [LikeTogglePayload], so
  * the replayer can collapse repeated toggles for one candidate down to the
  * last intent. Both directions are idempotent server-side: re-snoozing
@@ -285,10 +281,10 @@ data class SuggestionSnoozeTogglePayload(
 data class QuarantineUnflagPayload(val trackId: String)
 
 /**
- * Persisted payload for `MutationKind.PLAYLIST_APPEND`. Mirrors the
- * Flutter wire shape: list of track IDs to append to a specific
- * playlist. Server is idempotent at the (playlist_id, track_id) pair
- * level — re-firing the same payload yields no duplicates.
+ * Persisted payload for `MutationKind.PLAYLIST_APPEND`: the track IDs to
+ * append to one playlist. The server is idempotent at the
+ * (playlist_id, track_id) pair level — re-firing the same payload yields
+ * no duplicates.
  */
 @Serializable
 data class PlaylistAppendPayload(
@@ -314,7 +310,7 @@ data class QuarantineFlagPayload(
  * re-fires `POST /api/events` with type=play_offline; the server
  * records start+end from `atIso` (the original play-start time)
  * + `durationPlayedMs`, applies the canonical skip rule, and
- * advances #415 rotation when source is a system playlist.
+ * advances rotation when source is a system playlist.
  */
 @Serializable
 data class PlayOfflinePayload(
@@ -323,7 +319,7 @@ data class PlayOfflinePayload(
     val atIso: String,
     val durationPlayedMs: Long,
     val source: String? = null,
-    // #1551: device class for context conditioning; null on payloads queued
+    // Device class for context conditioning; null on payloads queued
     // before this field existed (decodes to null → server stores NULL).
     val deviceClass: String? = null,
 )
@@ -367,12 +363,12 @@ data class PlaybackErrorReportPayload(
     val clientId: String,
 )
 
-/** Persisted payload for `MutationKind.NOTIFICATION_READ` (M489). */
+/** Persisted payload for `MutationKind.NOTIFICATION_READ`. */
 @Serializable
 data class NotificationReadPayload(val id: String)
 
 /**
- * Persisted payload for `MutationKind.NOTIFICATIONS_READ_ALL` (M489).
+ * Persisted payload for `MutationKind.NOTIFICATIONS_READ_ALL`.
  * `upToIso` is the newest notice the user could see when they asked; null
  * when the inbox was empty on the device, which marks everything.
  */
@@ -380,7 +376,7 @@ data class NotificationReadPayload(val id: String)
 data class NotificationsReadAllPayload(val upToIso: String?)
 
 /**
- * Persisted payload for `MutationKind.NOTIFICATION_SETTING_SET` (M489): one
+ * Persisted payload for `MutationKind.NOTIFICATION_SETTING_SET`: one
  * kind's one channel, as a target state. `channel` is "inbox" | "phone" |
  * "email". No defaults, so every field is always written.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationReplayer.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationReplayer.kt
index dbe5293e..5a28f9b7 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationReplayer.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/mutations/MutationReplayer.kt
@@ -160,7 +160,7 @@ class MutationReplayer @Inject constructor(
     /**
      * Returns the outcome of replaying one row. SENT on a 2xx; DROP for an
      * unknown kind/variant. Network / HTTP failures THROW and are classified
-     * by [outcomeFor] — dispatchers no longer swallow.
+     * by [outcomeFor] — dispatchers never swallow them.
      */
     private suspend fun dispatch(row: CachedMutationEntity): Outcome = when (row.kind) {
         MutationKind.LIKE_TOGGLE -> dispatchLikeToggle(row.payload)
@@ -182,7 +182,7 @@ class MutationReplayer @Inject constructor(
         else -> Outcome.DROP
     }
 
-    /** The notifications inbox's kinds (M489), split out to keep [dispatch] simple. */
+    /** The notifications inbox's kinds, split out to keep [dispatch] simple. */
     private suspend fun dispatchNotification(row: CachedMutationEntity): Outcome = when (row.kind) {
         MutationKind.NOTIFICATION_READ -> dispatchNotificationRead(row.payload)
         MutationKind.NOTIFICATIONS_READ_ALL -> dispatchNotificationsReadAll(row.payload)
@@ -354,8 +354,8 @@ class MutationReplayer @Inject constructor(
 /**
  * Row ids of desired-state toggles superseded by a later toggle for the same
  * entity. Applies to every kind whose payload encodes a TARGET state rather
- * than an action — like-toggles, suggestion snoozes (#2374) and the
- * normalization preference (#4998) — because
+ * than an action — like-toggles, suggestion snoozes and the
+ * normalization preference — because
  * replaying a stale one last would invert the final state.
  *
  * Top-level and pure so it can be unit-tested without standing up a Retrofit
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/cache/sync/SyncController.kt b/android/app/src/main/java/com/fabledsword/minstrel/cache/sync/SyncController.kt
index 5ae67c21..40ef2b40 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/cache/sync/SyncController.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/cache/sync/SyncController.kt
@@ -34,9 +34,8 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Drives the delta sync against `/api/library/sync` (#357). Mirrors
- * the Flutter `SyncController`, scoped to the entity types the
- * native client cares about (artist/album/track). Likes and
+ * Drives the delta sync against `/api/library/sync`, scoped to the
+ * entity types the app caches (artist/album/track). Likes and
  * playlists get their own dedicated refresh paths so the sync
  * controller doesn't need to track them.
  *
@@ -46,10 +45,9 @@ import javax.inject.Singleton
  * with a persisted cookie). Re-running on every cookie change is
  * what makes the Library tabs populate within seconds of sign-in.
  *
- * Wipes-on-410: when the server's compaction window has passed the
- * stored cursor, the response is 410 Gone. The controller drops the
- * three local caches and recurses with cursor=0 — same wipe behavior
- * as the Flutter port.
+ * Restart-on-410: when the server's compaction window has passed the
+ * stored cursor, the response is 410 Gone. The controller resets the
+ * cursor to 0 and pulls the full entity set again (see [resetCursor]).
  */
 @Singleton
 class SyncController @Inject constructor(
@@ -110,11 +108,11 @@ class SyncController @Inject constructor(
     }
 
     /**
-     * Pulls pages until the server has nothing newer (#5654). The server
-     * returns at most 1000 changes a call; taking one page per trigger left
-     * the cache behind a change log that a full re-read grows by ~26,000
-     * rows, so merge deletes never arrived and the freshness sweep kept
-     * asking for tracks that were gone. The cursor is stored after each
+     * Pulls pages until the server has nothing newer. The server returns
+     * at most 1000 changes a call, and a full library re-read adds tens
+     * of thousands, so one page per trigger would leave the cache behind:
+     * merge deletes would never arrive and the freshness sweep would keep
+     * asking for tracks that are gone. The cursor is stored after each
      * page, so an interrupted pass resumes where it stopped.
      */
     private suspend fun sync() {
@@ -153,7 +151,7 @@ class SyncController @Inject constructor(
                 body.cursor > cursor
             }
             else -> {
-                // Unhandled status — treat as a no-op for v1; the next
+                // Unhandled status — treat as a no-op; the next
                 // app start retries from the same cursor.
                 false
             }
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/connectivity/NetworkStatusController.kt b/android/app/src/main/java/com/fabledsword/minstrel/connectivity/NetworkStatusController.kt
index 89fc5f39..b01f8d3e 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/connectivity/NetworkStatusController.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/connectivity/NetworkStatusController.kt
@@ -29,27 +29,25 @@ private const val POLL_DEGRADED_MS = 20_000L
 private const val ARBITRATE_MIN_GAP_MS = 2_000L
 
 /**
- * THE single authority on network/server reachability. Absorbs the former
- * VersionCheckController (the /healthz poll + version parsing) and
- * ServerHealthController (the tri-state derive) into one signal-driven unit so
- * the app has one place that answers "can we reach Minstrel?" — not three
- * half-systems reporting differently.
+ * THE single authority on network/server reachability: the /healthz poll,
+ * version parsing and the tri-state health derive live in one
+ * signal-driven unit, so the app has one place that answers "can we reach
+ * Minstrel?".
  *
  * Inputs (all funnel through a single-consumer intent channel for thread
  * safety — [reportSuccess]/[reportFailure] are called from the audio read path
  * and OkHttp threads):
  *  - device link transitions ([ConnectivityObserver]); link-return triggers an
- *    immediate probe so recovery is near-instant (fixes the sticky banner).
+ *    immediate probe so recovery is near-instant.
  *  - periodic /healthz probe, adaptive cadence (calm when Healthy, fast when down).
  *  - reportSuccess / reportFailure from the API interceptor, the audio data
  *    source, and the playback-error reporter.
  *  - recheck() from pull-to-refresh and the banner.
- *  - a forced probe when the app returns to the foreground (#1209). Without
- *    it a stale ServerDown outlived the condition that caused it: the poll
- *    loop's delay() is throttled while screen-off/doze, so recovery waited on
- *    whenever the OS next let the loop run. Meanwhile ServerDown makes
- *    OfflineGatedDataSource refuse every uncached track, so the app declined
- *    to play music that would have played fine.
+ *  - a forced probe when the app returns to the foreground. The poll
+ *    loop's delay() is throttled while screen-off/doze, so without it a
+ *    stale ServerDown would outlive its cause until the OS next let the
+ *    loop run — and ServerDown makes OfflineGatedDataSource refuse every
+ *    uncached track, declining music that would play fine.
  *
  * Version compatibility is a byproduct of the same /healthz response.
  *
@@ -112,7 +110,7 @@ class NetworkStatusController @Inject constructor(
 
     /**
      * App returned to the foreground — probe now rather than waiting for the
-     * poll loop (#1209).
+     * poll loop.
      *
      * The link-return probe in `init` does NOT cover this: it fires on a
      * connectivity *change*, and an app backgrounded on stable Wi-Fi sees none.
@@ -172,7 +170,7 @@ class NetworkStatusController @Inject constructor(
 
     private suspend fun probeOnce(force: Boolean = false) {
         // Startup guard: don't poll the localhost placeholder before AuthStore
-        // hydrates the real base URL — that false failure used to flash the banner.
+        // hydrates the real base URL — that false failure would flash the banner.
         if (authStore.baseUrl.value == AuthStore.DEFAULT_BASE_URL) return
         val now = System.currentTimeMillis()
         if (!force && now - lastProbeAtMs.get() < ARBITRATE_MIN_GAP_MS) return
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/connectivity/ReachabilityMachine.kt b/android/app/src/main/java/com/fabledsword/minstrel/connectivity/ReachabilityMachine.kt
index bc998515..3aff5458 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/connectivity/ReachabilityMachine.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/connectivity/ReachabilityMachine.kt
@@ -5,15 +5,14 @@ internal const val CORROBORATION_WINDOW_MS = 30_000L
 internal const val CORROBORATION_OP_THRESHOLD = 2
 
 /**
- * Minimum gap between op failures for them to count as SEPARATE evidence
- * (#1209).
+ * Minimum gap between op failures for them to count as SEPARATE evidence.
  *
  * A link handoff fails every in-flight request at once, so a burst is one
  * event producing N failures — not N independent observations that the server
- * is gone. Without this, two simultaneous failures corroborated each other
- * straight to Unreachable, and ServerDown makes OfflineGatedDataSource refuse
- * every uncached track. The app declined to play music that would have played
- * fine, for a blip that had already resolved.
+ * is gone. Counted separately, two simultaneous failures would corroborate
+ * each other straight to Unreachable, and ServerDown makes
+ * OfflineGatedDataSource refuse every uncached track: the app would decline
+ * music that plays fine, for a blip that had already resolved.
  *
  * 3s is comfortably above the sub-second window an OS handoff occupies while
  * still letting a genuine outage corroborate within seconds once a client
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsReporter.kt b/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsReporter.kt
index 4ce6f4f0..9bff541b 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsReporter.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsReporter.kt
@@ -38,7 +38,7 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * On-device diagnostics collector (M9). Active only while the account's
+ * On-device diagnostics collector. Active only while the account's
  * debug mode is enabled (server flag, read via AuthController.currentUser)
  * AND the user hasn't opted out locally. When active it taps existing
  * connectivity / player / UPnP / power seams READ-ONLY and writes a
@@ -196,13 +196,11 @@ class DiagnosticsReporter @Inject constructor(
     /**
      * Catch the renderer rapidly leaving and re-entering PLAYING.
      *
-     * The operator reports the Sonos "play pause play pause, like someone
-     * pressing it every half second", usually as a track starts, cleared by a
-     * manual pause or skip. Nothing here could see that: `player_state`
-     * carries source/loading/error but not playing, `track_change` needs the
-     * index to move, and the heartbeat samples once per 45s. The symptom fell
-     * through every existing collector, which is why it has only ever been
-     * described and never measured.
+     * The symptom: a Sonos rapidly play-pause-play-pausing, about every half
+     * second, usually as a track starts, cleared by a manual pause or skip.
+     * No other collector sees it: `player_state` carries
+     * source/loading/error but not playing, `track_change` needs the index
+     * to move, and the heartbeat samples once per 45s.
      *
      * Records every raw transport change (cheap — steady playback produces
      * a couple per track) and, when they come in a burst, one summary event
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsUploader.kt b/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsUploader.kt
index b4be91c6..b51571a1 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsUploader.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/DiagnosticsUploader.kt
@@ -27,7 +27,7 @@ import javax.inject.Singleton
 
 /**
  * Drains the [DiagnosticEventDao] ring buffer to POST /api/diagnostics
- * (M9). Triggers mirror [com.fabledsword.minstrel.cache.mutations.MutationReplayer]:
+ *. Triggers mirror [com.fabledsword.minstrel.cache.mutations.MutationReplayer]:
  * a periodic tick, a sign-in (sessionCookie non-null), and a server-health
  * recovery to [ServerHealth.Healthy] — so a dead-zone's buffered events
  * upload the moment the link comes back.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/TransportFlapDetector.kt b/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/TransportFlapDetector.kt
index dfcda283..b4faf033 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/TransportFlapDetector.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/diagnostics/TransportFlapDetector.kt
@@ -6,10 +6,9 @@ import com.fabledsword.minstrel.player.TransportObservation
  * Decides when a run of renderer transport changes is a *flap* — the renderer
  * repeatedly failing to settle — rather than an ordinary track transition.
  *
- * The operator reports the Sonos "play pause play pause, like someone pressing
- * it every half second", usually as a track starts. No diagnostic event could
- * see it, so it has been described several times and measured never. This is
- * the rule that decides when an episode is worth writing down.
+ * The symptom: a Sonos rapidly play-pause-play-pausing, about every half
+ * second, usually as a track starts. No other diagnostic event records it;
+ * this is the rule that decides when an episode is worth writing down.
  *
  * Pure decision state, like [com.fabledsword.minstrel.player.RemoteStallWatchdog]:
  * the caller owns the flow and the recording, this only answers "is this an
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/discover/data/DiscoverRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/discover/data/DiscoverRepository.kt
index c9fcedbf..96e08bec 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/discover/data/DiscoverRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/discover/data/DiscoverRepository.kt
@@ -29,16 +29,11 @@ enum class RequestOutcome { ACCEPTED, QUEUED }
 
 /**
  * Read-through Discover surface: catalogue search, suggestion feed, and
- * the request-creation write path. Mirrors the Flutter
- * `DiscoverApi` + `mutationQueueProvider` integration —
- * `feedback_offline_first_for_server_writes` says writes never go
- * fire-and-forget, so `createRequest` falls back to the
- * MutationQueue on transport failure.
+ * the request-creation write path. Writes never go fire-and-forget, so
+ * `createRequest` falls back to the MutationQueue on transport failure.
  *
- * Reads are not cached locally yet — discovery results are inherently
- * transient (60s server-side LRU); the cache wins are minor and
- * unblock no UX. Phase 13's offline pass adds an offline scrollback
- * for the suggestion feed only.
+ * Reads are not cached locally — discovery results are inherently
+ * transient (60s server-side LRU), so a local cache would win little.
  */
 @Singleton
 class DiscoverRepository @Inject constructor(
@@ -54,7 +49,7 @@ class DiscoverRepository @Inject constructor(
         api.listSnoozes().map { it.toDomain() }
 
     /**
-     * Parks a suggestion ("not right now"). Offline-first per rule #100: on
+     * Parks a suggestion ("not right now"). Offline-first: on
      * transport failure the target state is queued for the replayer rather
      * than dropped.
      *
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverScreen.kt b/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverScreen.kt
index ce27c2b7..ade53f2a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverScreen.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverScreen.kt
@@ -195,8 +195,8 @@ private fun KindChips(kind: RequestKind, onChange: (RequestKind) -> Unit) {
 
 /**
  * The snooze surface's data and callbacks, bundled rather than threaded
- * through as four more parameters — the pane grew from one action to three
- * with slice 4 and the signatures stopped being readable.
+ * through as separate parameters: the pane carries three actions, and the
+ * signatures stop being readable otherwise.
  */
 private data class SnoozeUi(
     val locallySnoozedMbids: Set<String>,
@@ -240,9 +240,9 @@ private fun SuggestionsList(
     ) {
         item { SuggestionsHeader() }
         if (items.isEmpty()) {
-            // An empty deck used to mean one thing — no listening signal yet.
-            // With snoozing it can also mean "you parked them all", and telling
-            // that user to go listen to something would be wrong advice.
+            // An empty deck means one of two things — no listening signal yet,
+            // or "you parked them all" — and telling the second user to go
+            // listen to something would be wrong advice.
             item {
                 CenteredMessage(
                     if (snoozeUi.snoozes.isEmpty()) {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverTiles.kt b/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverTiles.kt
index f5201266..334d3427 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverTiles.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverTiles.kt
@@ -79,8 +79,8 @@ internal fun SuggestionTile(
             IconButton(onClick = onSnooze) {
                 Icon(
                     imageVector = Lucide.Clock,
-                    // Rule #101: the label states what happens, and passes no
-                    // judgement on the music. Never "not for me".
+                    // The label states what happens and passes no judgement on the
+                    // music: never "not for me".
                     contentDescription = "Not right now — hide ${s.name} for a while",
                     tint = MaterialTheme.colorScheme.onSurfaceVariant,
                 )
@@ -173,7 +173,7 @@ private fun Avatar(imageUrl: String, fallback: ImageVector, circular: Boolean) {
             .background(MaterialTheme.colorScheme.surfaceVariant),
         contentAlignment = Alignment.Center,
     ) {
-        // The server hands back its own art endpoint (relative, M502 #5519),
+        // The server hands back its own art endpoint (relative),
         // which answers 404 when no source has an image: ServerImage resolves
         // the path and shows the icon while loading and on a miss.
         ServerImage(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverViewModel.kt
index 1e05471a..bce9f3c9 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/discover/ui/DiscoverViewModel.kt
@@ -68,7 +68,7 @@ class DiscoverViewModel @Inject constructor(
 
     init {
         loadSuggestions()
-        // Screen-level auto-recovery (issue #1245): re-run whichever pane
+        // Screen-level auto-recovery: re-run whichever pane
         // failed while the server was unreachable once health returns.
         viewModelScope.launch {
             networkStatus.recoveries().collect {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/events/EventsStream.kt b/android/app/src/main/java/com/fabledsword/minstrel/events/EventsStream.kt
index 925d4bd4..16c96adc 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/events/EventsStream.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/events/EventsStream.kt
@@ -54,7 +54,7 @@ private const val EVENTS_BUFFER_CAPACITY = 64
  *   retry. Without this a single blip silently kills cross-device
  *   reactivity until the next app launch.
  * - [connected] says whether a stream is open. Background delivery
- *   (M489 #5347) catches up on every rising edge: nothing replays a
+ *   catches up on every rising edge: nothing replays a
  *   frame sent while the stream was down.
  *
  * The URL passes through the placeholder host that
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/events/LiveEvent.kt b/android/app/src/main/java/com/fabledsword/minstrel/events/LiveEvent.kt
index 99656fec..825b9859 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/events/LiveEvent.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/events/LiveEvent.kt
@@ -4,8 +4,7 @@ import kotlinx.serialization.Serializable
 import kotlinx.serialization.json.JsonObject
 
 /**
- * Parsed event from the server's SSE stream. Mirrors
- * the Flutter client's `LiveEvent`.
+ * Parsed event from the server's SSE stream.
  *
  * - [kind] is the SSE `event:` field (e.g. "track.liked", "playlist.deleted").
  * - [userId] is the actor whose user-scoped state changed (empty for
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/events/LiveEventsDispatcher.kt b/android/app/src/main/java/com/fabledsword/minstrel/events/LiveEventsDispatcher.kt
index 46dbd07e..a656f0bc 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/events/LiveEventsDispatcher.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/events/LiveEventsDispatcher.kt
@@ -51,7 +51,7 @@ class LiveEventsDispatcher @Inject constructor(
             "artist.liked",
             "artist.unliked",
             -> refreshLikes()
-            // M489: a contentless nudge; the inbox refetches its newest page.
+            // a contentless nudge; the inbox refetches its newest page.
             "notification.created" -> refreshNotifications()
         }
         // Other kinds (playlist.*, quarantine.*, request.status_changed,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/events/ReconnectBackoff.kt b/android/app/src/main/java/com/fabledsword/minstrel/events/ReconnectBackoff.kt
index fca55601..6a19c2b6 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/events/ReconnectBackoff.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/events/ReconnectBackoff.kt
@@ -3,14 +3,14 @@ package com.fabledsword.minstrel.events
 import kotlin.random.Random
 
 /**
- * How long [EventsStream] waits before reconnecting (M489 #5347).
+ * How long [EventsStream] waits before reconnecting.
  *
  * The stream is wanted around the clock once notifications arrive with the app
  * closed, so a server that is down overnight must not cost a radio wakeup
- * every few seconds: Roundtable's flat 2s came to about 43,000 of them. The
- * wait doubles from [BASE_MS] to [MAX_MS]. The jitter spreads the moment every
- * phone on the server reconnects, which is when the server has just come back
- * and can least take a spike.
+ * every few seconds: a flat 2s retry is 1,800 wakeups an hour. The wait
+ * doubles from [BASE_MS] to [MAX_MS]. The jitter spreads the moment every
+ * phone on the server reconnects, which is when the server has just come
+ * back and can least take a spike.
  *
  * A network coming up (a hint, never a gate) or the app coming to the
  * foreground reconnects at once and starts the ladder over.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/history/data/HistoryRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/history/data/HistoryRepository.kt
index 3414993d..9877b160 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/history/data/HistoryRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/history/data/HistoryRepository.kt
@@ -33,9 +33,7 @@ data class HistoryPage(
 )
 
 /**
- * Cache-first listening history. Mirrors Flutter's `_historyProvider`
- * (`cacheFirst` over the `cached_history_snapshot` drift row with
- * `alwaysRefresh`) using the native Room + Flow idiom:
+ * Cache-first listening history, in the Room + Flow idiom:
  *
  *   - [observeHistory] emits the cached snapshot instantly (null until
  *     the first fetch lands), so the History tab paints from disk on
@@ -47,8 +45,8 @@ data class HistoryPage(
  *
  * The whole page is stored as one JSON blob (single-row table) rather
  * than per-row Room entities — history is a read-only timestamp-keyed
- * snapshot, so a blob is the simplest faithful mirror of the Drift
- * snapshot and avoids ordering/paging bookkeeping for no UX gain.
+ * snapshot, so a blob is the simplest faithful copy and avoids
+ * ordering/paging bookkeeping for no UX gain.
  */
 @Singleton
 class HistoryRepository @Inject constructor(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/history/ui/HistoryTab.kt b/android/app/src/main/java/com/fabledsword/minstrel/history/ui/HistoryTab.kt
index 5a9d436a..245e7a25 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/history/ui/HistoryTab.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/history/ui/HistoryTab.kt
@@ -86,7 +86,7 @@ class HistoryTabViewModel @Inject constructor(
 
     init {
         refresh()
-        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // Screen-level auto-recovery: re-pull when server
         // health returns, so a load that failed offline heals unprompted.
         viewModelScope.launch {
             networkStatus.recoveries().collect { refresh() }
@@ -99,7 +99,7 @@ class HistoryTabViewModel @Inject constructor(
             .onFailure { refreshError.value = ErrorCopy.fromThrowable(it) }
     }
 
-    /** Single-track play, matching the Flutter history-row behavior. */
+    /** Plays the tapped track on its own. */
     fun playTrack(track: TrackRef) {
         if (track.streamUrl.isEmpty()) return
         player.setQueue(listOf(track), initialIndex = 0, source = "history")
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/home/data/HomeRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/home/data/HomeRepository.kt
index 8e3db94a..a2aa761c 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/home/data/HomeRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/home/data/HomeRepository.kt
@@ -33,8 +33,7 @@ import javax.inject.Singleton
  * [MetadataProvider] Flow that emits the cached row (or null while it
  * hydrates) and fires a dedup'd, concurrency-gated on-miss fetch. A
  * null [HomeTile.value] renders as a skeleton in position; the tile
- * reveals when the fetch lands and Room re-emits. Mirrors Flutter's
- * per-item tile providers.
+ * reveals when the fetch lands and Room re-emits.
  *
  * `refreshIndex()` pulls `GET /api/home/index`, swaps all sections in
  * one transaction (so the rows update together in a single emission
@@ -99,8 +98,8 @@ class HomeRepository @Inject constructor(
      * One transaction for all seven sections is deliberate: Room notifies
      * observers once, on commit, so Home swaps from the old content to
      * the new in a single emission. Per-section, un-transacted writes
-     * made every row visibly collapse to empty and refill, one after
-     * another (issue #2327).
+     * would make every row visibly collapse to empty and refill, one
+     * after another.
      */
     suspend fun refreshIndex() {
         val wire = api.getHomeIndex()
@@ -141,7 +140,7 @@ class HomeRepository @Inject constructor(
      * the id list instead means a section whose contents didn't actually
      * move never restarts the `flatMapLatest` below, which would
      * otherwise tear down and rebuild all of its tiles' hydration flows
-     * and flicker unchanged tiles (issue #2327).
+     * and flicker unchanged tiles.
      */
     private fun observeSectionIds(section: String): Flow<List<String>> =
         homeIndexDao.observeBySection(section)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/home/ui/HomeScreen.kt b/android/app/src/main/java/com/fabledsword/minstrel/home/ui/HomeScreen.kt
index 21a4e9cb..511b2888 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/home/ui/HomeScreen.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/home/ui/HomeScreen.kt
@@ -133,7 +133,7 @@ private const val RECENTLY_ADDED_GRID_HEIGHT_DP = 440
 // "Updating your mixes…" veil. UpdateVeilController decides both whether it
 // appears at all — only when a refresh actually changes something — and how
 // long it stays, by watching the screen settle rather than by a fixed delay,
-// which lowered it while tiles and artwork were still landing (#2327).
+// which would lower it while tiles and artwork are still landing.
 // Near-opaque (VEIL_ALPHA) so the section churn never bleeds through.
 private const val VEIL_WIPE_MS = 280
 private const val VEIL_ALPHA = 0.96f
@@ -244,9 +244,8 @@ class HomeViewModel @Inject constructor(
 
     /**
      * Tap on a Most-played tile: replace the queue with the section's
-     * tracks and start at the tapped index. Mirrors Flutter's
-     * `_resolveSectionTracks` — Home's section is itself the playable
-     * unit, not a list of album-detail links.
+     * tracks and start at the tapped index. Home's section is itself the
+     * playable unit, not a list of album-detail links.
      */
     fun playMostPlayed(tracks: List<com.fabledsword.minstrel.models.TrackRef>, startIndex: Int) {
         if (tracks.isEmpty()) return
@@ -259,13 +258,11 @@ class HomeViewModel @Inject constructor(
 
     /**
      * Tap the album play-button overlay: fetch the album detail and
-     * play its tracks from the first. Mirrors Flutter's AlbumCard
-     * `_playAlbum`. Suspending so the button's spinner waits for the
-     * fetch + queue setup; the inner work is launched in viewModelScope
-     * so cancellation from leaving the screen mid-fetch doesn't kill
-     * playback. Errors surface via the snackbar channel (Android
-     * improvement over Flutter's silent-fail; matches the existing
-     * ArtistDetail play handler).
+     * play its tracks from the first. Suspending so the button's spinner
+     * waits for the fetch + queue setup; the inner work is launched in
+     * viewModelScope so cancellation from leaving the screen mid-fetch
+     * doesn't kill playback. Errors surface via the snackbar channel,
+     * like the ArtistDetail play handler.
      */
     suspend fun playAlbum(albumId: String) {
         viewModelScope.launch {
@@ -288,9 +285,8 @@ class HomeViewModel @Inject constructor(
 
     /**
      * Tap the artist play-button overlay: fetch every track across the
-     * artist's albums, Fisher-Yates shuffle, play from index 0. Mirrors
-     * Flutter's ArtistCard `_playArtistShuffle`. Empty + error semantics
-     * follow [playAlbum].
+     * artist's albums, Fisher-Yates shuffle, play from index 0. Empty +
+     * error semantics follow [playAlbum].
      */
     suspend fun playArtistShuffled(artistId: String) {
         viewModelScope.launch {
@@ -315,9 +311,8 @@ class HomeViewModel @Inject constructor(
      * Tap the playlist play-button overlay: fetch the playlist's tracks
      * (rotation-aware shuffle for refreshable system playlists, stored
      * order for everything else), 8s timeout, play from index 0.
-     * Mirrors Flutter PlaylistCard `_playPlaylist`. Empty-mix and
-     * timeout get their own copy strings; other errors fall through to
-     * [ErrorCopy.fromThrowable].
+     * Empty-mix and timeout get their own copy strings; other errors
+     * fall through to [ErrorCopy.fromThrowable].
      */
     suspend fun playPlaylist(playlist: PlaylistRef) {
         viewModelScope.launch {
@@ -366,9 +361,9 @@ class HomeViewModel @Inject constructor(
     fun retry() = veil.request(userInitiated = true)
 
     /**
-     * Manual pull-to-refresh. Goes behind the veil like every other refresh
-     * (operator call, 2026-07-31: the churn a pull causes is identical to
-     * the automatic paths, and a small spinner didn't hide it).
+     * Manual pull-to-refresh. Goes behind the veil like every other
+     * refresh: a pull churns the screen exactly as the automatic paths
+     * do, and a small spinner does not hide it.
      *
      * Suspends until the veil has taken over OR the session has finished,
      * so the pull indicator hands off to exactly one successor: the veil if
@@ -488,7 +483,7 @@ class HomeViewModel @Inject constructor(
      * Only user-initiated sessions say anything. The same outcome from a
      * background check — the initial load, the 03:00 rebuild, a reconnect —
      * is noise, and "Already up to date" on every launch would be worse
-     * than silence (operator's call, 2026-07-31).
+     * than silence.
      */
     private fun reportRefreshOutcome(result: VeilSessionResult) {
         if (!result.userInitiated) return
@@ -505,7 +500,7 @@ class HomeViewModel @Inject constructor(
      *
      * Raised only when a refresh actually changes what's on screen, and then
      * held until Home settles — tiles hydrated, artwork loaded — instead of
-     * for a fixed delay after the network pull returns (issue #2327). A
+     * for a fixed delay after the network pull returns. A
      * refresh that returns what's already cached shows no veil at all;
      * [reportRefreshOutcome] tells the user instead, if they asked.
      */
@@ -515,9 +510,9 @@ class HomeViewModel @Inject constructor(
         // Every refresh path goes through the controller, which decides
         // per session whether to raise the veil. That includes the initial
         // load: over a warm cache it's a full re-pull that churns every
-        // section, and it used to run completely unveiled.
+        // section.
         veil.request()
-        // Screen-level auto-recovery (issue #1245): a Home that failed to
+        // Screen-level auto-recovery: 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.
         // This is also the recovery that keeps trying after the veil has
@@ -525,9 +520,8 @@ class HomeViewModel @Inject constructor(
         viewModelScope.launch {
             networkStatus.recoveries().collect { veil.request() }
         }
-        // Server-side changes that rewrite what Home renders (#968 and
-        // the 2026-07-31 widening) re-pull behind the veil. Mirrors the
-        // web SSE consumer.
+        // Server-side changes that rewrite what Home renders re-pull
+        // behind the veil, as the web SSE consumer does.
         viewModelScope.launch {
             eventsStream.events
                 .filter { it.kind in VEILED_EVENT_KINDS }
@@ -758,8 +752,7 @@ private fun HomeSuccessContent(
             // Always rendered: real system/user playlists, with
             // 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.
+            // pool cards lead the row. Songs-like has its own row below.
             PlaylistsRow(
                 title = "Playlists",
                 rowItems = buildPlaylistsRow(sections.playlists, systemStatus, offline),
@@ -769,10 +762,9 @@ 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).
+        // Songs-like gets its own row so it can show a wider spread of
+        // "Songs like {artist}" mixes than a carousel slot allows. Hidden
+        // when there's nothing to show (offline with none cached).
         songsLikeSection(
             playlists = sections.playlists,
             status = systemStatus,
@@ -805,11 +797,11 @@ private fun HomeSuccessContent(
 }
 
 /**
- * The dedicated "Songs like…" row (#1491). Reuses [PlaylistsRow]'s card
+ * The dedicated "Songs like…" row. 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.
+ * visible.
  */
 private fun LazyListScope.songsLikeSection(
     playlists: List<PlaylistRef>,
@@ -1000,7 +992,7 @@ private fun EmptySection(title: String, body: String) {
 /**
  * Rediscover may have both an albums sub-row and an artists sub-row. When
  * both are present the artist row gets an empty title so the section
- * reads as a single visual block — matches the Flutter behavior.
+ * reads as a single visual block.
  */
 @Composable
 private fun RediscoverBlock(
@@ -1164,18 +1156,12 @@ enum class OfflinePoolKind(val label: String) {
  * 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. Songs-like has its own dedicated row (#1491) via
- * [buildSongsLikeRow] and no longer appears in this carousel.
+ * user-owned playlists. Songs-like has its own row via [buildSongsLikeRow].
  *
  * Offline: the two cache-backed pools (Recently played, Liked) lead, then the
  * same real playlists in curated order but stably partitioned fully-cached
  * first / greyed after, and the "building/pending" placeholders are dropped
  * (they need the server to generate, so they're meaningless offline).
- *
- * Diverges from Flutter (the Flutter client
- * `_buildPlaylistsRow`) which only shows the 5 fixed slots and never
- * surfaces the secondary kinds on Home. Operator authorized the
- * divergence on 2026-06-01; web UI catch-up tracked as task #53.
  */
 internal fun buildPlaylistsRow(
     owned: List<PlaylistRef>,
@@ -1204,7 +1190,7 @@ private fun buildOnlineRow(
     out += owned.firstOrNull { it.systemVariant == "discover" }
         ?.let { PlaylistRowItem.Real(it) }
         ?: PlaylistRowItem.Placeholder("Discover", variantFor("discover", status))
-    // Songs-like is no longer here — it has its own dedicated row (#1491).
+    // Songs-like is not here: it has its own row.
     for (variant in SECONDARY_SYSTEM_VARIANTS) {
         owned.firstOrNull { it.systemVariant == variant }?.let { out += PlaylistRowItem.Real(it) }
     }
@@ -1213,8 +1199,8 @@ private fun buildOnlineRow(
 }
 
 /**
- * Builds the dedicated Songs-like row (#1491): all "Songs like {artist}"
- * mixes the server generated, no longer capped to the 3 carousel slots.
+ * Builds the dedicated Songs-like row: every "Songs like {artist}" mix
+ * the server generated, uncapped.
  *
  * Online: every generated mix as a real card; when none exist yet, a few
  * placeholders so the building / seed-needed state stays visible.
@@ -1244,7 +1230,7 @@ internal fun buildSongsLikeRow(
  * 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).
+ * [buildSongsLikeRow] in both online and offline modes.
  */
 private fun orderedRealPlaylists(owned: List<PlaylistRef>): List<PlaylistRef> {
     val out = mutableListOf<PlaylistRef>()
@@ -1266,7 +1252,7 @@ private fun variantFor(slot: String, s: SystemPlaylistsStatus): String = when {
 
 // 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).
+// once generated, are shown in full, uncapped.
 private const val SONGS_LIKE_PLACEHOLDER_SLOTS = 3
 
 /**
@@ -1308,8 +1294,7 @@ private fun ArtistsRow(
 /**
  * Most-played section. Renders compact track tiles (cover + title + artist).
  * Tapping a tile replaces the queue with the entire section starting
- * at that tile — mirrors Flutter's `_resolveSectionTracks` behaviour
- * where Home sections are themselves playable units.
+ * at that tile — Home sections are themselves playable units.
  */
 @Composable
 private fun MostPlayedRow(
@@ -1373,12 +1358,8 @@ private const val MOST_PLAYED_TILE_HEIGHT_DP = 56
 private const val MOST_PLAYED_COVER_DP = 48
 
 // 3 rows of MOST_PLAYED_TILE_HEIGHT_DP + 2 * 8dp inter-row spacing,
-// rounded up. Mirrors Flutter (`CompactTrackCard` in
-// the Flutter client) which
-// uses a horizontal-row card pattern - much denser than the square
-// per-track tiles that web uses (operator request 2026-06-01: "in the
-// flutter iteration the tiles were different and smaller so more of
-// them could fit in a smaller space").
+// rounded up. Horizontal-row cards, much denser than the square
+// per-track tiles web uses, so more tracks fit in less space.
 private const val MOST_PLAYED_GRID_HEIGHT_DP = 200
 
 @Composable
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/data/LibraryRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/data/LibraryRepository.kt
index 90749260..517a38b3 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/data/LibraryRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/data/LibraryRepository.kt
@@ -23,10 +23,9 @@ import javax.inject.Singleton
  * server and upsert into Room — the Flow emissions then propagate
  * automatically.
  *
- * Constructs its own LibraryApi from the shared Retrofit. Per the
- * "repositories own their interfaces" pattern adopted in Phase 5.1's
- * NetworkModule, we don't @Provides per-endpoint Retrofit interfaces
- * — fewer Hilt bindings, locality of reference.
+ * Constructs its own LibraryApi from the shared Retrofit: repositories
+ * own their interfaces (see NetworkModule), so there is no @Provides
+ * per endpoint — fewer Hilt bindings, locality of reference.
  */
 // LibraryRepository owns reads + refreshes for three entity families
 // (artists / albums / tracks) plus shuffle. Function count scales with
@@ -46,8 +45,7 @@ class LibraryRepository @Inject constructor(
 
     // Joins each artist to its first cached album (by sort title) so the
     // tile cover derives from /api/albums/{id}/cover — cached_artists
-    // stores no cover and sync carries none. Mirrors Flutter's
-    // artistTileProvider JOIN.
+    // stores no cover and sync carries none.
     fun observeArtists(): Flow<List<ArtistRef>> =
         combine(artistDao.observeAll(), albumDao.observeAll()) { artists, albums ->
             val firstAlbumByArtist = albums
@@ -161,13 +159,12 @@ class LibraryRepository @Inject constructor(
     suspend fun shuffleLibrary(limit: Int = SHUFFLE_DEFAULT_LIMIT): List<TrackRef> =
         api.shuffleLibrary(limit = limit).map { it.toDomain() }
 
-    // ---- Browse axes (#367 / #2467) ----
+    // ---- Browse axes ----
     //
-    // Server-backed rather than cache-first, unlike everything above. The
-    // cache mirrors the whole library but includes tracks whose files are
-    // missing, with no flag to spot them (#2704), while the server's index
-    // excludes them -- so a locally-derived index would quietly disagree with
-    // the web client's. Revisit when #2704 lands.
+    // Server-backed rather than cache-first, unlike everything above: the
+    // server's index leaves out tracks whose files are missing and is the
+    // one the web client shows. See LibraryApi for why the cache's own
+    // missing mark is not used to build it locally.
 
     /** Genre index, ordered by track count then name (server order). */
     suspend fun genres(): List<GenreCount> =
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/AlbumDetailViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/AlbumDetailViewModel.kt
index abdba847..6a6ad4a9 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/AlbumDetailViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/AlbumDetailViewModel.kt
@@ -67,7 +67,7 @@ class AlbumDetailViewModel @Inject constructor(
 
     init {
         refresh()
-        // Screen-level auto-recovery (issue #1245): a detail that failed to
+        // Screen-level auto-recovery: 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 {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailScreen.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailScreen.kt
index 398b4e90..d4eaf3bb 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailScreen.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailScreen.kt
@@ -310,9 +310,9 @@ private fun ArtistHeader(
 
 @Composable
 private fun ArtistAvatar(artist: ArtistRef, fallbackAlbumId: String? = null) {
-    // Server coverUrl wins; otherwise mirror the server's "use the
-    // first album's cover" rule via the loaded album list (Flutter
-    // _ArtistAvatar). Bare Lucide.User only when neither exists.
+    // Server coverUrl wins; otherwise use the first loaded album's
+    // cover, the same rule the server applies. Bare Lucide.User only
+    // when neither exists.
     val model = when {
         artist.coverUrl.isNotEmpty() -> artist.coverUrl
         fallbackAlbumId != null -> albumCoverPath(fallbackAlbumId)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailViewModel.kt
index bf33fcc9..ee27ba6d 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/ArtistDetailViewModel.kt
@@ -72,7 +72,7 @@ class ArtistDetailViewModel @Inject constructor(
 
     init {
         refresh()
-        // Screen-level auto-recovery (issue #1245). From Error, redo the
+        // Screen-level auto-recovery. 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.
@@ -139,10 +139,9 @@ class ArtistDetailViewModel @Inject constructor(
 
     /**
      * Pull every track across the artist's albums, shuffle, and start
-     * playing. Mirrors Flutter's artist Play button — pressing Play on
-     * an artist is implicitly "shuffle this artist", not "play album by
-     * album in tracklist order". Network round-trip per click; fine
-     * because the user explicitly tapped Play.
+     * playing. Pressing Play on an artist means "shuffle this artist",
+     * not "play album by album in tracklist order". One network
+     * round-trip per click; fine because the user explicitly tapped Play.
      */
     fun playArtist() {
         viewModelScope.launch {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/BrowseViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/BrowseViewModel.kt
index 957c1ed4..393a1a73 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/BrowseViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/BrowseViewModel.kt
@@ -42,15 +42,12 @@ data class AlbumBrowseState(
 }
 
 /**
- * Backs the Genres and Years tabs (#2467), mirroring the web surfaces #367
- * shipped.
+ * Backs the Genres and Years tabs, the same browse axes the web client has.
  *
- * Both indexes come from the server, which is a deliberate departure from the
- * cache-first Artists/Albums tabs beside them: the local cache includes tracks
- * whose files are missing and cannot tell you which (#2704), while the server's
- * index excludes them, so a locally-derived index would disagree with the web
- * client's. These two tabs therefore need a connection; the empty states say so
- * rather than looking broken.
+ * Both indexes come from the server, unlike the cache-first Artists/Albums
+ * tabs beside them: the server's index leaves out tracks whose files are
+ * missing and matches the web client's. These two tabs therefore need a
+ * connection; the empty states say so rather than looking broken.
  */
 // Two browse axes, each with an index, a filter/sort or grouping, a
 // drill-down and a pager. The function count is two axes' worth of a
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/GenresTab.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/GenresTab.kt
index cf0290e2..b9153327 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/GenresTab.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/GenresTab.kt
@@ -41,7 +41,7 @@ import com.fabledsword.minstrel.shared.widgets.EmptyState
 import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 
 /**
- * Genres tab (#2467) — the Android half of the browse axis #367 shipped on web.
+ * Genres tab: the genre browse axis, as on web.
  *
  * Two states in one tab rather than a navigation destination: the index, and
  * the albums for a chosen genre. Back returns to the index. A route would have
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/LibraryScreen.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/LibraryScreen.kt
index 7d31d1b4..50f5f8a2 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/LibraryScreen.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/LibraryScreen.kt
@@ -54,17 +54,11 @@ import com.fabledsword.minstrel.shared.widgets.SkeletonArtistTile
 /**
  * Library tab. Seven-tab TabBar (Artists / Albums / Genres / Years /
  * History / Liked / Hidden), matching the web client's library tab bar.
- * Genres and Years arrived with #2467; the rest predate it and mirrored
- * the Flutter client.
  *
- * Artists + Albums are wired against the existing LibraryViewModel
- * (cache-first reads of cached_artists / cached_albums). The other
- * three tabs render placeholder EmptyStates pointing at the upcoming
- * data-layer phases:
- *   - History → Phase 9 (server-side /api/me/history wiring)
- *   - Liked   → Phase 8 (likes write path + cached_likes hydration)
- *   - Hidden  → Phase 10 (quarantine flag/unflag UI lives in Admin slice
- *               but the user-side "my hidden tracks" view comes here)
+ * Artists + Albums are cache-first reads of cached_artists /
+ * cached_albums through LibraryViewModel; Genres and Years read the
+ * server through BrowseViewModel; History, Liked and Hidden are their
+ * own tabs ([HistoryTab], [LikedTab], [HiddenTab]).
  */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
@@ -160,7 +154,7 @@ private const val TAB_LIKED = 5
 private const val TAB_HIDDEN = 6
 
 // Genres and Years sit straight after Albums, matching the web tab bar's
-// order (#2467) -- they are browse axes over the same albums, so they belong
+// order -- they are browse axes over the same albums, so they belong
 // beside them rather than after the personal tabs.
 private val LIBRARY_TABS =
     listOf("Artists", "Albums", "Genres", "Years", "History", "Liked", "Hidden")
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/YearsTab.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/YearsTab.kt
index b4d53c0a..eb15d504 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/ui/YearsTab.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/ui/YearsTab.kt
@@ -26,7 +26,7 @@ import com.fabledsword.minstrel.shared.widgets.EmptyState
 import com.fabledsword.minstrel.shared.widgets.ErrorRetry
 
 /**
- * Years tab (#2467). Same two-state shape as [GenresTab]: the decade-grouped
+ * Years tab. Same two-state shape as [GenresTab]: the decade-grouped
  * index, then the albums for a chosen year.
  *
  * Albums with no release date are absent from this axis entirely — the server
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/widgets/AlbumCard.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/widgets/AlbumCard.kt
index 462472a2..998b05b8 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/widgets/AlbumCard.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/widgets/AlbumCard.kt
@@ -25,16 +25,15 @@ import com.fabledsword.minstrel.shared.widgets.PlayCircleButton
 import androidx.compose.ui.Alignment
 
 /**
- * One album tile. Mirrors the Flutter `AlbumCard` (~176dp wide, 144dp
- * square cover). Tap fires `onClick` — wired to `AlbumDetail` nav in
- * Phase 5.5. The tile stashes its `album` in [LocalDetailSeedCache]
+ * One album tile (~176dp wide, 144dp square cover). Tap fires
+ * `onClick`. The tile stashes its `album` in [LocalDetailSeedCache]
  * before firing onClick so the detail screen's AppBar renders title /
  * cover / counts immediately without waiting for the fetch.
  *
  * [onPlay] is an opt-in play-overlay handler. When non-null, a 44dp
- * circular play button is overlaid at the bottom-right of the cover
- * (mirrors Flutter's PlayCircleButton). Only Home wires it currently;
- * Library / Discover / detail surfaces leave it null.
+ * circular play button is overlaid at the bottom-right of the cover.
+ * Only Home wires it currently; Library / Discover / detail surfaces
+ * leave it null.
  */
 @Composable
 fun AlbumCard(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/library/widgets/ArtistCard.kt b/android/app/src/main/java/com/fabledsword/minstrel/library/widgets/ArtistCard.kt
index 3d0e8e34..e426a5d0 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/library/widgets/ArtistCard.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/library/widgets/ArtistCard.kt
@@ -28,15 +28,13 @@ import com.fabledsword.minstrel.shared.widgets.PlayCircleButton
 
 /**
  * One artist tile. Circular cover; name centered beneath. Tap fires
- * `onClick` — wired to `ArtistDetail` nav in Phase 5.5. Stashes the
- * `artist` in [LocalDetailSeedCache] on click so the ArtistDetail
- * AppBar renders the name before the fetch lands.
+ * `onClick`. Stashes the `artist` in [LocalDetailSeedCache] on click
+ * so the ArtistDetail AppBar renders the name before the fetch lands.
  *
  * [onPlay] is an opt-in play-overlay handler. When non-null, a 44dp
- * circular play button is overlaid at the bottom-right of the avatar
- * (mirrors Flutter's PlayCircleButton). Only Home wires it currently.
- * Padding is 4dp instead of 6dp because the circular avatar pulls the
- * button visually inward at the corner.
+ * circular play button is overlaid at the bottom-right of the avatar.
+ * Only Home wires it currently. Padding is 4dp instead of 6dp because
+ * the circular avatar pulls the button visually inward at the corner.
  */
 @Composable
 fun ArtistCard(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/likes/data/LikesRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/likes/data/LikesRepository.kt
index f5e009f5..ba215019 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/likes/data/LikesRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/likes/data/LikesRepository.kt
@@ -24,26 +24,21 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Cache-first reads + offline-first writes for likes. Mirrors the
- * Flutter `likesControllerProvider` + `cached_likes`-driven Liked tab
- * pattern.
+ * Cache-first reads + offline-first writes for likes.
  *
- * Local `userId` discriminator is the server-side user UUID
- * (resolved via [AuthController.currentUser]); falls back to
- * [ANONYMOUS_USER_ID] when no user is signed in so existing local
- * cache rows from pre-#576 builds remain queryable until the first
- * authenticated [refreshIds] call overwrites them. On user-switch
- * (sign-out / sign-in as different user) the OUTGOING user's
- * cached_likes rows are wiped so they don't leak into the new
- * session — drift #576 audit caught the leak.
+ * The local `userId` discriminator is the server-side user UUID
+ * (resolved via [AuthController.currentUser]); it falls back to
+ * [ANONYMOUS_USER_ID] when no user is signed in, so rows in that bucket
+ * stay queryable until the first authenticated [refreshIds] call
+ * overwrites them. On user-switch (sign-out / sign-in as a different
+ * user) the OUTGOING user's cached_likes rows are wiped so they don't
+ * leak into the new session.
  *
- * Write path follows `feedback_offline_first_for_server_writes` —
- * never fire-and-forget:
+ * Writes never go fire-and-forget:
  *   1. Optimistic Room mutation (UI flips instantly).
  *   2. Best-effort server call.
- *   3. On exception → enqueue in MutationQueue for the Phase 12.2
- *      replayer to drain when connectivity returns.
- *
+ *   3. On exception → enqueue in MutationQueue for the replayer to
+ *      drain when connectivity returns.
  * Reads expose Flows of hydrated DomainRefs. Per-tile hydration goes
  * through the existing Library DAOs — IDs without cached entity rows
  * are silently dropped (the SyncController fills the gap async).
@@ -62,12 +57,10 @@ class LikesRepository @Inject constructor(
     private val api: LikesApi = retrofit.create()
 
     init {
-        // Drift #576: clear the outgoing user's cached_likes rows
-        // when the signed-in user changes. Mostly a hygiene fix —
-        // discriminator-based queries already prevent the wrong
-        // user from SEEING leaked rows, but without this the rows
-        // pile up forever as different accounts sign in/out on the
-        // same device.
+        // Clear the outgoing user's cached_likes rows when the signed-in
+        // user changes. Discriminator-based queries already keep the wrong
+        // user from SEEING them; without this the rows pile up forever as
+        // different accounts sign in/out on the same device.
         scope.launch {
             var previousId: String? = null
             authController.currentUser.collect { user ->
@@ -138,7 +131,7 @@ class LikesRepository @Inject constructor(
      */
     suspend fun toggleLike(entityType: String, entityId: String, desiredState: Boolean): Boolean {
         // 1. Optimistic Room mutation — scoped to the signed-in user
-        //    (or the legacy "local" fallback for pre-#576 rows).
+        //    (or the "local" bucket when nobody is signed in).
         val uid = currentUserId()
         if (desiredState) {
             likeDao.upsertAll(
@@ -157,8 +150,7 @@ class LikesRepository @Inject constructor(
         ) {
             // Intentional swallow: the queue replays this later; surfacing
             // the network error here would force callers (UI) to handle it
-            // even though it's already been buffered. The replayer logs
-            // per-attempt diagnostics when it lands in Phase 12.2.
+            // even though it's already been buffered.
             mutationQueue.enqueueLikeToggle(entityType, entityId, desiredState)
             false
         }
@@ -166,17 +158,14 @@ class LikesRepository @Inject constructor(
 
     /**
      * Pulls `GET /api/likes/ids` and atomically replaces the user's
-     * cached_likes set with the server's canonical view. Called by
-     * the LikedTab ViewModel on init (and by the SyncController in
-     * Phase 12).
+     * cached_likes set with the server's canonical view. Called by the
+     * LikedTab ViewModel on init and on a live likes event.
      *
-     * Drift #570 fix: previously this called `upsertAll` only, which
-     * added rows for IDs the server had but never removed rows the
-     * server no longer surfaced — so a cross-device unlike (user
-     * likes on web, then unlikes on web) left the Liked tab on
-     * Android showing the now-unliked entry forever. The atomic
-     * replaceAllForUser DAO method runs a transactional delete-then-
-     * insert so the local set is exactly what the server reports.
+     * A replace, not an upsert: upserts add rows for IDs the server has
+     * but never remove the ones it dropped, so an unlike made on another
+     * device would stay on the Liked tab forever. The replaceAllForUser
+     * DAO method runs a transactional delete-then-insert so the local
+     * set is exactly what the server reports.
      */
     suspend fun refreshIds() {
         val uid = currentUserId()
@@ -189,13 +178,10 @@ class LikesRepository @Inject constructor(
     }
 
     companion object {
-        // Pre-auth fallback discriminator. Drift #576: when no user is
-        // signed in OR for cached_likes rows written by pre-#576
-        // builds (which all tagged "local"), reads continue to query
-        // this bucket so the Liked tab isn't suddenly empty after the
-        // upgrade. The first authenticated refreshIds() call writes
-        // rows under the real user UUID; reads then transparently
-        // switch over via currentUserId().
+        // Fallback discriminator for when no user is signed in. Reads
+        // query this bucket until the first authenticated refreshIds()
+        // writes rows under the real user UUID; reads then switch over
+        // via currentUserId().
         const val ANONYMOUS_USER_ID: String = "local"
         const val ENTITY_ARTIST: String = "artist"
         const val ENTITY_ALBUM: String = "album"
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/likes/ui/LikedTab.kt b/android/app/src/main/java/com/fabledsword/minstrel/likes/ui/LikedTab.kt
index 393a4b82..72af673f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/likes/ui/LikedTab.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/likes/ui/LikedTab.kt
@@ -81,7 +81,7 @@ class LikedTabViewModel @Inject constructor(
 
     init {
         refresh()
-        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // Screen-level auto-recovery: re-pull when server
         // health returns, so a load that failed offline heals unprompted.
         viewModelScope.launch {
             networkStatus.recoveries().collect { refresh() }
@@ -122,8 +122,8 @@ class LikedTabViewModel @Inject constructor(
 
     /**
      * Build a queue from the currently-displayed liked tracks and start
-     * playback at [initialIndex]. Mirrors Flutter's tap-on-liked-track
-     * behavior: the visible track list becomes the play queue. Tracks
+     * playback at [initialIndex]: the visible track list becomes the
+     * play queue. Tracks
      * with empty streamUrl are ignored as queue entries (the row that
      * routes here is itself click-gated on streamUrl).
      */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/metadata/HomeArtistPrewarmer.kt b/android/app/src/main/java/com/fabledsword/minstrel/metadata/HomeArtistPrewarmer.kt
index a89b39e6..d944cfaa 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/metadata/HomeArtistPrewarmer.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/metadata/HomeArtistPrewarmer.kt
@@ -7,11 +7,11 @@ import javax.inject.Singleton
 private const val TOP_N = 8
 
 /**
- * Pre-warms the Room cache for likely-tap artist tiles on Home. Mirrors
- * Flutter's `MetadataPrefetcher`: conservative — artists only (a single
- * round-trip per id), top-8 per call, and once per id per session so
- * repeated index refreshes don't re-fetch. Albums are intentionally not
- * pre-warmed (their detail fetch fans out a track list).
+ * Pre-warms the Room cache for likely-tap artist tiles on Home.
+ * Conservative: artists only (a single round-trip per id), top-8 per
+ * call, and once per id per session so repeated index refreshes don't
+ * re-fetch. Albums are intentionally not pre-warmed (their detail fetch
+ * fans out a track list).
  *
  * Fetches go through [MetadataProvider.refreshArtist], so they share the
  * same per-id dedup AND the 4-slot concurrency gate as on-render
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/metadata/MetadataProvider.kt b/android/app/src/main/java/com/fabledsword/minstrel/metadata/MetadataProvider.kt
index 4e6c06e4..3ffdb9c0 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/metadata/MetadataProvider.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/metadata/MetadataProvider.kt
@@ -29,10 +29,8 @@ private const val HTTP_NOT_FOUND = 404
 /**
  * Cache-first metadata reads with eager on-miss live-fetch.
  *
- * Mirrors Flutter's tile-provider pattern (`albumTileProvider(id)` /
- * `artistTileProvider(id)` / `trackTileProvider(id)`): subscribers
- * observe a per-ID Flow that emits the Room row immediately if
- * present, and otherwise triggers a single background fetch that
+ * Subscribers observe a per-ID Flow that emits the Room row immediately
+ * if present, and otherwise triggers a single background fetch that
  * upserts into Room — the flow then re-emits the populated row.
  *
  * Fetch dedup is per-ID via a ConcurrentHashMap of in-flight Jobs;
@@ -57,9 +55,8 @@ class MetadataProvider @Inject constructor(
     private val inFlightTracks = ConcurrentHashMap<String, Job>()
 
     // Caps concurrent on-miss fetches so a cold Home (~30 tiles) doesn't
-    // fire ~30 parallel /api calls. Mirrors Flutter HydrationQueue's
-    // _maxConcurrent = 4. Per-id dedup (above) is orthogonal: the gate
-    // bounds distinct-id fetches; extras suspend on the semaphore.
+    // fire ~30 parallel /api calls. Per-id dedup (above) is orthogonal:
+    // the gate bounds distinct-id fetches; extras suspend on the semaphore.
     private val fetchGate = Semaphore(MAX_CONCURRENT_FETCHES)
 
     /**
@@ -123,7 +120,7 @@ class MetadataProvider @Inject constructor(
      * [onGone] runs when the server answers 404: the row no longer exists
      * there (a duplicate merge, a deleted file), so the cached copy is
      * dropped. Kept, it stays stale forever and [FreshnessSweeper] asks for
-     * it every pass (#5654). Any other failure leaves the row for a retry.
+     * it every pass. Any other failure leaves the row for a retry.
      */
     private fun launchDeduped(
         inFlight: ConcurrentHashMap<String, Job>,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/AdminQuarantineItem.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/AdminQuarantineItem.kt
index 5ca7071b..f759a69c 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/AdminQuarantineItem.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/AdminQuarantineItem.kt
@@ -14,7 +14,7 @@ data class AdminQuarantineReportRef(
 /**
  * Aggregated quarantine row in the admin queue — all reports against a
  * single track collapsed into per-reason counts plus the underlying
- * per-user reports. Mirrors Flutter's `AdminQuarantineItem`.
+ * per-user reports.
  *
  * `topReasonSummary` returns the most-cited reason, with a "(+N more)"
  * suffix when other distinct reasons exist.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/AdminTagSourceRef.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/AdminTagSourceRef.kt
index f892c7aa..54e63295 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/AdminTagSourceRef.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/AdminTagSourceRef.kt
@@ -1,6 +1,6 @@
 package com.fabledsword.minstrel.models
 
-/** Domain model for one tag-enrichment provider in the admin surface (#1521). */
+/** Domain model for one tag-enrichment provider in the admin surface. */
 data class AdminTagSourceRef(
     val id: String,
     val displayName: String,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/AdminUserRef.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/AdminUserRef.kt
index 96fa7bd5..0d19b4ec 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/AdminUserRef.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/AdminUserRef.kt
@@ -1,7 +1,7 @@
 package com.fabledsword.minstrel.models
 
 /**
- * One admin-side user row. Mirrors Flutter's `AdminUser`. The
+ * One admin-side user row. The
  * admin-scoped variant exposes `autoApproveRequests` and the
  * canonical `createdAt` that the user-scoped /me response omits.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/AlbumRef.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/AlbumRef.kt
index 512565f1..a24a5d53 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/AlbumRef.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/AlbumRef.kt
@@ -1,8 +1,7 @@
 package com.fabledsword.minstrel.models
 
 /**
- * Lightweight reference to one album. Mirrors
- * the Flutter client's `AlbumRef`.
+ * Lightweight reference to one album.
  *
  * `coverUrl` and `durationSec` match the server contract (not
  * `cover_art_url` / `duration_ms`). `year` is omitempty server-side so
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/ArtistRef.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/ArtistRef.kt
index 73dbf1f1..190fba87 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/ArtistRef.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/ArtistRef.kt
@@ -1,8 +1,7 @@
 package com.fabledsword.minstrel.models
 
 /**
- * Lightweight reference to one artist. Mirrors
- * the Flutter client's `ArtistRef`.
+ * Lightweight reference to one artist.
  *
  * `coverUrl` is the server's field name (NOT cover_art_url). Server emits
  * empty string when the artist has no representative album cover; UI code
@@ -23,9 +22,8 @@ data class ArtistRef(
      * first cached album's `/api/albums/{id}/cover` via [coverAlbumId].
      *
      * The fallback matters because cached_artists stores no cover and
-     * the sync payload carries none — so for cache-sourced artist tiles
-     * we mirror Flutter's `artistTileProvider`, which JOINs the first
-     * album to supply the cover. Resolve through `ServerImage`.
+     * the sync payload carries none — so cache-sourced artist tiles take
+     * the first album's cover instead. Resolve through `ServerImage`.
      */
     val displayCoverUrl: String?
         get() = when {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/Discover.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/Discover.kt
index b51729b9..b320ee11 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/Discover.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/Discover.kt
@@ -43,15 +43,15 @@ data class SeedContributionRef(
 
 /**
  * Out-of-library artist suggestion from `GET /api/discover/suggestions`.
- * `attributionText` mirrors Flutter's SuggestionFeed.attributionText
- * (Oxford-comma, max 3 seeds) so the subtitle reads naturally.
+ * `attributionText` names up to 3 seeds with an Oxford comma so the
+ * subtitle reads naturally.
  */
 data class ArtistSuggestionRef(
     val mbid: String,
     val name: String,
     val imageUrl: String = "",
     val attribution: List<SeedContributionRef> = emptyList(),
-    /** Taste-profile tags this candidate matches, strongest first (#2377). */
+    /** Taste-profile tags this candidate matches, strongest first. */
     val matchedTags: List<String> = emptyList(),
 ) {
     val attributionText: String
@@ -72,10 +72,9 @@ data class ArtistSuggestionRef(
      *
      * Prefers the taste-tag reason over seed attribution when we have one,
      * because it describes the MUSIC ("sounds like what you like") rather than
-     * the graph ("adjacent to something you played") — the whole point of
-     * milestone #268 slice 6. Falls back to attribution, which is the common
-     * case: tag coverage for out-of-library artists is partial by nature
-     * (#2376), so most candidates have no matched tags.
+     * the graph ("adjacent to something you played"). Falls back to
+     * attribution, which is the common case: tag coverage for out-of-library
+     * artists is partial by nature, so most candidates have no matched tags.
      *
      * Kept in lockstep with the web client's reasonText() in
      * SuggestionFeed.svelte — same wording, same Oxford comma.
@@ -97,7 +96,7 @@ data class ArtistSuggestionRef(
 }
 
 /**
- * A suggestion the user parked with "not right now" (#2374).
+ * A suggestion the user parked with "not right now".
  *
  * Deliberately NOT a dislike: it carries no verdict on the artist, expires on
  * its own, and never reaches the taste profile. Anything that treats this as
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/Invite.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/Invite.kt
index 5513da15..aa403b44 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/Invite.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/Invite.kt
@@ -1,9 +1,8 @@
 package com.fabledsword.minstrel.models
 
 /**
- * Domain shape for one admin-issued registration invite. Mirrors
- * the Flutter client's `Invite` and the server's
- * `inviteResp` from `internal/api/admin_invites.go`.
+ * Domain shape for one admin-issued registration invite, from the
+ * server's `inviteResp` in `internal/api/admin_invites.go`.
  *
  * `invitedBy` and `redeemedBy` are UUIDs of users (not usernames);
  * the server doesn't denormalise. TTL is hardcoded server-side at
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/ListenBrainzStatus.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/ListenBrainzStatus.kt
index 70175138..71891b62 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/ListenBrainzStatus.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/ListenBrainzStatus.kt
@@ -1,9 +1,8 @@
 package com.fabledsword.minstrel.models
 
 /**
- * Caller's ListenBrainz integration state. Mirrors
- * the Flutter client's `ListenBrainzStatus`
- * and the server's `listenBrainzResp`.
+ * Caller's ListenBrainz integration state, from the server's
+ * `listenBrainzResp`.
  *
  * The token itself is never read back from the server — `tokenSet`
  * is the visible signal. Empty `lastScrobbledAt` means no scrobble
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/MyProfile.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/MyProfile.kt
index 44695010..c407f2a3 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/MyProfile.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/MyProfile.kt
@@ -1,8 +1,8 @@
 package com.fabledsword.minstrel.models
 
 /**
- * Domain shape for the caller's account profile. Mirrors Flutter's
- * `MyProfile`. `displayName` and `email` are nullable — server stores
+ * Domain shape for the caller's account profile. `displayName` and
+ * `email` are nullable — server stores
  * null when the user hasn't set them yet (registration only requires
  * a username).
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/Playlist.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/Playlist.kt
index 676eb33c..17af814a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/Playlist.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/Playlist.kt
@@ -2,7 +2,6 @@ package com.fabledsword.minstrel.models
 
 /**
  * Lightweight reference to one playlist (user or system-generated).
- * Mirrors the Flutter client's `Playlist`.
  *
  * `systemVariant` discriminates user vs. system playlists — null for
  * user-owned, one of "for_you" / "discover" / "songs_like_artist" / etc.
@@ -26,10 +25,9 @@ data class PlaylistRef(
     val isSystem: Boolean get() = systemVariant != null
 
     /**
-     * Whether the "Regenerate" affordance applies. Mirrors Flutter's
-     * `Playlist.refreshable`: every system playlist EXCEPT
-     * songs_like_artist (server's *songs-like-X* family doesn't
-     * expose a refresh trigger; rebuilds are scheduler-driven).
+     * Whether the "Regenerate" affordance applies: every system playlist
+     * EXCEPT songs_like_artist (the server's songs-like family exposes no
+     * refresh trigger; rebuilds are scheduler-driven).
      */
     val refreshable: Boolean get() = isSystem && systemVariant != "songs_like_artist"
 
@@ -42,12 +40,12 @@ data class PlaylistRef(
 }
 
 /**
- * One row of a playlist's tracks. Mirrors Flutter's `PlaylistTrack`.
+ * One row of a playlist's tracks.
  *
  * `trackId` and `streamUrl` are nullable because the upstream track can
  * be removed from the library while the row stays in the playlist —
- * those tiles render grey + unplayable per Flutter's `isAvailable`
- * convention. [unavailable] is the second, softer case: the track is
+ * those tiles render grey + unplayable. [unavailable] is the second,
+ * softer case: the track is
  * still there but its file is missing. Both render grey and refuse to
  * play; only the second is worth explaining to the user, because it
  * can fix itself.
@@ -64,9 +62,9 @@ data class PlaylistTrackRef(
     val streamUrl: String? = null,
     /**
      * The track is still in the library but its file is missing from
-     * disk (#2527). Unlike a null [trackId] this is expected to be
+     * disk. Unlike a null [trackId] this is expected to be
      * temporary — the scanner clears it when the file returns, and
-     * adopts the row if it returns under a new name (#2528) — so the
+     * adopts the row if it returns under a new name — so the
      * row keeps its identity, its likes and its play history.
      */
     val unavailable: Boolean = false,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/QuarantineRef.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/QuarantineRef.kt
index dac51d9c..8f6ecb48 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/QuarantineRef.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/QuarantineRef.kt
@@ -1,8 +1,7 @@
 package com.fabledsword.minstrel.models
 
 /**
- * One quarantined track owned by the caller. Mirrors the Flutter
- * `QuarantineMineRow` (web `QuarantineMineRow`).
+ * One quarantined track owned by the caller.
  *
  * `reasonLabel` provides the display string mapped from the raw
  * server-side reason key — UI renders it as a pill on the row.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/Request.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/Request.kt
index dd04374f..29b59394 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/Request.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/Request.kt
@@ -23,10 +23,9 @@ enum class RequestStatus {
 }
 
 /**
- * One request the user has submitted. Mirrors
- * the Flutter client's `AdminRequest` —
- * shared between the user-side `/api/requests` view and the admin
- * cross-user view since the wire shape is identical.
+ * One request the user has submitted, shared between the user-side
+ * `/api/requests` view and the admin cross-user view since the wire
+ * shape is identical.
  *
  * `displayName` picks the right field based on kind:
  *   - album → albumTitle (fallback artistName)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/TrackRef.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/TrackRef.kt
index 06cc3ce1..b3c3f80d 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/TrackRef.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/TrackRef.kt
@@ -3,12 +3,11 @@ package com.fabledsword.minstrel.models
 import kotlinx.serialization.Serializable
 
 /**
- * Lightweight reference to one track. Mirrors
- * the Flutter client's `TrackRef`.
+ * Lightweight reference to one track.
  *
- * The `Ref` suffix matches the Flutter convention — these types carry
- * only the IDs + display fields needed for list rendering + the player
- * queue, not full per-row metadata.
+ * The `Ref` suffix marks types that carry only the IDs + display fields
+ * needed for list rendering + the player queue, not full per-row
+ * metadata.
  *
  * Constructed from `TrackWire` (server JSON) via `LibraryMappers`, and
  * from `CachedTrackEntity` (Room cache) via the same mappers. Either
@@ -32,7 +31,7 @@ data class TrackRef(
     val durationSec: Int = 0,
     val streamUrl: String = "",
     /**
-     * The server has no file for this track right now (#2704). It still
+     * The server has no file for this track right now. It still
      * belongs to the library, keeps its history, and may come back — but
      * streaming it will fail, so nothing should queue it.
      *
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/UserRef.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/UserRef.kt
index e527451c..33d1e12a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/UserRef.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/UserRef.kt
@@ -17,7 +17,7 @@ data class UserRef(
     val username: String,
     val isAdmin: Boolean = false,
     /**
-     * Account-level diagnostics opt-in (M9). NOT present in the login
+     * Account-level diagnostics opt-in. 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.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/AdminQuarantineWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/AdminQuarantineWire.kt
index 3a62bd77..7d29b20a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/AdminQuarantineWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/AdminQuarantineWire.kt
@@ -4,9 +4,8 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * One user's individual report under an aggregated quarantine row.
- * Mirrors Flutter's `AdminQuarantineReport` /
- * `internal/api/admin_quarantine.go` reportView.
+ * One user's individual report under an aggregated quarantine row
+ * (`internal/api/admin_quarantine.go` reportView).
  */
 @Serializable
 data class AdminQuarantineReportWire(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/AdminTagSourceWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/AdminTagSourceWire.kt
index 375f3a3a..98c930a9 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/AdminTagSourceWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/AdminTagSourceWire.kt
@@ -4,7 +4,7 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * Wire DTOs for the `/api/admin/tag-sources` admin surface (#1521).
+ * Wire DTOs for the `/api/admin/tag-sources` admin surface.
  * Every field defaults defensively so a missing JSON key never crashes
  * deserialization. `versionBumped` is present only on the PATCH response.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/BrowseWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/BrowseWire.kt
index 346311c1..68330cbb 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/BrowseWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/BrowseWire.kt
@@ -4,7 +4,7 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * One row of `GET /api/library/genres` (#367).
+ * One row of `GET /api/library/genres`.
  *
  * The label is the file tag's own string, split on `[;,]` and trimmed but
  * otherwise untouched by the server — no case folding, no synonym mapping.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/DiscoverWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/DiscoverWire.kt
index 03a4fcbf..60de2119 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/DiscoverWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/DiscoverWire.kt
@@ -4,10 +4,9 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * One row of `GET /api/catalogue/search` (the MusicBrainz search, M502
- * #5519). Mirrors `web/src/lib/api/types.ts
- * CatalogueSearchResult`. `imageUrl` is the server's own art endpoint,
- * relative, so it goes through ServerImage.
+ * One row of `GET /api/catalogue/search` (the MusicBrainz search). Mirrors
+ * `web/src/lib/api/types.ts` CatalogueSearchResult. `imageUrl` is the
+ * server's own art endpoint, relative, so it goes through ServerImage.
  *
  * `inLibrary` and `requested` let the UI greyout rows the user can't
  * act on (already imported / already awaiting review). All defaults
@@ -37,8 +36,8 @@ data class ArtistSuggestionWire(
     val attribution: List<SeedContributionWire> = emptyList(),
     /**
      * Tags this candidate shares with the user's taste profile, strongest
-     * first (max 3, #2377). Absent for most candidates — tag coverage for
-     * out-of-library artists is partial by nature (#2376) — so the default
+     * first (max 3). Absent for most candidates — tag coverage for
+     * out-of-library artists is partial by nature — so the default
      * empty list is the common case, not an error.
      */
     @SerialName("matched_tags") val matchedTags: List<String> = emptyList(),
@@ -86,9 +85,8 @@ data class SnoozeSuggestionBody(
 )
 
 /**
- * Body posted to `POST /api/requests`. Mirrors the Flutter `createRequest`
- * payload shape. Optional fields are emitted only when non-null
- * server-side; matching that here keeps the wire identical.
+ * Body posted to `POST /api/requests`. Optional fields are emitted only
+ * when non-null server-side; matching that here keeps the wire identical.
  */
 @Serializable
 data class CreateRequestBody(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/EventsWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/EventsWire.kt
index 5ccecbdd..473cec1e 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/EventsWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/EventsWire.kt
@@ -26,7 +26,7 @@ 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).
+    // Device class for context conditioning (server normalizes).
     @SerialName("device_class") val deviceClass: String? = null,
 )
 
@@ -57,6 +57,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).
+    // Device class for context conditioning (server normalizes).
     @SerialName("device_class") val deviceClass: String? = null,
 )
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/PlaylistWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/PlaylistWire.kt
index a4fa6152..2ece8341 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/PlaylistWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/PlaylistWire.kt
@@ -42,7 +42,7 @@ data class PlaylistsListWire(
  * may have been removed from the library while the row stays in the
  * playlist with its display fields preserved.
  *
- * [unavailable] is the other way a row outlives its audio (#2527): the
+ * [unavailable] is the other way a row outlives its audio: the
  * track is still in the library, with its history and likes, but its
  * file is missing from disk. The server withholds `stream_url` in that
  * case too, so a client that only checked the URL would already skip
@@ -65,10 +65,8 @@ data class PlaylistTrackWire(
 )
 
 /**
- * `GET /api/playlists/{id}` envelope. Server flattens the playlist
- * fields at the root level and adds a `tracks` array — matches the
- * Flutter fromJson which calls `Playlist.fromJson(j)` on the same map
- * that owns `tracks`.
+ * `GET /api/playlists/{id}` envelope. The server flattens the playlist
+ * fields at the root level and adds a `tracks` array.
  */
 @Serializable
 data class PlaylistDetailWire(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/QuarantineMineWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/QuarantineMineWire.kt
index 6ec6bebf..7de3175f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/QuarantineMineWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/QuarantineMineWire.kt
@@ -4,14 +4,11 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * One row of `GET /api/quarantine/mine`. Mirrors
- * the Flutter client's `QuarantineMineRow`
- * (web `QuarantineMineRow`).
+ * One row of `GET /api/quarantine/mine` (web `QuarantineMineRow`).
  *
  * Reason values: `bad_rip` / `wrong_file` / `wrong_tags` / `duplicate`
- * / `other`. Stored as a plain string on the wire; the UI does the
- * display-label mapping inline rather than via an enum to match
- * Flutter's switch-on-string pattern.
+ * / `other`. Stored as a plain string on the wire; the UI maps the
+ * display label inline rather than via an enum.
  */
 @Serializable
 data class QuarantineMineWire(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/RadioResponseWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/RadioResponseWire.kt
index b9dbbf4d..0969344c 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/RadioResponseWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/RadioResponseWire.kt
@@ -6,8 +6,7 @@ import kotlinx.serialization.Serializable
  * Response envelope for `GET /api/radio?seed_track=<id>&limit=<n>`.
  * The seed is returned at index 0 followed by up to limit-1
  * weighted-shuffle picks scored by the server's recommendation engine.
- * Mirrors Flutter's `RadioApi.seedTrack` parse — the `tracks` key is
- * the only field in the envelope.
+ * The `tracks` key is the only field in the envelope.
  */
 @Serializable
 data class RadioResponseWire(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/ReplayGainWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/ReplayGainWire.kt
index b58a9254..7ca9161a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/ReplayGainWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/ReplayGainWire.kt
@@ -3,7 +3,7 @@ package com.fabledsword.minstrel.models.wire
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
-/** One track's entry in `GET /api/tracks/replay-gain` (#4997). Decode-only. */
+/** One track's entry in `GET /api/tracks/replay-gain`. Decode-only. */
 @Serializable
 data class ReplayGainWire(
     @SerialName("track_gain") val trackGain: Float? = null,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/RequestWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/RequestWire.kt
index 548a3fe2..d78cd555 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/RequestWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/RequestWire.kt
@@ -6,8 +6,7 @@ import kotlinx.serialization.Serializable
 /**
  * Wire shape of `requestView` from `internal/api/requests.go` — the
  * row returned by both `GET /api/requests` (caller's own requests) and
- * `GET /api/admin/requests` (cross-user admin view). Mirrors
- * the Flutter client's `AdminRequest`.
+ * `GET /api/admin/requests` (cross-user admin view).
  *
  * Status values: `pending` / `approved` / `rejected` / `completed` /
  * `failed`. Kind values: `artist` / `album` / `track`.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/SyncResponseWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/SyncResponseWire.kt
index 67e75e61..286cbb3d 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/SyncResponseWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/SyncResponseWire.kt
@@ -28,7 +28,7 @@ data class SyncAlbumWire(
     @SerialName("release_date") val releaseDate: String? = null,
     @SerialName("cover_art_path") val coverArtPath: String? = null,
     val mbid: String? = null,
-    // The album's ReplayGain 2.0 values (#4997): dB to -18 LUFS and a linear
+    // The album's ReplayGain 2.0 values: dB to -18 LUFS and a linear
     // peak. Null until every track on the album is measured.
     @SerialName("album_gain") val albumGain: Float? = null,
     @SerialName("album_peak") val albumPeak: Float? = null,
@@ -46,23 +46,24 @@ data class SyncTrackWire(
     @SerialName("file_path") val filePath: String? = null,
     @SerialName("file_format") val fileFormat: String? = null,
     val genre: String? = null,
-    // The file is currently absent from disk server-side (#2704). Shipped as
+    // The file is currently absent from disk server-side. Shipped as
     // state rather than the row being withheld, because a missing file is
     // expected to return — dropping it would churn the cache on every
-    // transient unmount and discard the identity #2528 preserves.
+    // transient unmount and lose the row's identity, which the server keeps
+    // for a file that comes back.
     //
     // Defaults false so a server predating the field deserialises cleanly and
     // its tracks stay playable, which is the correct reading of "this server
     // has nothing to say about missing files".
     val missing: Boolean = false,
-    // The track's ReplayGain 2.0 values (#4997); null until it is measured.
+    // The track's ReplayGain 2.0 values; null until it is measured.
     @SerialName("track_gain") val trackGain: Float? = null,
     @SerialName("track_peak") val trackPeak: Float? = null,
 )
 
 /**
- * `/api/library/sync` upsert bucket. Server batches all entity types
- * in one shot per cursor advance. v1 native client only consumes
+ * `/api/library/sync` upsert bucket. The server batches all entity types
+ * in one shot per cursor advance. The app consumes only
  * artist/album/track — likes get their own `/api/likes/ids` refresh
  * path, and playlists pull on the Playlists screen visit.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/TrackWire.kt b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/TrackWire.kt
index ec230fc0..88d38c3e 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/models/wire/TrackWire.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/models/wire/TrackWire.kt
@@ -4,15 +4,12 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * Wire shape for `TrackRef` as the server emits it. Mirrors
- * the Flutter client's `TrackRef.fromJson`
- * field-for-field; the keys are snake_case because the server is Go
- * (json:"album_id" etc.).
+ * Wire shape for `TrackRef` as the server emits it; the keys are
+ * snake_case because the server is Go (json:"album_id" etc.).
  *
  * Mappers in feature packages translate this to the domain TrackRef
- * data class and the `cached_tracks` Room entity. Default values match
- * the Flutter Dart-side "?? 0" / "?? ''" fallbacks for forward-compat
- * with sparse server responses.
+ * data class and the `cached_tracks` Room entity. Fields default to
+ * 0 / "" so sparse server responses still decode.
  */
 @Serializable
 data class TrackWire(
@@ -26,8 +23,8 @@ data class TrackWire(
     @SerialName("disc_number") val discNumber: Int? = null,
     @SerialName("duration_sec") val durationSec: Int = 0,
     @SerialName("stream_url") val streamUrl: String = "",
-    // Omitted by the server when false, so the default carries most rows
-    // (#2704). True only from the direct-lookup surfaces — album detail and
+    // Omitted by the server when false, so the default carries most rows.
+    // True only from the direct-lookup surfaces — album detail and
     // search — which return a track the user asked for by name or container
     // rather than one Minstrel chose.
     val unavailable: Boolean = false,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/nav/DetailSeedCache.kt b/android/app/src/main/java/com/fabledsword/minstrel/nav/DetailSeedCache.kt
index 953ff536..b79cd331 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/nav/DetailSeedCache.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/nav/DetailSeedCache.kt
@@ -14,8 +14,7 @@ import javax.inject.Singleton
  * init so the AppBar header (title / cover / counts) renders
  * immediately, before the network round-trip completes.
  *
- * Mirrors Flutter's go_router `extra:` parameter pattern. Bounded
- * per-bucket via insertion-order LRU so back/forward navigation
+ * Bounded per-bucket via insertion-order LRU so back/forward navigation
  * doesn't grow unbounded.
  */
 @Singleton
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/nav/MinstrelNavGraph.kt b/android/app/src/main/java/com/fabledsword/minstrel/nav/MinstrelNavGraph.kt
index 43cefbf5..64decef0 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/nav/MinstrelNavGraph.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/nav/MinstrelNavGraph.kt
@@ -37,9 +37,8 @@ import com.fabledsword.minstrel.settings.ui.SettingsScreen
 import com.fabledsword.minstrel.shared.widgets.ShellScaffold
 
 /**
- * App NavHost. Mirrors the Flutter split between shell routes (wrapped
- * by `_ShellWithPlayerBar` → banners + screen + MiniPlayer) and
- * top-level non-shell routes (NowPlaying / Queue / unauthenticated).
+ * App NavHost. Shell routes (banners + screen + MiniPlayer) are split
+ * from top-level non-shell routes (NowPlaying / Queue / unauthenticated).
  *
  * Per-route transition: only NowPlaying gets the modal slide-up; the
  * rest use the default fade.
@@ -203,7 +202,7 @@ private fun NavGraphBuilder.inShellDetail(
     }
 }
 
-/** The notifications inbox and its settings (M489). */
+/** The notifications inbox and its settings. */
 private fun NavGraphBuilder.inShellNotifications(
     navController: NavHostController,
     expandPlayer: () -> Unit,
@@ -227,7 +226,6 @@ private fun NavGraphBuilder.inShellNotifications(
 private fun NavGraphBuilder.outsideShell(navController: NavHostController) {
     composable<NowPlaying>(
         // Slide up from the bottom on enter; back down on dismiss.
-        // Mirrors the Flutter CustomTransitionPage (280ms easeOutCubic).
         enterTransition = { slideInVertically(initialOffsetY = { it }) },
         exitTransition = { slideOutVertically(targetOffsetY = { it }) },
         popEnterTransition = { slideInVertically(initialOffsetY = { it }) },
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/data/NotificationSettingsRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/data/NotificationSettingsRepository.kt
index 2b4c1f03..3aa3bd3b 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/data/NotificationSettingsRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/data/NotificationSettingsRepository.kt
@@ -24,9 +24,9 @@ import javax.inject.Singleton
 enum class NotificationChannel(val wire: String) { INBOX("inbox"), PHONE("phone"), EMAIL("email") }
 
 /**
- * Per-user notification settings (M489), following snippet #5107: the device
- * copy (a cached JSON row) shows a change at once, the PUT is best effort,
- * and a failed or out-of-order one is queued for the MutationReplayer.
+ * Per-user notification settings, offline-first: the device copy (a
+ * cached JSON row) shows a change at once, the PUT is best effort, and a
+ * failed or out-of-order one is queued for the MutationReplayer.
  */
 @Singleton
 class NotificationSettingsRepository @Inject constructor(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/data/NotificationsRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/data/NotificationsRepository.kt
index c0d97963..f6910934 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/data/NotificationsRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/data/NotificationsRepository.kt
@@ -20,10 +20,10 @@ import javax.inject.Singleton
 import kotlin.time.Duration.Companion.milliseconds
 
 /**
- * The notifications inbox (M489). The newest page lives in Room so the bell's
- * badge and the Notifications screen work offline. Reads follow rule 100: the
- * device marks the row at once, the call is best effort, and a failed call is
- * queued for the MutationReplayer.
+ * The notifications inbox. The newest page lives in Room so the bell's
+ * badge and the Notifications screen work offline. Reads are
+ * offline-first: the device marks the row at once, the call is best
+ * effort, and a failed call is queued for the MutationReplayer.
  */
 @Singleton
 class NotificationsRepository @Inject constructor(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/BootReceiver.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/BootReceiver.kt
index 1b044458..87c2c922 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/BootReceiver.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/BootReceiver.kt
@@ -12,7 +12,7 @@ import javax.inject.Inject
 
 /**
  * Starts background delivery after a reboot, and after the app updates itself
- * (M489 #5347). Without it, notifications stop until the user next opens the
+ *. Without it, notifications stop until the user next opens the
  * app, which is exactly when they least need telling.
  *
  * Both broadcasts are among the few exemptions allowed to start a foreground
@@ -31,7 +31,7 @@ class BootReceiver : BroadcastReceiver() {
         val pending = goAsync()
         scope.launch {
             try {
-                // Bounded (rule 156): the session load gives up after its
+                // Bounded: the session load gives up after its
                 // own deadline and answers from what it has.
                 authStore.awaitSessionHydrated()
                 val signedIn = !authStore.sessionCookie.value.isNullOrEmpty()
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryLauncher.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryLauncher.kt
index dc89f02a..5da6d5f0 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryLauncher.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryLauncher.kt
@@ -15,7 +15,7 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Phone notifications (M489 #5347). Activated by force-@Inject in
+ * Phone notifications. Activated by force-@Inject in
  * MinstrelApplication, and the single owner of [DeliveryService]'s lifetime:
  * it runs exactly while signed in with "Notifications when the app is closed"
  * on. Signing out stops it, so a logged-out device holds no connection.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryPlan.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryPlan.kt
index 1feecb64..938350c9 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryPlan.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryPlan.kt
@@ -5,7 +5,7 @@ import com.fabledsword.minstrel.cache.db.entities.CachedNotificationEntity
 import kotlinx.datetime.Instant
 
 /**
- * The decisions behind phone notifications (M489 #5347), kept free of Android
+ * The decisions behind phone notifications, kept free of Android
  * so they can be tested as plain functions.
  */
 
@@ -31,7 +31,7 @@ internal data class CatchUp(
  *   kind with the phone off is never announced later.
  *
  * A coalesced notice (tracks missing, now 5) keeps the time it arrived when
- * its count grows (M542), so it is announced once: the inbox shows it grown,
+ * its count grows, so it is announced once: the inbox shows it grown,
  * the phone does not buzz for it again.
  */
 internal fun planCatchUp(
@@ -54,7 +54,7 @@ internal sealed interface Announcement {
 
     /**
      * Coming back from a day offline is one line, not forty buzzes. [lines]
-     * are the newest notices' titles, so the pile says what it holds (M542).
+     * are the newest notices' titles, so the pile says what it holds.
      */
     data class Pile(
         val count: Int,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryService.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryService.kt
index 0f0c8842..49b8a95d 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryService.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/DeliveryService.kt
@@ -17,8 +17,8 @@ import com.fabledsword.minstrel.R
 import timber.log.Timber
 
 /**
- * Keeps Minstrel's process alive so notifications arrive with the app closed
- * (M489 #5347, Roundtable's DeliveryService).
+ * Keeps Minstrel's process alive so notifications arrive with the app
+ * closed.
  *
  * **Why a held connection instead of push.** The APK installs from the
  * Minstrel server itself, not the Play Store, so nothing pushes the app onto
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/NotificationPoster.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/NotificationPoster.kt
index 6f0958a8..983f20fa 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/NotificationPoster.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/NotificationPoster.kt
@@ -17,7 +17,7 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Puts an [Announcement] in the shade (M489 #5347). The words are the
+ * Puts an [Announcement] in the shade. The words are the
  * server's: the same title and body the inbox shows. Tapping one opens what it
  * is about; tapping a pile opens the inbox.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/NotificationSync.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/NotificationSync.kt
index cb36b400..05bfc2e9 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/NotificationSync.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/delivery/NotificationSync.kt
@@ -16,8 +16,8 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Decides what the shade says by asking the server, never by trusting a frame
- * (M489 #5347, Roundtable's NotificationSync).
+ * Decides what the shade says by asking the server, never by trusting a
+ * frame.
  *
  * A `notification.created` frame and a reconnect both mean "go and look", so
  * both run [catchUp]. The frame carries nothing, so nothing can be announced
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationLinks.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationLinks.kt
index 420ef076..bac2fce0 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationLinks.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationLinks.kt
@@ -10,7 +10,7 @@ import com.fabledsword.minstrel.nav.Requests
 /**
  * The app screen for a notice's link. The server writes web paths, the same
  * for every client; this maps them onto the app's routes. The library's
- * health pages sit under Collection on the web (M504): Reports opens the
+ * health pages sit under Collection on the web: Reports opens the
  * app's report screen, and the ones the app has no screen for (duplicates,
  * suspect sources, missing files) open the Admin landing, as do other Admin
  * pages; anything unknown opens nothing.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationSettingsScreen.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationSettingsScreen.kt
index 5fcbfbf6..70d74219 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationSettingsScreen.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationSettingsScreen.kt
@@ -58,8 +58,8 @@ import com.fabledsword.minstrel.shared.widgets.ShellContentWindowInsets
 private val CELL_WIDTH = 56.dp
 
 /**
- * Per-user notification settings (M489): a row per kind with a box for each
- * channel. Rows read as a menu (rule 188); anything that needs explaining
+ * Per-user notification settings: a row per kind with a box for each
+ * channel. Rows read as a menu; anything that needs explaining
  * is one short line.
  */
 @Composable
@@ -172,7 +172,7 @@ private fun KindRow(
 
 /**
  * What this device does, above the per-kind grid that follows the account:
- * whether notifications arrive with the app closed (M489 #5347), and whether
+ * whether notifications arrive with the app closed, and whether
  * the system lets Minstrel post them at all.
  */
 @Composable
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationSettingsViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationSettingsViewModel.kt
index c67350cd..b90dc60f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationSettingsViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationSettingsViewModel.kt
@@ -23,7 +23,7 @@ class NotificationSettingsViewModel @Inject constructor(
     authController: AuthController,
     private val authStore: AuthStore,
 ) : ViewModel() {
-    /** "Notifications when the app is closed": this device's choice (M489 #5347). */
+    /** "Notifications when the app is closed": this device's choice. */
     val backgroundDelivery: StateFlow<Boolean> = authStore.backgroundDelivery
 
     val settings: StateFlow<NotificationSettingsWire?> = repository.settings
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationsViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationsViewModel.kt
index 9640bb07..66760d4b 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationsViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/notifications/ui/NotificationsViewModel.kt
@@ -41,7 +41,7 @@ class NotificationsViewModel @Inject constructor(
 
     init {
         refresh()
-        // Back online: the cached page may be stale (#1245's recovery idiom).
+        // Back online: the cached page may be stale, so refetch it.
         viewModelScope.launch { networkStatus.recoveries().collect { refresh() } }
     }
 
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/LikeMediaCallback.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/LikeMediaCallback.kt
index 9af56f44..1ac606b3 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/LikeMediaCallback.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/LikeMediaCallback.kt
@@ -19,8 +19,7 @@ import kotlinx.coroutines.launch
  * so they inherit the offline-resilient MutationQueue path.
  *
  * The [onConnect] grant is REQUIRED — without it the button is
- * silently invisible on some surfaces (Media3 issue #2679). See the
- * spec at docs/superpowers/specs/2026-06-02-android-media3-like-button-design.md.
+ * silently invisible on some surfaces (androidx/media#2679).
  *
  * Suspend work in [onCustomCommand] is launched on [scope] (a
  * service-lifetime scope) so the callback returns synchronously and
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/MinstrelForwardingPlayer.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/MinstrelForwardingPlayer.kt
index af40b975..c5af2e2f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/MinstrelForwardingPlayer.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/MinstrelForwardingPlayer.kt
@@ -723,8 +723,8 @@ class MinstrelForwardingPlayer(
      * Change-gated on purpose: steady playback is one reading repeated once a
      * second, which is worth nothing and would fill the ring buffer. What is
      * worth capturing is the renderer LEAVING a state — which during normal
-     * playback happens a couple of times per track, and during the fault the
-     * operator describes should happen repeatedly within a few seconds.
+     * playback happens a couple of times per track, and during a flap
+     * repeatedly within a few seconds.
      */
     private fun observeTransport(transport: TransportInfo, info: PositionInfo) {
         val key = transport.state to transport.statusOk
@@ -828,7 +828,7 @@ class MinstrelForwardingPlayer(
     }
 
     /**
-     * Most-authoritative -> most-degraded (project rule #48): the track-id
+     * Most-authoritative -> most-degraded: the track-id
      * parsed from the renderer's current URI wins; else the 1-based Sonos Track
      * index; else null (leave the cursor put rather than surface a wrong track).
      * Must run on the application looper -- reads the delegate timeline.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/MinstrelPlayerService.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/MinstrelPlayerService.kt
index f0d21efa..94881db8 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/MinstrelPlayerService.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/MinstrelPlayerService.kt
@@ -31,8 +31,8 @@ import timber.log.Timber
 import javax.inject.Inject
 
 /**
- * The app's foreground media-playback service. Replaces what the Flutter
- * audio_service plugin wrapped — Media3 owns the foreground lifecycle,
+ * The app's foreground media-playback service. Media3 owns the
+ * foreground lifecycle,
  * the MediaSession, the notification card, lock-screen surface, BT/AVRCP
  * routing, Pixel Watch tile, and Android Auto adapter natively.
  *
@@ -90,7 +90,7 @@ class MinstrelPlayerService : MediaSessionService() {
         serviceScope.launch { refreshNormalization() }
     }
 
-    // Takes up a leveling preference changed on another device (M464 #5000).
+    // Takes up a leveling preference changed on another device.
     // Offline, the device's copy stands, which is the one playback reads.
     private suspend fun refreshNormalization() {
         try {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/PlayEventsReporter.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/PlayEventsReporter.kt
index c62cdb32..7e6a4671 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/PlayEventsReporter.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/PlayEventsReporter.kt
@@ -22,25 +22,23 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Mobile play-event lifecycle reporter. Closes the parity gap where
- * Android-played tracks never reached the server — without this,
- * History stayed empty for mobile listening, recommendation scoring
- * was biased toward web/desktop, ListenBrainz scrobbles never fired,
- * and system-playlist rotation didn't advance on mobile activity.
+ * Mobile play-event lifecycle reporter. Without it, Android listening
+ * would never reach the server: History would stay empty for mobile
+ * plays, recommendation scoring would skew toward web, ListenBrainz
+ * scrobbles would not fire, and system-playlist rotation would not
+ * advance.
  *
  * State machine over (current track id, playing) observed against
  * [PlayerController.uiState]. The client always calls `playEnded`
  * with the actual position played to; the server applies its
  * configurable skip rule (`skip_max_completion_ratio` AND
  * `skip_max_duration_played_ms`, default 50% AND 30s) to decide
- * was_skipped. Earlier shape made the classification client-side via
- * a "within 3s of duration" rule, which left the server's threshold
- * dead code and treated any "next" tap as a skip — too strict
- * (operator 2026-06-01).
+ * was_skipped. Classifying on the client (say, "within 3s of
+ * duration") would leave the server's threshold dead and count every
+ * "next" tap as a skip.
  *
- * `playSkipped` endpoint stays on the wire for a future explicit-
- * dislike affordance, but isn't called from normal track-change
- * transitions any more.
+ * The `playSkipped` endpoint stays on the wire for a future explicit-
+ * dislike affordance; normal track changes do not call it.
  *
  * Live calls go through [EventsApi]; failures fall through to the
  * offline [MutationQueue] so a flaky connection never loses a play.
@@ -271,7 +269,7 @@ 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
+        // 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"
     }
@@ -281,11 +279,10 @@ class PlayEventsReporter @Inject constructor(
         // alone: the foreground media service keeps the process — and this
         // app-scope uiState collector — alive, so the live state machine
         // closes the play accurately on the next real track change. Closing
-        // here (the old always-offline behavior) raced the collector's
-        // re-begin and minted a duplicate, skip-misclassified row on every
-        // screen-lock. Only durably close a PAUSED play, where no further
-        // progress will happen and a process kill would otherwise orphan the
-        // open server row. See docs/superpowers/2026-06-11 contract audit.
+        // here would race the collector's re-begin and mint a duplicate,
+        // skip-misclassified row on every screen-lock. Only durably close a
+        // PAUSED play, where no further progress will happen and a process
+        // kill would otherwise orphan the open server row.
         if (curTrackId != null && !curPlaying) {
             closeCurrent()
         }
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/PlaybackErrorReporter.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/PlaybackErrorReporter.kt
index 929692b4..0a8bef38 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/PlaybackErrorReporter.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/PlaybackErrorReporter.kt
@@ -20,8 +20,7 @@ private const val DEBOUNCE_MS = 2_000L
  * Without the snackbar the player just silently skips the dead track —
  * the worst kind of bug, because the user can't tell "this file is
  * broken" from "the app is flaky". Without the admin report the
- * operator never finds out the track is bad and the next user hits
- * the same wall.
+ * admins never find out the track is bad and the next user hits
  *
  * The snackbar text:
  * collect [PlayerController.playbackErrorEvents], debounce in a 2s
@@ -30,7 +29,7 @@ private const val DEBOUNCE_MS = 2_000L
  *
  * The server report fires per event (no debounce) via
  * [PlaybackErrorRepository], which handles the offline-first
- * MutationQueue fallback per the standing rule for server writes.
+ * MutationQueue fallback, as every server write has.
  *
  * ShellScaffold collects [messages] into its existing snackbar host
  * so the reporter doesn't need its own UI surface. Constructed at
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerController.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerController.kt
index 87f09513..4ceb665f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerController.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerController.kt
@@ -103,15 +103,12 @@ class PlayerController @Inject constructor(
      * "track loaded but has no audio" case the user sees as the
      * player sitting frozen on a track.
      *
-     * Drift #561: this was originally Channel.CONFLATED, which silently
-     * dropped every emission except the latest each time the reporter
-     * loop wasn't actively reading. A network blip that failed 5
-     * tracks back-to-back would surface only the last failure to the
-     * snackbar (the "Skipped 5 unplayable tracks" coalescing path was
-     * dead code) AND only POST one playback_errors row to the admin
-     * inbox instead of 5. Buffered so every burst event reaches the
-     * reporter; default capacity is 64 which is well above any real
-     * burst rate.
+     * Buffered, not CONFLATED: a conflated channel drops every emission
+     * but the latest while the reporter loop isn't reading, so a network
+     * blip that failed 5 tracks back-to-back would surface only the last
+     * failure (the "Skipped 5 unplayable tracks" coalescing would never
+     * run) and POST one playback_errors row instead of 5. The default
+     * capacity of 64 is well above any real burst rate.
      */
     private val playbackErrorEventsChannel = Channel<PlaybackErrorEvent>(Channel.BUFFERED)
     val playbackErrorEvents: Flow<PlaybackErrorEvent> = playbackErrorEventsChannel.receiveAsFlow()
@@ -125,7 +122,7 @@ class PlayerController @Inject constructor(
     private var lastEvaluatedItemIndex: Int = -1
 
     /**
-     * #968: self-heal budget — re-pulls of a stale refreshable queue since
+     * Self-heal budget — re-pulls of a stale refreshable queue since
      * the last successful play. Capped so a still-broken refresh can't loop;
      * reset when any track loads with real audio.
      */
@@ -140,8 +137,8 @@ class PlayerController @Inject constructor(
 
     init {
         // A remote stall that survived the watchdog's retries is a playback
-        // failure like any other: the user gets the snackbar and the operator
-        // gets an admin-inbox row, via the same reporter that handles dead
+        // failure like any other: the user gets the snackbar and admins get
+        // an admin-inbox row, via the same reporter that handles dead
         // files. Without this the session just ends in silence -- the exact
         // failure the watchdog exists to surface.
         scope.launch {
@@ -164,10 +161,9 @@ class PlayerController @Inject constructor(
      * Completes when [mediaController] is non-null and the listener has
      * been attached. Used by [awaitReady] so cold-boot callers like
      * [ResumeController] can wait for the IPC bind before calling
-     * transport methods that would otherwise no-op silently. Drift
-     * #562 caught the race where a fast restore() landed before the
-     * MediaSessionService connection was up, silently dropping the
-     * restored queue.
+     * transport methods that would otherwise no-op silently: a fast
+     * restore() landing before the MediaSessionService connection is up
+     * would drop the restored queue.
      */
     private val readyDeferred = kotlinx.coroutines.CompletableDeferred<Unit>()
 
@@ -212,8 +208,8 @@ class PlayerController @Inject constructor(
     }
 
     /**
-     * Cycles the player's repeat mode: off → all → one → off. Mirrors
-     * Flutter's `cycleRepeat`. The wire order (none/all/one) matches
+     * Cycles the player's repeat mode: off → all → one → off. The wire
+     * order (none/all/one) matches
      * what the Now Playing icon swap expects — Lucide.Repeat for off
      * and all, Lucide.Repeat1 for one.
      */
@@ -255,13 +251,9 @@ class PlayerController @Inject constructor(
      * MediaItem extras.
      *
      * [autoplay] controls whether playback starts immediately. The
-     * default is true to preserve the "user pressed play on a tile"
-     * UX every existing caller relies on. Drift #560: cold-boot
-     * resume passes autoplay = false so the persisted queue is
-     * restored without auto-starting playback after the user has
-     * been away from the app — starting audio on cold launch was
-     * surprising for users who had paused mid-track before
-     * backgrounding.
+     * default is true: the user pressed play on a tile. Cold-boot
+     * resume passes autoplay = false so the persisted queue is restored
+     * without starting audio after the user has been away from the app.
      */
     fun setQueue(
         tracks: List<TrackRef>,
@@ -270,7 +262,7 @@ class PlayerController @Inject constructor(
         autoplay: Boolean = true,
     ) {
         val controller = mediaController ?: return
-        // One choke point for #2704: a track whose file the server has lost
+        // One choke point: a track whose file the server has lost
         // must not take a queue slot, whichever surface built the list.
         // Playlists already drop them earlier (toPlayableTrackRefs), but
         // album play-all, search, radio and cold-boot resume all arrive here
@@ -285,7 +277,7 @@ class PlayerController @Inject constructor(
         replayGains.request(
             playable.tracks.drop(startIndex).take(GAIN_PREFETCH).map { it.id },
         )
-        // Drift #562 cold-boot resume calls this from a non-Main suspend
+        // Cold-boot resume calls this from a non-Main suspend
         // context after awaitReady() unblocks (ResumeController launches
         // on Dispatchers.Default by the time it reaches us). MediaController
         // enforces application-thread access and throws
@@ -377,9 +369,7 @@ class PlayerController @Inject constructor(
      *    the radio results after the current item. If the seed is the
      *    currently playing track (the common "tap Start Radio on the
      *    song I'm listening to" case), drop it from the appended list
-     *    so it doesn't immediately repeat. This is an intentional
-     *    divergence from Flutter's `playerActions.startRadio`, which
-     *    always calls `playTracks` and restarts playback from 0.
+     *    so it doesn't immediately repeat.
      *
      * No-op on an empty server response; throws on transport / non-2xx
      * for the caller to surface in a snackbar.
@@ -459,7 +449,7 @@ class PlayerController @Inject constructor(
     }
 
     /**
-     * #968: the queue is fully unplayable (every track failed to load). If it
+     * The queue is fully unplayable (every track failed to load). If it
      * came from a refreshable source — a system playlist (bare-variant source)
      * or radio ("radio:<seed>") — the snapshot is probably stale (app/tab left
      * open across the daily rebuild); re-pull it and resume instead of stopping.
@@ -527,7 +517,7 @@ class PlayerController @Inject constructor(
                 return
             }
         mediaController = controller
-        // Drift #562: signal awaitReady() callers (ResumeController et al.)
+        // Signal awaitReady() callers (ResumeController et al.)
         // that the controller is bound. Listener is attached below in
         // the same coroutine so by the time downstream code runs after
         // awaitReady, the Player.Listener is wired too.
@@ -655,10 +645,8 @@ class PlayerController @Inject constructor(
      * `Player.Events` callbacks only fire at boundaries (track change,
      * pause/play, buffer state), never on normal position advancement,
      * so the seek bar would otherwise sit static between events. Polls
-     * at [POSITION_POLL_INTERVAL_MS]; matches the in-app cadence of
-     * Spotify / Apple Music / Flutter (just_audio `positionStream` runs
-     * at ~200ms; this 500ms is a battery-friendly middle ground that
-     * still reads as smooth on a slider).
+     * at [POSITION_POLL_INTERVAL_MS], which reads as smooth on a slider
+     * without being battery-hostile.
      *
      * The poll only patches position fields via `.copy()` so a stale
      * `onEvents` snapshot can't clobber the latest state. MediaController
@@ -801,7 +789,7 @@ class PlayerController @Inject constructor(
                 // paused under UPnP (it never probes a duration in that state).
                 if (durationSec > 0) setDurationMs(durationSec.toLong() * MS_PER_SECOND)
                 // Album and track position let the gain processor tell an
-                // album played in order from a mix (M464 #5000).
+                // album played in order from a mix.
                 trackNumber?.let { setTrackNumber(it) }
                 discNumber?.let { setDiscNumber(it) }
                 val extras = GainAudioProcessor.albumExtras(albumId)
@@ -879,13 +867,11 @@ class PlayerController @Inject constructor(
 }
 
 // 500ms: smooth-enough on a slider without being battery-hostile.
-// Flutter (just_audio positionStream) ticks at ~200ms; Spotify / Apple
-// Music sit around 250-500ms in-app. Lock-screen / notification
-// surfaces are driven by Media3's MediaSession callbacks separately;
-// they don't need this poll.
+// Lock-screen / notification surfaces are driven by Media3's
+// MediaSession callbacks separately; they don't need this poll.
 private const val POSITION_POLL_INTERVAL_MS = 500L
 
-// #968: at most one stale-queue self-heal re-pull per exhaustion (reset on
+// At most one stale-queue self-heal re-pull per exhaustion (reset on
 // the next successful play) so a still-broken refresh can't loop.
 private const val MAX_SELF_HEAL_ATTEMPTS = 1
 
@@ -907,7 +893,7 @@ data class PlaybackErrorEvent(
 
 /**
  * A queue with the server-missing tracks removed, and the caller's starting
- * index moved to match (#2704).
+ * index moved to match.
  */
 data class PlayableQueue(val tracks: List<TrackRef>, val initialIndex: Int)
 
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerFactory.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerFactory.kt
index 2cc0cc0e..23d95acf 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerFactory.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerFactory.kt
@@ -37,24 +37,20 @@ import javax.inject.Singleton
 
 /**
  * Builds the process-singleton player with our shared OkHttp +
- * SimpleCache chain. The MinstrelPlayerService (Phase 6.2) calls
- * `build()` once during onCreate.
+ * SimpleCache chain. MinstrelPlayerService calls `build()` once during
+ * onCreate.
  *
- * `simpleCache` is exposed as a val so the AudioCacheEvictionWorker
- * (Phase 12.3) can call `cache.removeSpan(...)` when evicting tracks
- * to disk-clear their cached spans.
- *
- * The default `LeastRecentlyUsedCacheEvictor` provides the floor LRU
- * (sizeBytes cap = rollingCap); our policy layer in the worker layers
- * the 2-bucket protection on top by feeding `removeSpan` only for
- * unprotected tracks.
+ * `simpleCache` is exposed as a val for what needs the on-disk bytes:
+ * the cached-track ids, the offline pools, the prefetcher and the
+ * Storage card. The `LeastRecentlyUsedCacheEvictor` bounds it at the
+ * rolling cap; there is no separate liked-track bucket yet.
  *
  * `build()` returns a [MinstrelForwardingPlayer] wrapping the internal
- * ExoPlayer. When the UPnP route drops (3 consecutive poll failures or
- * a SOAP failure), [dropEvents] emits the route name so the NowPlaying
- * surface can show a snackbar. The MutableSharedFlow uses DROP_OLDEST
- * with capacity=1 so a burst of failures during a single tear-down
- * surfaces as one event rather than queueing N.
+ * ExoPlayer. When the UPnP route drops (the poll loop's consecutive-
+ * failure threshold), [dropEvents] emits the route name so the
+ * NowPlaying surface can show a snackbar. The MutableSharedFlow uses
+ * DROP_OLDEST with capacity=1 so a burst of failures during a single
+ * tear-down surfaces as one event rather than queueing N.
  */
 @Singleton
 class PlayerFactory @Inject constructor(
@@ -154,7 +150,7 @@ class PlayerFactory @Inject constructor(
         val mediaSourceFactory = DefaultMediaSourceFactory(context)
             .setDataSourceFactory(cacheDataSource)
 
-        // Loudness normalization (M464 #5000) runs inside the audio sink so
+        // Loudness normalization runs inside the audio sink so
         // each track's gain starts on its first sample. Audio offload would
         // bypass the sink's processors; ExoPlayer leaves it off unless asked
         // (TrackSelectionParameters.audioOffloadPreferences), and nothing here
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerModule.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerModule.kt
index ebba0584..b4bd42e2 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerModule.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/PlayerModule.kt
@@ -10,13 +10,12 @@ import javax.inject.Singleton
 
 /**
  * Player + audio-cache wiring. PlayerFactory has @Inject so it doesn't
- * need a @Provides here; this module exists to provide the
- * configuration values (CacheConfig) it depends on, and any future
- * player-related singletons that aren't @Inject-constructible.
+ * need a @Provides here; this module provides the configuration values
+ * (CacheConfig) it depends on, and any player-related singletons that
+ * aren't @Inject-constructible.
  *
- * MinstrelPlayerService (Phase 6.2) injects PlayerFactory and calls
- * `build()` from `onCreate`. The eviction worker (Phase 12.3) injects
- * PlayerFactory too and reads `simpleCache` from it.
+ * MinstrelPlayerService injects PlayerFactory and calls `build()` from
+ * `onCreate`.
  */
 @Module
 @InstallIn(SingletonComponent::class)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/RemotePlayerState.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/RemotePlayerState.kt
index 9e5b2e93..4d750586 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/RemotePlayerState.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/RemotePlayerState.kt
@@ -16,7 +16,7 @@ import javax.inject.Singleton
  * The poll-failure counter is the sole drop arbiter: [DROP_THRESHOLD]
  * consecutive poll failures = remote considered dropped (returns true
  * from recordPollFailure for the caller to surface). Any success resets it.
- * Failed transport commands no longer drop the route -- they retry and
+ * Failed transport commands do not drop the route -- they retry and
  * otherwise defer to this counter (see MinstrelForwardingPlayer).
  */
 @Singleton
@@ -29,7 +29,7 @@ class RemotePlayerState @Inject constructor() {
     @Volatile var lastError: Throwable? = null; private set
     @Volatile var trackNumber: Int = 0; private set
 
-    // The operator's last explicit transport intent (play=true, pause=false),
+    // The user's last explicit transport intent (play=true, pause=false),
     // distinct from the observed remote isPlaying. handleRemoteDrop resumes
     // local playback based on THIS, not isPlaying -- so a play() that fails
     // its SOAP (stale/dead renderer) still resumes on the phone instead of
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/RemoteStallWatchdog.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/RemoteStallWatchdog.kt
index a21944cc..f670c876 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/RemoteStallWatchdog.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/RemoteStallWatchdog.kt
@@ -6,13 +6,10 @@ import com.fabledsword.minstrel.player.output.upnp.TransportState
  * Notices when a UPnP renderer has stopped playing without being asked, and
  * decides whether to try getting it going again.
  *
- * The gap this closes (diagnostics 2026-08-16): a Sonos playing from the
- * server stopped by itself mid-track while the phone was in Doze. The poll
- * loop was frozen, so nothing saw it; when the screen came back on the app
- * faithfully reported "queue track 10, position 113s, not playing" and then
- * sat there. Playback was over and no part of the app considered that a
- * problem. A renderer streams autonomously, which is exactly why a failed
- * stream is invisible without something watching for it.
+ * A renderer streams autonomously, so a failed stream is invisible without
+ * something watching for it: a Sonos can stop by itself mid-track while the
+ * phone is in Doze, the poll loop is frozen, and on wake the app reports
+ * "not playing" with nothing treating that as a problem.
  *
  * Deliberately conservative about what counts as a stall:
  *
@@ -20,7 +17,7 @@ import com.fabledsword.minstrel.player.output.upnp.TransportState
  *    PAUSED is left alone: the likely cause is a person pausing from the
  *    Sonos app or a wall controller, and fighting them for the transport is
  *    obnoxious. A stream that dies stops, it does not pause.
- *  - Only when the operator's last intent was to play. A stop we asked for
+ *  - Only when the user's last intent was to play. A stop we asked for
  *    is not a stall.
  *  - Only after [STALL_CONFIRM_POLLS] consecutive polls agree, so a single
  *    reading during a track change (Sonos passes through STOPPED and
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/ResumeController.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/ResumeController.kt
index ca8569a7..517dbaa1 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/ResumeController.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/ResumeController.kt
@@ -53,7 +53,7 @@ class ResumeController @Inject constructor(
                 .getOrNull()
                 ?.takeIf { it.tracks.isNotEmpty() }
                 ?: return
-        // Drift #562: wait for the MediaController binding before
+        // Wait for the MediaController binding before
         // calling setQueue, otherwise restore() racing the IPC
         // handshake silently drops the persisted queue (PlayerController
         // setQueue early-returns when mediaController is null).
@@ -64,7 +64,7 @@ class ResumeController @Inject constructor(
                 .coerceAtLeast(0)
                 .coerceAtMost(payload.tracks.lastIndex),
             source = payload.source,
-            // Drift #560: cold-boot resume must NOT auto-start
+            // Cold-boot resume must NOT auto-start
             // playback. The user has been away from the app; starting
             // audio on cold launch is surprising. They tap play to
             // resume. Queue + position are restored; transport is idle.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/StreamTokenProvider.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/StreamTokenProvider.kt
index 45e8b281..a8dbfbf9 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/StreamTokenProvider.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/StreamTokenProvider.kt
@@ -21,7 +21,7 @@ class StreamTokenProvider @Inject constructor(retrofit: Retrofit) {
 
     /**
      * Mints a URL for a speaker, leveled when the user's setting calls for
-     * it (M464 #5002). The server answers with the plain stream when it does
+     * it. The server answers with the plain stream when it does
      * not, so every speaker URL asks.
      */
     suspend fun mint(trackId: String, asAlbum: Boolean = false, prerender: Boolean = false): StreamTokenResponse =
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/TransportObservation.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/TransportObservation.kt
index f816efac..6df708d1 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/TransportObservation.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/TransportObservation.kt
@@ -4,12 +4,11 @@ package com.fabledsword.minstrel.player
  * One reading of what a UPnP renderer says it is doing, taken by the poll
  * loop and emitted only when it differs from the previous reading.
  *
- * Exists for diagnostics. The operator reports the Sonos rapidly
- * play-pause-play-pausing at the start of a track, and nothing in the
- * diagnostics could see it: `player_state` records source / loading / error
- * but not whether we are playing, `track_change` needs the queue index to
- * move, and the heartbeat samples once every 45 seconds. A symptom that
- * lasts a few seconds and changes no index fell straight through all three.
+ * Exists for diagnostics, for a Sonos rapidly play-pause-play-pausing at the
+ * start of a track: `player_state` records source / loading / error but not
+ * whether we are playing, `track_change` needs the queue index to move, and
+ * the heartbeat samples once every 45 seconds, so a symptom that lasts a few
+ * seconds and changes no index falls through all three.
  *
  * This is the closest observation point we have to the renderer's own truth
  * — the raw GetTransportInfo reading, before the two-poll confirmation and
@@ -31,7 +30,7 @@ data class TransportObservation(
     val trackNumber: Int,
     /** The renderer's reported position within the track. */
     val positionMs: Long,
-    /** Whether the operator's last intent was to be playing. */
+    /** Whether the user's last intent was to be playing. */
     val playIntent: Boolean,
     /** Monotonic stamp, so a consumer can measure gaps between readings. */
     val atElapsedMs: Long,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/gain/GainAudioProcessor.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/gain/GainAudioProcessor.kt
index 8baa70d0..1380961a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/gain/GainAudioProcessor.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/gain/GainAudioProcessor.kt
@@ -13,8 +13,8 @@ import com.fabledsword.minstrel.settings.data.NormalizationPrefs
 import java.nio.ByteBuffer
 
 /**
- * Applies each track's loudness gain inside ExoPlayer's audio sink (M464
- * #5000), so the level changes on the exact sample a track starts, gapless
+ * Applies each track's loudness gain inside ExoPlayer's audio sink, so the
+ * level changes on the exact sample a track starts, gapless
  * transitions included. `Player.setVolume` could do neither: it stops at 1,
  * and set from a transition callback it lands about two seconds late
  * because the next track is already buffered (androidx/media#418).
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/gain/GainMath.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/gain/GainMath.kt
index b72fee8e..aaa6ac1e 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/gain/GainMath.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/gain/GainMath.kt
@@ -8,7 +8,7 @@ import kotlin.math.min
 import kotlin.math.pow
 
 /**
- * One track's ReplayGain 2.0 values from the server (#4997): dB to the
+ * One track's ReplayGain 2.0 values from the server: dB to the
  * -18 LUFS reference, and linear true peaks. A null field has not been
  * measured yet.
  */
@@ -27,7 +27,7 @@ data class ReplayGain(
 data class AlbumPosition(val albumId: String?, val discNumber: Int?, val trackNumber: Int?)
 
 /**
- * Loudness-normalization math (M464 #5000). The same rules as the web
+ * Loudness-normalization math. The same rules as the web
  * player's `web/src/lib/player/gain.ts`, so a track levels the same on
  * every device.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/gain/ReplayGainStore.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/gain/ReplayGainStore.kt
index 7d6400f3..b1bff0fb 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/gain/ReplayGainStore.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/gain/ReplayGainStore.kt
@@ -17,7 +17,7 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * The gains the player levels by (M464 #5000), looked up per track and
+ * The gains the player levels by, looked up per track and
  * held for the life of the process. The audio thread reads them with [get];
  * [request] fills them in the background.
  *
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/output/OutputPickerController.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/output/OutputPickerController.kt
index 42a423b2..2709c6b4 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/output/OutputPickerController.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/output/OutputPickerController.kt
@@ -63,12 +63,7 @@ data class RouteSnapshot(
  *    AVTransport.SetAVTransportURI + Play, pause local playback so
  *    audio yields to the network speaker
  *  - [OutputRoute.Protocol.CAST] / [OutputRoute.Protocol.SONOS] —
- *    reserved for follow-up slices; ignored for now.
- *
- * Mirrors the OutputPickerController role described in
- * docs/superpowers/specs/2026-06-03-android-output-picker-bluetooth-design.md
- * and the UPnP extensions in
- * docs/superpowers/specs/2026-06-03-android-output-picker-upnp-design.md.
+ *    not implemented; selecting one does nothing.
  */
 @Singleton
 class OutputPickerController @Inject constructor(
@@ -163,7 +158,7 @@ class OutputPickerController @Inject constructor(
         mediaRouter.addCallback(selector, callback)
         // When MinstrelForwardingPlayer reports the active UPnP route has
         // dropped (the poll loop's consecutive-failure threshold tripping --
-        // the sole drop arbiter; a failed transport command no longer drops),
+        // the sole drop arbiter; a failed transport command does not drop),
         // clear the UPnP selection state and fall back to local ExoPlayer at
         // the last-known remote position. This mirrors selectSystem's disconnect
         // path but skips the Stop SOAP since the device is already unreachable.
@@ -227,11 +222,11 @@ class OutputPickerController @Inject constructor(
     }
 
     /**
-     * Timer fired: the operator paused on a UPnP route and never resumed.
+     * Timer fired: the user paused on a UPnP route and never resumed.
      * Stop the renderer (best-effort -- it's reachable, unlike a drop),
      * clear the UPnP overlay so routesState falls back to the phone, and
      * seek local ExoPlayer to the last remote position. No play(): the
-     * operator was paused, so we revert routing silently. Guarded by the
+     * user was paused, so we revert routing silently. Guarded by the
      * selectUpnpMutex so it can't race selectUpnp/resync.
      */
     private suspend fun revertToPhoneOnIdle() = selectUpnpMutex.withLock {
@@ -429,9 +424,9 @@ class OutputPickerController @Inject constructor(
      */
     private fun handleRemoteDrop() {
         val capturedPositionMs = remoteState.positionMs
-        // Resume on the operator's last play-intent, not the observed remote
+        // Resume on the user's last play-intent, not the observed remote
         // state: after a pause, isPlaying is false, but a failed play() that
-        // triggered this drop means the operator DID ask to play -- honor it.
+        // triggered this drop means the user DID ask to play -- honor it.
         val wasPlayingRemote = remoteState.lastPlayIntent
         activeUpnpHolder.set(null)
         activeUpnpHolder.setTarget(null)
@@ -469,8 +464,8 @@ class OutputPickerController @Inject constructor(
      * Select [route]. SYSTEM routes hand off to [MediaRouter]; UPNP
      * routes mint a signed stream token + drive AVTransport on the
      * discovered renderer + pause local playback. Other protocols
-     * (CAST / SONOS) are reserved for follow-up slices and are
-     * silently ignored — the picker shouldn't show them yet.
+     * (CAST / SONOS) are not implemented and are silently ignored — the
+     * picker doesn't show them.
      */
     fun select(route: OutputRoute) {
         when (route.protocol) {
@@ -524,7 +519,7 @@ class OutputPickerController @Inject constructor(
         // Honor Sonos topology: pick the coordinator's route when the user
         // tapped a group row. Suppression in routesState already keeps the
         // visible row at the coordinator's id, so this is identity in the
-        // common case -- defensive for follow-up flows.
+        // common case -- defensive for any other caller.
         val effectiveRoute = upnpDiscovery.coordinatorRouteFor(route.id)
             ?.let { OutputRoute.fromUpnpRoute(it) } ?: route
         val transport = upnpDiscovery.transportFor(effectiveRoute.id)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/output/OutputRoute.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/output/OutputRoute.kt
index 3baecd30..fb8131ec 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/output/OutputRoute.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/output/OutputRoute.kt
@@ -9,11 +9,9 @@ import com.fabledsword.minstrel.player.output.upnp.UpnpRoute
  * Android framework presence (RouteInfo can't be constructed in
  * JVM tests, mirroring the LikeMediaCallback constraint).
  *
- * The [protocol] field is a forward-compatibility hook for the
- * UPnP / DLNA / Sonos / Cast slice (scope captured in
- * docs/superpowers/specs/2026-06-03-android-output-picker-upnp-scope.md).
- * THIS slice always sets `protocol = SYSTEM` — the system-route
- * categories MediaRouter surfaces (built-in / wired / Bluetooth).
+ * [protocol] says how a route is driven: SYSTEM for the categories
+ * MediaRouter surfaces (built-in / wired / Bluetooth), UPNP for
+ * discovered network renderers. CAST and SONOS are reserved.
  */
 data class OutputRoute(
     val id: String,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/output/SonosQueueLoader.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/output/SonosQueueLoader.kt
index 355abbfd..54e17d3a 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/output/SonosQueueLoader.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/output/SonosQueueLoader.kt
@@ -18,16 +18,15 @@ import javax.inject.Singleton
 
 /**
  * Owns the shape of a Sonos renderer's native queue: loading it, growing it,
- * diffing it against local queue mutations, and — the part that was missing —
- * confirming the renderer actually took what we sent.
+ * diffing it against local queue mutations, and confirming the renderer
+ * actually took what we sent.
  *
- * Split out of [OutputPickerController], which is about *which route is
+ * Kept apart from [OutputPickerController], which is about *which route is
  * selected*. How many tracks the renderer is holding is a separate concern
- * with its own failure modes, and it had grown large enough to hide one:
- * every write here is a SOAP call that can fail individually, and until
- * [verifyQueueLength] nothing ever read the result back.
+ * with its own failure modes: every write here is a SOAP call that can fail
+ * individually, so [verifyQueueLength] reads the result back.
  *
- * Every URL sent is a leveled one (M464 #5002): the server renders the track
+ * Every URL sent is a leveled one: the server renders the track
  * at the user's loudness gain, or hands back the plain stream when leveling
  * is off. Renders are slow enough to matter, so the track playing and the
  * one after it are rendered ahead; the rest render when the speaker asks.
@@ -118,12 +117,10 @@ class SonosQueueLoader @Inject constructor(
      *
      * [appendTracksToQueue] tolerates individual failures and gives up after
      * [EXTEND_ABORT_AFTER_FAILURES] consecutive ones, because Sonos rate-limits
-     * burst adds (logcat 2026-06-04: 33 consecutive failures once offset 39 was
-     * reached). That is the right call in the moment — some tracks loaded beats
-     * none — but it used to be the end of the story, and the renderer was left
-     * holding a queue shorter than ours with nothing aware of it. It then
-     * played what it had and stopped, which looked exactly like playback dying
-     * for no reason.
+     * burst adds. Some tracks loaded beats none, but it leaves the renderer
+     * holding a queue shorter than ours; unchecked, the renderer plays what
+     * it has and stops, which looks exactly like playback dying for no
+     * reason.
      *
      * Sonos appends sequentially, so a short queue means a missing tail: taking
      * `fullQueue.drop(nrTracks)` is the gap. Bounded at [VERIFY_ROUNDS] passes
@@ -195,12 +192,10 @@ class SonosQueueLoader @Inject constructor(
                 if (outcome.isSuccess) {
                     consecutiveFailures = 0
                     succeeded += 1
-                    // Throttle the burst so we don't tickle Sonos's burst-add
-                    // rejection -- logcat 2026-06-04 showed 33 consecutive
-                    // failures clustered at ~10ms intervals once offset 39 was
-                    // reached, which looks like a rate-limit kicking in. The
-                    // delay is small enough that extending 100 tracks adds
-                    // only ~5s to background work that's already async.
+                    // Throttle the burst so Sonos's burst-add rejection does not
+                    // kick in (rapid adds start failing in a run, which looks like a
+                    // rate limit). The delay is small enough that extending 100
+                    // tracks adds only ~5s to background work that's already async.
                     delay(EXTEND_THROTTLE_MS)
                 } else {
                     consecutiveFailures += 1
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/output/upnp/AVTransportClient.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/output/upnp/AVTransportClient.kt
index 0f08c370..2020d5c3 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/output/upnp/AVTransportClient.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/output/upnp/AVTransportClient.kt
@@ -215,16 +215,12 @@ class AVTransportClient(
      * What the renderer believes it is holding: how many tracks are in its
      * queue, and the URI the transport is pointed at.
      *
-     * We load the queue with AddURIToQueue and, until this existed, never
-     * read it back — so a partially-applied load was invisible. Sonos
-     * rate-limits burst adds (logcat 2026-06-04: 33 consecutive failures once
-     * offset 39 was reached), and [OutputPickerController]'s extend loop gives
-     * up after a few of those and leaves a short queue behind. The renderer
-     * then plays what it actually has and stops, correctly, at an end the app
-     * did not know existed.
-     *
-     * NrTracks is the cheap authoritative answer, so queue truncation becomes
-     * something we can detect and repair rather than infer.
+     * The queue is loaded with AddURIToQueue, and Sonos rate-limits burst
+     * adds, so `SonosQueueLoader`'s extend loop can give up and leave a short
+     * queue behind. The renderer then plays what it actually has and stops,
+     * correctly, at an end the app did not know existed. NrTracks is the
+     * cheap authoritative answer, so queue truncation is something we
+     * detect and repair rather than infer.
      */
     suspend fun getMediaInfo(): MediaInfo {
         val result = soap.call(
@@ -270,7 +266,7 @@ class AVTransportClient(
         // external (non-Sonos-library) source. Without those, Sonos
         // discards our metadata content and regenerates its own with
         // class=object.item and the URL query string as the title
-        // (logcat 2026-06-04 confirmed). Match SoCo's pattern.
+        // instead. Match SoCo's pattern.
         val safeTitle = title.ifBlank { "Minstrel" }
         return buildString {
             append("<DIDL-Lite ")
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/ui/MiniPlayer.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/ui/MiniPlayer.kt
index 3c2cce15..529efea7 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/ui/MiniPlayer.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/ui/MiniPlayer.kt
@@ -54,8 +54,7 @@ private const val MINI_BAR_TONAL_ELEVATION_DP = 4
 private const val COVER_SIZE_DP = 48
 private const val SCRUBBER_ROW_HEIGHT_DP = 4
 
-// Upward flick speed (dp/s) that expands the bar into NowPlaying.
-// The 200 px/s threshold carries over from the Flutter player bar,
+// Upward flick speed (dp/s) that expands the bar into NowPlaying,
 // expressed in dp and converted via density so the gesture feels the
 // same across screens.
 private const val SWIPE_UP_VELOCITY_DP = 200
@@ -115,7 +114,7 @@ private fun MiniCover(coverUrl: String, contentDescription: String) {
  *     own content; otherwise the row keeps its intrinsic 48dp and the
  *     leftover height collects at the bottom as dead surface.
  *
- * No kebab on the mini bar (operator 2026-06-01): the full kebab
+ * No kebab on the mini bar: the full kebab
  * surface lives on NowPlayingScreen, and dropping it from the mini
  * gives the title/artist column the horizontal room it needs to
  * actually display the artist name without truncation.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/ui/NowPlayingScreen.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/ui/NowPlayingScreen.kt
index 7179063a..e0171ee8 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/ui/NowPlayingScreen.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/ui/NowPlayingScreen.kt
@@ -118,9 +118,8 @@ private val SCRUB_THUMB_WIDTH_DP = 4.dp
 private val SCRUB_THUMB_HEIGHT_DP = 18.dp
 
 // Vertical drag-down threshold (in pixels) past which the gesture
-// pops the player. Matches Flutter's 80px threshold in spirit;
-// using pointer-input pixels not dp because gesture velocity also
-// participates in the dismiss decision.
+// pops the player. Pointer-input pixels, not dp, because gesture
+// velocity also participates in the dismiss decision.
 private const val DRAG_DISMISS_THRESHOLD_PX = 200f
 
 /**
@@ -223,8 +222,8 @@ private const val DOMINANT_TINT_MID = 0.18f
 private const val DOMINANT_TINT_MID_STOP = 0.45f
 
 /**
- * Drag-down to dismiss. Mirrors Flutter's modal-page gesture: a
- * downward over-scroll past the threshold pops the screen.
+ * Drag-down to dismiss: a downward over-scroll past the threshold pops
+ * the screen.
  *
  * Implementation note: the body Column uses verticalScroll, which
  * eats every vertical drag delta before a top-level
@@ -371,7 +370,7 @@ private fun NowPlayingContent(
         TrackHeader(title = track.title, artist = track.artistName, album = track.albumTitle)
         Spacer(Modifier.height(24.dp))
         // Action row (like, shuffle, repeat, queue, kebab) sits ABOVE the
-        // scrubber. Android previously had it below the transport row.
+        // scrubber.
         BottomActionsRow(
             navController = navController,
             track = track,
@@ -623,7 +622,7 @@ private fun ScrubberRow(positionMs: Long, durationMs: Long, onSeek: (Long) -> Un
         thumbColor = accent,
         activeTrackColor = accent,
         // M3 inactive default is secondaryContainer (purple baseline);
-        // pin to surfaceVariant (= slate) for Flutter parity.
+        // pin to surfaceVariant (= slate).
         inactiveTrackColor = MaterialTheme.colorScheme.surfaceVariant,
     )
     Slider(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueDragMath.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueDragMath.kt
index 7d0d8ad8..0c1e5c4f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueDragMath.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueDragMath.kt
@@ -6,7 +6,7 @@ import kotlin.math.roundToInt
  * Drag offset to row delta, rounded to the nearest row boundary. The Android
  * half of web's `offsetToDelta` (web/src/lib/components/queue-row-math.ts):
  * the two clients are meant to agree, and QueueDragMathTest mirrors web's
- * cases so both are held to it (#2436).
+ * cases so both are held to it.
  *
  * Ties round toward positive infinity, as JS `Math.round` does: half a row
  * down moves one row, half a row up stays put. A row not yet measured
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueRow.kt b/android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueRow.kt
index 6dee5a84..40cc1d52 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueRow.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueRow.kt
@@ -50,12 +50,10 @@ import com.fabledsword.minstrel.shared.widgets.ServerImage
 import com.fabledsword.minstrel.theme.LocalActionColors
 
 /*
- * A single queue row, split out of QueueScreen.kt when swipe-to-remove (#2435)
- * pushed that file past detekt's TooManyFunctions limit. The seam is real and
- * not just a way to satisfy the analyzer: the row now carries two gestures, a
- * swipe background, and its own accessibility surface, which is more behaviour
- * than the screen that lists it. `internal` rather than `private` only because
- * QueueList (still in QueueScreen.kt) is the caller.
+ * A single queue row, kept apart from QueueScreen.kt: the row carries two
+ * gestures, a swipe background, and its own accessibility surface, which
+ * is more behaviour than the screen that lists it. `internal` rather than
+ * `private` only because QueueList (still in QueueScreen.kt) is the caller.
  */
 
 @Suppress("LongParameterList") // Compose row wiring — layout + queue callbacks, not logic.
@@ -78,7 +76,7 @@ internal fun QueueRow(
     } else {
         Color.Transparent
     }
-    // Swipe left to remove, replacing the X button (#2395 follow-up). Only
+    // Swipe left to remove. Only
     // end-to-start is enabled: a right-swipe has no meaning here, and leaving it
     // live would delete tracks on a mis-aimed gesture in either direction.
     val dismissState = rememberSwipeToDismissBoxState(
@@ -153,7 +151,7 @@ private fun QueueRowContent(
         verticalAlignment = Alignment.CenterVertically,
         horizontalArrangement = Arrangement.spacedBy(12.dp),
     ) {
-        // The album art IS the grab surface (#2395). The grip icon it replaces
+        // The album art IS the grab surface: a separate grip icon would
         // cost ~36dp of every row's width — icon plus its 12dp gap — on the
         // narrowest surface in the app, competing with the title for space.
         QueueRowThumbnail(
@@ -247,14 +245,14 @@ private fun Modifier.queueReorderActions(
 
 /**
  * Reorder-drag behaviour for a queue row, applied to whatever element is the
- * grab surface — the album art, since #2395 removed the grip icon.
+ * grab surface — the album art.
  *
  * Uses **detectDragGesturesAfterLongPress**, not detectDragGestures, and that
- * is the load-bearing detail. The grip was a small target, so a plain drag
- * gesture on it never competed with anything. A 48dp thumbnail is a large
- * chunk of every row, and with a plain drag detector any vertical pan starting
- * on artwork would be swallowed as a row-reorder instead of scrolling the
- * queue — the list would feel broken precisely where it's easiest to touch.
+ * is the load-bearing detail. A 48dp thumbnail is a large chunk of every row,
+ * and with a plain drag detector any vertical pan starting on artwork would be
+ * swallowed as a row-reorder instead of scrolling the queue — the list would
+ * feel broken precisely where it's easiest to touch.
+ * Long-press-then-drag separates the two: pan scrolls, long-press reorders,
  * Long-press-then-drag separates the two: pan scrolls, long-press reorders,
  * tap still plays (the detector doesn't consume a plain tap, so it falls
  * through to the row's clickable).
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/playlists/data/PlaylistPlayback.kt b/android/app/src/main/java/com/fabledsword/minstrel/playlists/data/PlaylistPlayback.kt
index aca9f650..f2c6d2c4 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/playlists/data/PlaylistPlayback.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/playlists/data/PlaylistPlayback.kt
@@ -35,7 +35,7 @@ suspend fun playPlaylistShuffled(
         onMessage("Mix isn't ready yet - try again in a moment")
         return
     }
-    // Drift #564: bare systemVariant string (not "playlist:<variant>") --
+    // Bare systemVariant string (not "playlist:<variant>") --
     // server's rotation matcher keys on the bare variant.
     val source = if (playlist.refreshable) playlist.systemVariant else null
     // System playlist tile play button == "pick a random song + shuffle
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/playlists/data/PlaylistsRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/playlists/data/PlaylistsRepository.kt
index b3d99126..bbe0371f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/playlists/data/PlaylistsRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/playlists/data/PlaylistsRepository.kt
@@ -29,8 +29,7 @@ import javax.inject.Singleton
 
 /**
  * Cache-first reads of the caller's playlists plus per-playlist track
- * lists. Mirrors the Flutter `playlistsListProvider` + `playlistDetail`
- * pattern: Room is the source of truth for UI observation; refresh*
+ * lists. Room is the source of truth for UI observation; refresh*
  * methods push wire data into Room and the Flow emissions propagate.
  *
  * Track-list hydration: `cached_playlist_tracks` only stores ordered
@@ -38,8 +37,7 @@ import javax.inject.Singleton
  * fields come back from `/api/playlists/{id}` in `PlaylistTrackWire`
  * — we cache the membership rows in Room (so the playlist tracks list
  * persists offline at the ID level) AND keep the freshest detail
- * response in memory via the returned `PlaylistDetailRef`. A proper
- * per-track hydration queue lands with the Phase 12 sync controller.
+ * response in memory via the returned `PlaylistDetailRef`.
  */
 @Singleton
 class PlaylistsRepository @Inject constructor(
@@ -217,12 +215,10 @@ data class PlaylistDetailRef(
 /**
  * Convert each [PlaylistTrackRef] to a player-ready [TrackRef], dropping
  * any row that isn't actually playable (trackId missing OR streamUrl
- * missing). The two call sites (PlaylistDetailViewModel.play and
- * HomeViewModel.playPlaylist) used to hand-roll this conversion and
- * differed on whether they applied the filter, which let unplayable
- * tracks reach `player.setQueue` and silently no-op inside Media3
- * (setUri("") never errors). Centralise both the conversion AND the
- * defensive filter so the queue is always playable.
+ * missing). Every caller goes through here because an unplayable track
+ * that reaches `player.setQueue` silently no-ops inside Media3
+ * (setUri("") never errors), so the conversion and the filter live
+ * together.
  */
 fun List<PlaylistTrackRef>.toPlayableTrackRefs(): List<TrackRef> =
     filter { it.isAvailable && !it.streamUrl.isNullOrEmpty() }
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/playlists/ui/PlaylistDetailScreen.kt b/android/app/src/main/java/com/fabledsword/minstrel/playlists/ui/PlaylistDetailScreen.kt
index 1106fdc0..5b7b4425 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/playlists/ui/PlaylistDetailScreen.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/playlists/ui/PlaylistDetailScreen.kt
@@ -146,7 +146,7 @@ class PlaylistDetailViewModel @Inject constructor(
     val regenerated: Flow<String> = regeneratedChannel.receiveAsFlow()
 
     /**
-     * #980: a system-playlist rebuild landed (SSE) while this screen is open —
+     * A system-playlist rebuild landed (SSE) while this screen is open —
      * its list is now stale and the uuid has rotated. Drives a "this mix was
      * refreshed → Refresh" snackbar rather than yanking the user; Refresh
      * re-resolves the variant via [reloadRebuilt].
@@ -169,7 +169,7 @@ class PlaylistDetailViewModel @Inject constructor(
                 .filter { it.kind.startsWith("playlist.") }
                 .collect { handlePlaylistEvent(it) }
         }
-        // Screen-level auto-recovery (issue #1245): a detail that failed to
+        // Screen-level auto-recovery: 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 {
@@ -186,7 +186,7 @@ class PlaylistDetailViewModel @Inject constructor(
      * ignored — the playlists-list screen handles those.
      */
     private fun handlePlaylistEvent(event: LiveEvent) {
-        // #980: a system rebuild carries no playlist_id (it rebuilds all of the
+        // A system rebuild carries no playlist_id (it rebuilds all of the
         // user's system mixes at once) — handle it before the per-id filter.
         if (event.kind == "playlist.system_rebuilt") {
             markStaleIfSystem()
@@ -258,7 +258,7 @@ class PlaylistDetailViewModel @Inject constructor(
     }
 
     /**
-     * #980: user tapped Refresh on the stale-view snackbar. The rebuild
+     * User tapped Refresh on the stale-view snackbar. The rebuild
      * already ran server-side (uuid rotated) — re-resolve the variant to the
      * fresh playlist id and hand it to [regenerated] for navigate-replace.
      * Unlike [regenerate] this does NOT trigger another rebuild.
@@ -276,7 +276,7 @@ class PlaylistDetailViewModel @Inject constructor(
         }
     }
 
-    /** #980: user dismissed the stale-view snackbar without refreshing. */
+    /** User dismissed the stale-view snackbar without refreshing. */
     fun dismissStale() {
         staleInternal.value = false
     }
@@ -286,7 +286,7 @@ class PlaylistDetailViewModel @Inject constructor(
         val refs = tracks.toPlayableTrackRefs()
         if (refs.isEmpty()) return
         val startIndex = refs.indexOfFirst { it.id == startTrackId }.coerceAtLeast(0)
-        // Drift #564: for refreshable system playlists, send the bare
+        // For refreshable system playlists, send the bare
         // systemVariant string so the rotation matcher
         // (systemPlaylistSources in playevents/writer.go) sees the
         // play. User playlists keep the "playlist:<id>" tag for
@@ -322,7 +322,7 @@ fun PlaylistDetailScreen(
             }
         }
     }
-    // #980: a rebuild landed while this system-playlist screen is open. Offer a
+    // A rebuild landed while this system-playlist screen is open. Offer a
     // non-intrusive "refreshed → Refresh" snackbar; Refresh re-resolves the
     // rotated uuid (via the regenerated navigate-replace flow).
     val snackbarHostState = remember { SnackbarHostState() }
@@ -578,7 +578,7 @@ private fun TrackRow(
     val enabled = row.isAvailable
     val rowAlpha = if (enabled) 1f else UNAVAILABLE_ALPHA
     // A greyed row with no explanation reads as a bug. Say which kind of
-    // dead it is: a missing file (#2527) is the library's problem and can
+    // dead it is: a missing file is the library's problem and can
     // fix itself when the file returns, so it earns a line the user can
     // act on. A removed track needs no note — grey and unplayable is the
     // whole story once it's gone from the library.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/playlists/ui/PlaylistsListScreen.kt b/android/app/src/main/java/com/fabledsword/minstrel/playlists/ui/PlaylistsListScreen.kt
index 3df31460..9b565c93 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/playlists/ui/PlaylistsListScreen.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/playlists/ui/PlaylistsListScreen.kt
@@ -102,7 +102,7 @@ class PlaylistsListViewModel @Inject constructor(
                 .filter { it.kind.startsWith("playlist.") }
                 .collect { refresh() }
         }
-        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // Screen-level auto-recovery: re-pull when server
         // health returns, so a load that failed offline heals unprompted.
         viewModelScope.launch {
             networkStatus.recoveries().collect { refresh() }
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/playlists/widgets/OfflinePoolCard.kt b/android/app/src/main/java/com/fabledsword/minstrel/playlists/widgets/OfflinePoolCard.kt
index 37476989..c0338cc2 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/playlists/widgets/OfflinePoolCard.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/playlists/widgets/OfflinePoolCard.kt
@@ -26,7 +26,7 @@ import com.fabledsword.minstrel.theme.FabledSwordFlatTokens
  * Home tile for an offline cache-backed pool ("Recently played" /
  * "Liked"). Tapping shuffles + plays that pool from the local cache.
  * Sized to match [PlaylistCard] so the Playlists row stays visually
- * consistent. Mirrors Flutter's `_OfflinePoolCard`.
+ * consistent.
  */
 @Composable
 fun OfflinePoolCard(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/quarantine/data/QuarantineRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/quarantine/data/QuarantineRepository.kt
index f67b0d28..23f16631 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/quarantine/data/QuarantineRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/quarantine/data/QuarantineRepository.kt
@@ -33,9 +33,7 @@ enum class FlagOutcome { ACCEPTED, QUEUED }
 
 /**
  * Cache-first accessor for the caller's quarantine list + offline-
- * first flag / unflag writes. Mirrors Flutter's `MyQuarantineController`
- * (drift `cached_quarantine_mine` + SWR + optimistic mutations) using
- * the native Room + Flow idiom:
+ * first flag / unflag writes, in the Room + Flow idiom:
  *
  *   - [observeMine] emits the cached rows, so the Hidden tab paints
  *     from disk instantly and survives connectivity loss.
@@ -44,7 +42,7 @@ enum class FlagOutcome { ACCEPTED, QUEUED }
  *   - [flag] / [unflag] mutate the cache optimistically (the Flow
  *     re-emits immediately), call the server, and enqueue on failure
  *     so the intent persists offline. The optimistic row is NOT rolled
- *     back on failure — same as Flutter.
+ *     back on failure.
  */
 @Singleton
 class QuarantineRepository @Inject constructor(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/quarantine/ui/HiddenTabViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/quarantine/ui/HiddenTabViewModel.kt
index 9d05fbce..661b80ab 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/quarantine/ui/HiddenTabViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/quarantine/ui/HiddenTabViewModel.kt
@@ -55,16 +55,15 @@ class HiddenTabViewModel @Inject constructor(
         refresh()
         // Live cross-device updates: any quarantine.* event (hide /
         // unhide / resolve / delete from another device) re-fetches the
-        // snapshot while the tab is open. Mirrors Flutter's
-        // LiveEventsDispatcher invalidating myQuarantineProvider; here
-        // the screen-scoped VM subscribes directly, per the Android
-        // dispatcher's documented pattern for screen-scoped state.
+        // snapshot while the tab is open. The screen-scoped VM subscribes
+        // directly, the dispatcher's documented pattern for screen-scoped
+        // state.
         viewModelScope.launch {
             eventsStream.events
                 .filter { it.kind.startsWith("quarantine.") }
                 .collect { refresh() }
         }
-        // Screen-level auto-recovery (issue #1245): re-pull when server
+        // Screen-level auto-recovery: re-pull when server
         // health returns, so a load that failed offline heals unprompted.
         viewModelScope.launch {
             networkStatus.recoveries().collect { refresh() }
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/requests/data/RequestsRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/requests/data/RequestsRepository.kt
index 7e7eb9be..4814e651 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/requests/data/RequestsRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/requests/data/RequestsRepository.kt
@@ -19,9 +19,8 @@ enum class CancelOutcome { Synced, Queued }
 
 /**
  * Read-through accessor for the caller's own requests +
- * cancel-while-pending write. No Room caching for v1 — same rationale
- * as HistoryRepository; the offline-snapshot mirror lands with a
- * later slice. Cancel is offline-first: direct REST on the happy
+ * cancel-while-pending write. No Room caching. Cancel is offline-first:
+ * direct REST on the happy
  * path, MutationQueue fallback on transport failure so the user's
  * intent persists across connectivity loss.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/requests/ui/RequestsScreen.kt b/android/app/src/main/java/com/fabledsword/minstrel/requests/ui/RequestsScreen.kt
index ab5c721f..03d13202 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/requests/ui/RequestsScreen.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/requests/ui/RequestsScreen.kt
@@ -230,8 +230,7 @@ private fun CancelConfirmDialog(
 
 @Composable
 private fun KindAvatar(kind: String) {
-    // Flutter mapping: disc-3 for artist, library-big for album,
-    // music for track.
+    // Icons: disc-3 for artist, library-big for album, music for track.
     val icon = when (kind) {
         "artist" -> Lucide.Disc3
         "album" -> Lucide.LibraryBig
@@ -261,7 +260,7 @@ private fun RequestRef.listenRoute(): Any? = when {
 
 /**
  * "2 albums · 14 tracks ingested" — null when both counts are zero.
- * Singularization matches Flutter ("1 album · 1 track ingested").
+ * Singular when the count is 1 ("1 album · 1 track ingested").
  */
 private fun RequestRef.ingestProgressText(): String? {
     if (importedAlbumCount == 0 && importedTrackCount == 0) return null
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/requests/ui/RequestsViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/requests/ui/RequestsViewModel.kt
index d95597d6..d1c3a82d 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/requests/ui/RequestsViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/requests/ui/RequestsViewModel.kt
@@ -24,7 +24,7 @@ import javax.inject.Inject
 
 private val RELEVANT_EVENT_KINDS = setOf("request.status_changed")
 
-// Cadence for in-flight request polling — matches the web client (#369):
+// Cadence for in-flight request polling — matches the web client:
 // fast enough to feel live, slow enough not to hammer the server.
 private const val POLL_INTERVAL_MS = 12_000L
 
@@ -48,7 +48,7 @@ class RequestsViewModel @Inject constructor(
                 .collect { silentReload() }
         }
         viewModelScope.launch { pollWhileInFlight() }
-        // Screen-level auto-recovery (issue #1245): a load that failed while
+        // Screen-level auto-recovery: a load that failed while
         // the server was unreachable heals the moment health returns, without
         // waiting for the next poll tick.
         viewModelScope.launch {
@@ -76,13 +76,13 @@ class RequestsViewModel @Inject constructor(
 
     /**
      * Auto-poll while any request is mid-ingest (status APPROVED), matching the
-     * web client (#369). Reloads silently every [POLL_INTERVAL_MS] and pauses
+     * web client. Reloads silently every [POLL_INTERVAL_MS] and pauses
      * when nothing is in-flight — complements the SSE push so progress stays
      * live even if the event stream drops.
      */
     private suspend fun pollWhileInFlight() {
         while (true) {
-            // Also retry from a failed load (issue #1245): from UiState.Error
+            // Also retry from a failed load: 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.
@@ -149,7 +149,7 @@ class RequestsViewModel @Inject constructor(
                         }
                     }
                 }
-                // Drift #577: only refetch on the Synced outcome. The
+                // Only refetch on the Synced outcome. The
                 // Queued path is offline by definition — the optimistic
                 // removal at the top of cancel() is correct, and a
                 // refresh() call here would either (a) get the
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/search/ui/SearchViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/search/ui/SearchViewModel.kt
index b0d265eb..24a08477 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/search/ui/SearchViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/search/ui/SearchViewModel.kt
@@ -72,7 +72,7 @@ class SearchViewModel @Inject constructor(
                     runSearch(q)
                 }
         }
-        // Screen-level auto-recovery (issue #1245): a search that failed
+        // Screen-level auto-recovery: 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 {
@@ -105,7 +105,7 @@ class SearchViewModel @Inject constructor(
 
     /**
      * Tapping a search result builds a queue from the full visible
-     * track-results list starting at the tapped entry, matching Flutter.
+     * track-results list starting at the tapped entry.
      * Falls back to single-track playback when the loaded state isn't
      * a Success (shouldn't happen in normal flow but keeps the call
      * safe).
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/settings/data/NormalizationPrefs.kt b/android/app/src/main/java/com/fabledsword/minstrel/settings/data/NormalizationPrefs.kt
index ea9d6a1a..a77deeec 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/settings/data/NormalizationPrefs.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/settings/data/NormalizationPrefs.kt
@@ -4,7 +4,7 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
 /**
- * The user's loudness-normalization preference (M464 #4998). The server
+ * The user's loudness-normalization preference. The server
  * holds it, so this device, the web player and casts all level the same
  * way; a copy is kept on the device so offline playback still applies it.
  * Field names and values match `GET/PUT /api/me/normalization`.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/settings/data/NormalizationRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/settings/data/NormalizationRepository.kt
index 4e6f0727..52d2a57f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/settings/data/NormalizationRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/settings/data/NormalizationRepository.kt
@@ -14,11 +14,11 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * The user's loudness-normalization preference (M464 #4998). The device's
+ * The user's loudness-normalization preference. The device's
  * copy lives in [AuthStore] so playback reads it offline; the server's copy
  * is what other devices and casts use.
  *
- * Writes follow rule 100: the device shows the change at once, the PUT is
+ * Writes are offline-first: the device shows the change at once, the PUT is
  * best effort, and a failed PUT is queued for the MutationReplayer.
  */
 @Singleton
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/AboutCardViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/AboutCardViewModel.kt
index c05127dc..b9539bd8 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/AboutCardViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/AboutCardViewModel.kt
@@ -42,8 +42,8 @@ data class AboutUiState(
     // can drive the comparison without a BuildConfig.
     val installedCode: Long = BuildConfig.VERSION_CODE.toLong(),
     // A debug build is signed with this machine's debug key, so the server's
-    // release-signed APK can never install over it (family idea #5103,
-    // practice 9). It updates from Android Studio instead.
+    // release-signed APK can never install over it. It updates from Android
+    // Studio instead.
     val selfUpdates: Boolean = !BuildConfig.DEBUG,
     val isChecking: Boolean = false,
     val installStage: InstallStage = InstallStage.IDLE,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/NormalizationCard.kt b/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/NormalizationCard.kt
index bcb5ffd2..0e9076ee 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/NormalizationCard.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/NormalizationCard.kt
@@ -27,7 +27,7 @@ import com.fabledsword.minstrel.settings.data.NormalizationMode
 import com.fabledsword.minstrel.settings.data.NormalizationPrefs
 
 /**
- * Volume leveling (M464 #4998). The choice is stored on the server, so the
+ * Volume leveling. The choice is stored on the server, so the
  * web player and casts follow it too.
  */
 @Composable
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/SettingsViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/SettingsViewModel.kt
index 6a1e9562..4de63638 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/SettingsViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/SettingsViewModel.kt
@@ -20,7 +20,7 @@ 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.
+    // account debug flag (admin-set) + this device's local opt-out.
     val diagnosticsEnabledByAdmin: Boolean = false,
     val diagnosticsOptOut: Boolean = false,
 )
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/StorageCard.kt b/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/StorageCard.kt
index 351eb31b..612194c1 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/StorageCard.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/settings/ui/StorageCard.kt
@@ -56,15 +56,11 @@ fun StorageCard(viewModel: StorageViewModel = hiltViewModel()) {
                 color = MaterialTheme.colorScheme.onSurface,
             )
             UsageRow(usedBytes = state.usedBytes)
-            // Per-bucket caps + prefetch toggle + cache-liked toggle
-            // intentionally omitted in v1. The underlying systems
-            // (per-bucket SimpleCache eviction, MetadataPrefetcher,
-            // pin-on-like flow) don't exist on Android yet — surfacing
-            // controls that silently do nothing is worse than hiding
-            // them. Only the rolling cap is wired
-            // (PlayerFactory.kt:43-47 uses rollingCapBytes only); the
-            // Liked cap was a no-op. CacheSettings fields stay
-            // persisted so the controls return when the systems land.
+            // Only the rolling cap is shown. Nothing enforces a separate
+            // liked cap or pins liked tracks yet, and a control that silently
+            // does nothing is worse than none. The prefetch window has no
+            // control either; AudioPrefetcher uses the stored value (default
+            // 5). CacheSettings keeps every field so the controls can return.
             CapDropdown(
                 label = "Cache limit",
                 value = state.settings.rollingCapBytes,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/ServerUrls.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/ServerUrls.kt
index 1caeb7b1..86d9bed5 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/ServerUrls.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/ServerUrls.kt
@@ -13,8 +13,7 @@ package com.fabledsword.minstrel.shared
  * render their own fallback (or, for playback, the queue entry fails
  * fast rather than handing Media3 a malformed URI).
  *
- * This is the single place a server URL becomes loadable, mirroring
- * Flutter's `ServerImage._resolve` (which prepends the base URL).
+ * This is the single place a server URL becomes loadable.
  * Any code handing a server-provided URL to a network client must
  * route through here — covers, stream URLs, anything `/api/...`.
  */
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/UpdateVeilController.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/UpdateVeilController.kt
index 0e7161a0..79ebf602 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/UpdateVeilController.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/UpdateVeilController.kt
@@ -91,13 +91,12 @@ data class VeilSessionResult(
  * Drives an "updating" overlay from *observed content change and settling*
  * rather than from a fixed delay.
  *
- * The problem this replaces: a veil held for `refresh().join() + 500ms`
- * lowers while the screen is still moving, because finishing the network
- * pull is nowhere near the end of the visible work — the pull writes id
- * lists, then tiles hydrate one by one, then artwork loads. And a plain
- * `isUpdating` Boolean set in a `finally` gets cleared by whichever of
- * two overlapping refreshes finishes first, wiping the veil off mid-update
- * (issue #2327).
+ * A fixed hold (`refresh().join() + 500ms`) lowers while the screen is
+ * still moving, because finishing the network pull is nowhere near the end
+ * of the visible work — the pull writes id lists, then tiles hydrate one by
+ * one, then artwork loads. And a plain `isUpdating` Boolean set in a
+ * `finally` gets cleared by whichever of two overlapping refreshes finishes
+ * first, wiping the veil off mid-update.
  *
  * So instead: run [work], raise only if the content actually changes, then
  * hold until [settleSignal] reports the screen has stopped changing for
@@ -121,7 +120,7 @@ data class VeilSessionResult(
  * cached content. Giving up ends only *this* session — it sets no latch and
  * blocks nothing, so the caller's own recovery paths (reconnect re-pull,
  * freshness sweeps, the next event, a manual pull) keep retrying afterwards
- * exactly as before. Callers that want to surface a failure can do it from
+ * regardless. Callers that want to surface a failure can do it from
  * [onSessionEnd] instead.
  *
  * @param work one refresh attempt; returns true when it succeeded.
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/AppBarActionsViewModel.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/AppBarActionsViewModel.kt
index 7225af92..718433b4 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/AppBarActionsViewModel.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/AppBarActionsViewModel.kt
@@ -33,7 +33,7 @@ class AppBarActionsViewModel @Inject constructor(
             initialValue = false,
         )
 
-    /** Unread notices for the bell's badge (M489). */
+    /** Unread notices for the bell's badge. */
     val unreadCount: StateFlow<Int> = notifications.unreadCount
         .stateIn(
             scope = viewModelScope,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/CachedDot.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/CachedDot.kt
index 8405f5a6..c17b749f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/CachedDot.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/CachedDot.kt
@@ -19,12 +19,11 @@ import com.fabledsword.minstrel.theme.LocalFabledSwordTheme
 val LocalCachedTrackIds = staticCompositionLocalOf { emptySet<String>() }
 
 /**
- * Small accent download glyph shown next to a track row when the track
- * is cached locally. Ports Flutter's `CachedIndicator`
- * (`circle_check_big`, size 14, accent, 4px left pad) — renders nothing
- * when the track isn't cached. Reads the reactive set from
- * [LocalCachedTrackIds], so the dot appears/disappears as the cache
- * fills and evicts without per-row queries.
+ * Small accent glyph (`circle_check_big`, size 14, 4px left pad) shown
+ * next to a track row when the track is cached locally; renders nothing
+ * otherwise. Reads the reactive set from [LocalCachedTrackIds], so the
+ * dot appears/disappears as the cache fills and evicts without per-row
+ * queries.
  */
 @Composable
 fun CachedDot(trackId: String, modifier: Modifier = Modifier) {
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/EmptyState.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/EmptyState.kt
index 26694390..2b1d0909 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/EmptyState.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/EmptyState.kt
@@ -31,7 +31,7 @@ import com.composables.icons.lucide.Lucide
  * in nested-scroll dispatch when wrapped by PullToRefreshBox —
  * pull-to-refresh fires on Empty / Error states without the content
  * actually scrolling. The fillParentMaxSize on the inner Box keeps
- * the centered visual identical to the pre-LazyColumn layout.
+ * the content centered in the viewport.
  */
 @Composable
 fun EmptyState(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/LikeButton.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/LikeButton.kt
index 67067ae4..78927cb4 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/LikeButton.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/LikeButton.kt
@@ -25,7 +25,7 @@ import com.composables.icons.lucide.Lucide
  * matches the cross-app pattern (Spotify, Apple Music, etc.). Lucide
  * ships outlined-only by design; the filled variant is built locally
  * from the same path data so we keep the project's icon system
- * consistent (operator 2026-06-01).
+ * consistent.
  */
 @Composable
 fun LikeButton(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/MainAppBarActions.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/MainAppBarActions.kt
index d8cffb5f..634400b4 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/MainAppBarActions.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/MainAppBarActions.kt
@@ -33,8 +33,8 @@ import com.fabledsword.minstrel.nav.Search as SearchRoute
 import com.fabledsword.minstrel.nav.Settings as SettingsRoute
 
 /**
- * The universal navigation surface for every shell screen — Flutter's
- * `MainAppBarActions`. There is no bottom nav, drawer, or rail; every
+ * The universal navigation surface for every shell screen. There is no
+ * bottom nav, drawer, or rail; every
  * top-level AppBar carries this row, and the kebab covers the rest.
  *
  *   [Home] [Library] [Search] [ ⋮ Playlists / Discover / Settings / Admin ]
@@ -79,7 +79,7 @@ fun MainAppBarActions(
     }
 }
 
-/** The inbox bell with its unread badge (M489): the count to 9, then "9+". */
+/** The inbox bell with its unread badge: the count to 9, then "9+". */
 @Composable
 private fun NotificationsBell(unread: Int, onClick: () -> Unit) {
     val label = badgeLabel(unread)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/PullToRefreshScaffold.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/PullToRefreshScaffold.kt
index b3fdefa2..f786e115 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/PullToRefreshScaffold.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/PullToRefreshScaffold.kt
@@ -25,10 +25,6 @@ import kotlinx.coroutines.launch
  * not on a heuristic delay. ViewModels whose existing `refresh()`
  * launched into viewModelScope just need to start returning the Job
  * (`fun refresh(): Job = viewModelScope.launch { ... }`).
- *
- * Mirrors the Flutter `RefreshIndicator` wrapping that every list +
- * grid has in the web/mobile client — Android v1 was missing this
- * everywhere (audit #8).
  */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/ServerImage.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/ServerImage.kt
index 0bd0b25e..19310895 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/ServerImage.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/ServerImage.kt
@@ -21,8 +21,8 @@ import com.fabledsword.minstrel.shared.resolveServerUrl
 // The fallback fades out as the artwork crossfades in (Coil's crossfade is
 // configured globally on the ImageLoader in MinstrelApplication). Matching
 // durations makes the swap read as one cross-dissolve; without the fade the
-// placeholder icon vanished a frame before the cover appeared, which is the
-// "art popping in" the Home veil exists to hide (issue #2327).
+// placeholder icon vanishes a frame before the cover appears, which is the
+// "art popping in" the Home veil exists to hide.
 private const val FALLBACK_FADE_MS = 220
 
 /**
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/ShellScaffold.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/ShellScaffold.kt
index d445cb5d..6d6327e5 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/ShellScaffold.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/ShellScaffold.kt
@@ -92,10 +92,9 @@ fun ShellScaffold(
         }
     }
     // Consume the status-bar inset once here so the banner stack sits
-    // below the status bar (mirrors Flutter's SafeArea(bottom:false)).
-    // statusBarsPadding consumes the inset for descendants, so the in-
-    // shell screens' app bars no longer re-pad for the status bar —
-    // avoiding a double inset while fixing banners drawing under it.
+    // below the status bar. statusBarsPadding consumes the inset for
+    // descendants, so the in-shell screens' app bars do not re-pad for
+    // the status bar — no double inset, and no banner drawing under it.
     Column(modifier = modifier.fillMaxSize().statusBarsPadding()) {
         // Banner slot. VersionTooOldBanner appears when the server's
         // min_client_version exceeds our build; UpdateBanner softly
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/Skeletons.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/Skeletons.kt
index 5fe31a88..93a72f5e 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/Skeletons.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/Skeletons.kt
@@ -30,10 +30,9 @@ import androidx.compose.ui.unit.dp
 import com.fabledsword.minstrel.theme.FabledSwordFlatTokens
 
 /**
- * Skeleton placeholders for cold-load states. Mirror Flutter's
- * `SkeletonAlbumTile` / `SkeletonArtistTile` / `_CompactTrackSkeleton`
- * — same geometry as the real cards so the layout doesn't reflow when
- * real data lands and the screen-level Crossfade reveals.
+ * Skeleton placeholders for cold-load states, with the same geometry as
+ * the real cards so the layout doesn't reflow when real data lands and
+ * the screen-level Crossfade reveals.
  */
 
 private const val PULSE_MIN_ALPHA = 0.3f
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/TrackRow.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/TrackRow.kt
index 4c708811..d3d4eb67 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/TrackRow.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/TrackRow.kt
@@ -23,13 +23,12 @@ private const val OFFLINE_UNAVAILABLE_ALPHA = 0.4f
 private const val OFFLINE_TAP_MESSAGE = "Not downloaded — connect to play"
 
 /**
- * Shared track-list row. Replaces the 5 per-screen `TrackRow`s — every
- * track list shares the same row skeleton (clickable Row, title + artist
- * column, CachedDot, nowPlaying highlight); only the leading element
- * (track number vs cover thumb) and the trailing controls (duration,
- * relative time, LikeButton, TrackActionsButton) vary. Callers fill
- * those via the [leading] and [trailing] slots so each screen's row is
- * a thin wrapper that no longer re-implements the Row layout.
+ * Shared track-list row. Every track list shares the same row skeleton
+ * (clickable Row, title + artist column, CachedDot, nowPlaying
+ * highlight); only the leading element (track number vs cover thumb)
+ * and the trailing controls (duration, relative time, LikeButton,
+ * TrackActionsButton) vary. Callers fill those via the [leading] and
+ * [trailing] slots.
  *
  * [enabled] gates the click (use for unavailable rows). [contentAlpha]
  * dims the title + artist text colors — pass <1f for the
@@ -43,8 +42,8 @@ private const val OFFLINE_TAP_MESSAGE = "Not downloaded — connect to play"
  * fires a Toast instead of attempting playback. The text dims so the
  * user can see at a glance which rows in a long list will work offline.
  * The trailing slot stays interactive so the kebab / like / playlist-
- * add affordances can still queue mutations for offline replay (Phase
- * 5 of #618 gates those at the action level).
+ * add affordances can still queue mutations for offline replay; each
+ * action gates itself for offline.
  */
 @Composable
 fun TrackRow(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/AddToPlaylistSheet.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/AddToPlaylistSheet.kt
index 288a14a6..df907560 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/AddToPlaylistSheet.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/AddToPlaylistSheet.kt
@@ -31,8 +31,8 @@ import com.fabledsword.minstrel.shared.UiState
 
 /**
  * ModalBottomSheet that lists the caller's user-owned playlists and
- * pops back with the picked id via [onPick]. Mirrors Flutter's
- * `AddToPlaylistSheet`. System playlists are filtered out — they're
+ * pops back with the picked id via [onPick]. System playlists are
+ * filtered out — they're
  * not appendable.
  */
 @OptIn(ExperimentalMaterial3Api::class)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/HideTrackSheet.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/HideTrackSheet.kt
index 8ffd2cd0..d4063d54 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/HideTrackSheet.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/HideTrackSheet.kt
@@ -38,7 +38,7 @@ private val HIDE_REASONS = listOf(
 
 /**
  * ModalBottomSheet that collects a hide reason + optional notes and
- * pops back via [onSubmit]. Mirrors Flutter's `HideTrackSheet`. The
+ * pops back via [onSubmit]. The
  * reason vocabulary matches the server wire values exactly.
  */
 @OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/TrackActionsSheet.kt b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/TrackActionsSheet.kt
index 139e8b55..7609d195 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/TrackActionsSheet.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/shared/widgets/trackactions/TrackActionsSheet.kt
@@ -37,8 +37,8 @@ import com.composables.icons.lucide.User
 import com.fabledsword.minstrel.models.TrackRef
 
 /**
- * The 7-item track-actions modal bottom sheet. Mirrors Flutter's
- * `TrackActionsSheet`. Opens via [TrackActionsButton] (or any caller
+ * The 7-item track-actions modal bottom sheet. Opens via
+ * [TrackActionsButton] (or any caller
  * holding a `TrackRef`); closes via [onDismiss] after any item runs
  * or when the user swipes down.
  *
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/theme/FabledSwordTheme.kt b/android/app/src/main/java/com/fabledsword/minstrel/theme/FabledSwordTheme.kt
index 288c19bc..96d21e9f 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/theme/FabledSwordTheme.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/theme/FabledSwordTheme.kt
@@ -6,11 +6,9 @@ import androidx.compose.ui.unit.Dp
 
 /**
  * Mode-resolved snapshot of the FabledSword design system, exposed via
- * [LocalFabledSwordTheme]. Mirrors the Flutter `FabledSwordTheme`
- * ThemeExtension — most Flutter widgets read `Theme.of(context).extension<
- * FabledSwordTheme>()!.parchment` directly rather than via `colorScheme`,
- * and the Android port follows the same convention to keep token
- * semantics centralized rather than scattered across Material role mappings.
+ * [LocalFabledSwordTheme]. UI code reads tokens from here rather than via
+ * `colorScheme`, so token semantics stay centralized instead of scattered
+ * across Material role mappings.
  *
  * UI code reads tokens via `LocalFabledSwordTheme.current.parchment`,
  * `.iron`, `.accent`, etc. The MinstrelTheme composable swaps between
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/theme/FabledSwordTokens.kt b/android/app/src/main/java/com/fabledsword/minstrel/theme/FabledSwordTokens.kt
index 5a52e73c..583de92e 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/theme/FabledSwordTokens.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/theme/FabledSwordTokens.kt
@@ -5,8 +5,7 @@ import androidx.compose.ui.unit.dp
 
 /**
  * Raw color values for the dark surface cohort. Source of truth:
- * `shared/fabledsword.tokens.json` (dark block) — moved to the repo root
- * when the Flutter client was deleted; the tokens were never its property.
+ * `shared/fabledsword.tokens.json` (dark block).
  *
  * Token names are **semantic roles**, not literal colors. In dark
  * mode, `parchment` is light text on dark surfaces (#E8E4D8); in
@@ -66,12 +65,9 @@ object FabledSwordFlatTokens {
 }
 
 /**
- * Back-compat alias mirroring the Flutter `FabledSwordTokens` class
- * (dark surfaces + flat). Existing call sites that read
- * `FabledSwordTokens.iron` continue to work but bind to dark-mode
- * values regardless of system mode. New code should read from
- * `LocalFabledSwordTheme.current` instead. Removed in a follow-up
- * once all widgets are migrated.
+ * Deprecated alias (dark surfaces + flat) that binds to dark-mode values
+ * regardless of system mode. Nothing reads it; UI code reads
+ * `LocalFabledSwordTheme.current`.
  */
 @Deprecated(
     "Use LocalFabledSwordTheme.current — see FabledSwordTheme.kt",
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/theme/MinstrelTheme.kt b/android/app/src/main/java/com/fabledsword/minstrel/theme/MinstrelTheme.kt
index 220e9f1b..69db9b51 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/theme/MinstrelTheme.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/theme/MinstrelTheme.kt
@@ -65,11 +65,11 @@ private fun lightMaterialColorScheme() =
  * Theme entry point. Selects dark vs light based on system mode and
  * provides both the Material 3 [MaterialTheme] and the
  * [LocalFabledSwordTheme] for token-level reads. [LocalActionColors]
- * is kept for back-compat — same values; consumers should migrate to
- * `LocalFabledSwordTheme.current.moss` etc. in a later cleanup.
+ * carries the same values for the composables that still read it;
+ * new code reads `LocalFabledSwordTheme.current.moss` etc.
  *
- * `darkOverride` lets callers force one mode (Phase 11 Settings will
- * carry a user-controlled override).
+ * `darkOverride` forces one mode; MainActivity passes the user's theme
+ * setting.
  */
 @Composable
 fun MinstrelTheme(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/theme/Typography.kt b/android/app/src/main/java/com/fabledsword/minstrel/theme/Typography.kt
index 373e275d..5f4c8905 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/theme/Typography.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/theme/Typography.kt
@@ -12,12 +12,11 @@ import com.fabledsword.minstrel.R
 /**
  * Bundled typefaces, vendored into res/font by tools/vendor-fonts.py.
  *
- * These were fetched at runtime through the Play Services font provider until
- * 2026-09-09. That is a network dependency for rendering, and a deployed
- * instance is not guaranteed one — the provider is also absent entirely on
- * devices without Play Services, where the app silently fell back to the
- * platform default and stopped looking like Minstrel. Bundling costs ~0.86 MB
- * of APK and removes both failure modes.
+ * Bundled rather than fetched through the Play Services font provider:
+ * that is a network dependency for rendering, which a deployed instance is
+ * not guaranteed, and the provider is absent entirely on devices without
+ * Play Services, where text silently falls back to the platform default.
+ * Bundling costs ~0.86 MB of APK and removes both failure modes.
  *
  * Per FabledSword design system:
  *   - Fraunces — display + headline (mythic serif)
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/update/api/ClientVersionApi.kt b/android/app/src/main/java/com/fabledsword/minstrel/update/api/ClientVersionApi.kt
index b05c79f4..cde173f4 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/update/api/ClientVersionApi.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/update/api/ClientVersionApi.kt
@@ -5,8 +5,7 @@ import retrofit2.http.GET
 
 /**
  * Retrofit interface for `GET /api/client/version`. Returns the
- * server-bundled APK version + download URL + size. Mirrors the
- * Flutter `ClientUpdateController` shape.
+ * server-bundled APK version + download URL + size.
  */
 interface ClientVersionApi {
     @GET("api/client/version")
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/update/data/InstallOutcome.kt b/android/app/src/main/java/com/fabledsword/minstrel/update/data/InstallOutcome.kt
index 86fbd0d8..ef6e6dcd 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/update/data/InstallOutcome.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/update/data/InstallOutcome.kt
@@ -1,11 +1,11 @@
 package com.fabledsword.minstrel.update.data
 
 /**
- * Terminal verdict from the platform on a self-update install (#2438).
+ * Terminal verdict from the platform on a self-update install.
  *
- * The old `ACTION_VIEW` handoff had no verdict at all — we fired an intent and
- * assumed. A [PackageInstaller][android.content.pm.PackageInstaller] session
- * reports back, so "declined" and "failed" stop looking identical.
+ * A [PackageInstaller][android.content.pm.PackageInstaller] session
+ * reports back, unlike an `ACTION_VIEW` handoff, so "declined" and
+ * "failed" do not look identical.
  */
 sealed interface InstallOutcome {
     /**
@@ -30,11 +30,9 @@ sealed interface InstallOutcome {
  * [UpdateBanner][com.fabledsword.minstrel.update.ui.UpdateBanner] and the
  * Settings About card.
  *
- * DOWNLOADING and INSTALLING are deliberately distinct. They used to be one
- * state because the install half was fire-and-forget and took no time from our
- * side; now that we await the platform's verdict, collapsing them would leave
- * the UI claiming "Downloading…" through an install that can sit on a confirm
- * dialog indefinitely.
+ * DOWNLOADING and INSTALLING are deliberately distinct: the install awaits
+ * the platform's verdict and can sit on a confirm dialog indefinitely, so
+ * one combined state would leave the UI claiming "Downloading…" through it.
  */
 enum class InstallStage { IDLE, DOWNLOADING, INSTALLING, ERROR }
 
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/update/data/SelfUpdateSession.kt b/android/app/src/main/java/com/fabledsword/minstrel/update/data/SelfUpdateSession.kt
index 1b4a1323..90442929 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/update/data/SelfUpdateSession.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/update/data/SelfUpdateSession.kt
@@ -30,20 +30,20 @@ private const val WRITE_FROM_START = 0L
 private const val RESULT_ACTION = "com.fabledsword.minstrel.INSTALL_RESULT"
 
 /**
- * Installs an APK over ourselves through a [PackageInstaller] session (#2438).
+ * Installs an APK over ourselves through a [PackageInstaller] session.
  *
  * Split from [ApkInstaller] because the two halves are different work — one
  * speaks HTTP, the other speaks to the package manager — and the session half
  * carries a receiver, a PendingIntent and version-gated params that would
  * crowd the downloader out of its own file.
  *
- * ## Why a session, rather than the ACTION_VIEW intent this replaced
+ * ## Why a session, rather than an ACTION_VIEW intent
  *
  * Two reasons, and the second is the one that matters to users.
  *
- * The old path fired `ACTION_VIEW` at an `application/vnd.android.package-archive`
- * URI and hoped. It could not report an outcome, so a failed install and a
- * user who declined looked identical — see [InstallOutcome].
+ * `ACTION_VIEW` at an `application/vnd.android.package-archive` URI cannot
+ * report an outcome, so a failed install and a user who declined look
+ * identical — see [InstallOutcome].
  *
  * More importantly, a session is where the platform lets a self-updater say it
  * is one. [PackageInstaller.SessionParams.setRequireUserAction] with
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/update/data/UpdateBannerController.kt b/android/app/src/main/java/com/fabledsword/minstrel/update/data/UpdateBannerController.kt
index 4bd9bef7..c81f6b83 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/update/data/UpdateBannerController.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/update/data/UpdateBannerController.kt
@@ -22,16 +22,16 @@ private const val POLL_INTERVAL_MS = 24 * 60 * 60 * 1000L
  * APK outranks this build — by ordering key where the server reports one,
  * by name otherwise — exposes its [UpdateInfo] so
  * [com.fabledsword.minstrel.update.ui.UpdateBanner] can nudge an
- * install. Mirrors Flutter's `ClientUpdateController`.
+ * install.
  *
  * Dismissals are kept in memory and keyed by version, so dismissing
  * one release's banner still lets a later release re-surface — and a
- * restart re-shows it, which is acceptable nudging for v1 (matches
- * Flutter). Server 404 / network errors stay silent. Constructed at
+ * restart re-shows it, which is acceptable nudging. Server 404 /
+ * network errors stay silent. Constructed at
  * launch via the construct-the-singleton trick in `MinstrelApplication`.
  *
  * A debug build never polls: it is signed with a local debug key, so the
- * server's release-signed APK could never install over it (#5103).
+ * server's release-signed APK could never install over it.
  */
 @Singleton
 class UpdateBannerController @Inject constructor(
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/update/data/UpdateRepository.kt b/android/app/src/main/java/com/fabledsword/minstrel/update/data/UpdateRepository.kt
index 6eddfd73..4dbd9b24 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/update/data/UpdateRepository.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/update/data/UpdateRepository.kt
@@ -8,9 +8,8 @@ import javax.inject.Inject
 import javax.inject.Singleton
 
 /**
- * Thin facade over `/api/client/version`. Reused by the About card
- * (Check for updates button) and — in a follow-up — a startup
- * version banner.
+ * Thin facade over `/api/client/version`, used by the About card's
+ * Check for updates button and by [UpdateBannerController].
  */
 @Singleton
 class UpdateRepository @Inject constructor(retrofit: Retrofit) {
@@ -32,10 +31,10 @@ private fun UpdateInfoWire.toDomain(): UpdateInfo = UpdateInfo(
  *
  * **Decide on the ordering key whenever the server sends one.** That is the
  * same value Android's package installer compares, so an offer made this way
- * implies an install the platform will actually accept. The app used to
- * compare NAMES while the platform installed by `versionCode`, with nothing
- * keeping the two orderings consistent — so it could offer a build Android
- * then refused as a downgrade, or stay quiet about one it would have taken.
+ * implies an install the platform will actually accept. Comparing NAMES
+ * while the platform installs by `versionCode` keeps nothing consistent
+ * between the two orderings: it can offer a build Android then refuses as
+ * a downgrade, or stay quiet about one it would take.
  *
  * Name comparison survives only as the fallback for a server that predates
  * the field. A null code means "this server cannot tell me" — never "zero" —
@@ -55,8 +54,8 @@ fun isUpdateAvailable(
     }
 
 /**
- * True when [server] is strictly newer than [installed]. Mirrors
- * Flutter's `isVersionNewer` — splits both strings on `.`, parses
+ * True when [server] is strictly newer than [installed]. Splits both
+ * strings on `.`, parses
  * each component as an int (non-numeric = 0), pads the shorter list
  * with zeros, then compares component-wise. Handles our date-style
  * versions (2026.05.10.1) which exceed semver's three-part shape,
diff --git a/android/app/src/main/java/com/fabledsword/minstrel/update/ui/UpdateBanner.kt b/android/app/src/main/java/com/fabledsword/minstrel/update/ui/UpdateBanner.kt
index ebb6b93c..906a5287 100644
--- a/android/app/src/main/java/com/fabledsword/minstrel/update/ui/UpdateBanner.kt
+++ b/android/app/src/main/java/com/fabledsword/minstrel/update/ui/UpdateBanner.kt
@@ -34,15 +34,15 @@ import com.fabledsword.minstrel.update.data.isBusy
 /**
  * Shell-level soft banner that nudges an available update. Renders
  * nothing until [UpdateBannerController] surfaces a newer bundled APK
- * (and the user hasn't dismissed that version). Ports Flutter's
- * `UpdateBanner`: a download glyph, "Update Minstrel · {version}
- * available", an Install button (download → system installer), and a
- * dismiss X. Uses an understated surface tone, not the alarming
- * error color reserved for `VersionTooOldBanner`.
+ * (and the user hasn't dismissed that version): a download glyph,
+ * "Update Minstrel · {version} available", an Install button
+ * (download → system installer), and a dismiss X. Uses an understated
+ * surface tone, not the alarming error color reserved for
+ * `VersionTooOldBanner`.
  *
- * Divergence: [ApkInstaller][com.fabledsword.minstrel.update.data.ApkInstaller]
+ * [ApkInstaller][com.fabledsword.minstrel.update.data.ApkInstaller]
  * exposes no byte progress, so the downloading state is an
- * indeterminate bar rather than Flutter's determinate one.
+ * indeterminate bar.
  */
 @Composable
 fun UpdateBanner(viewModel: UpdateBannerViewModel = hiltViewModel()) {
diff --git a/android/app/src/main/res/drawable/ic_notification.xml b/android/app/src/main/res/drawable/ic_notification.xml
index f51a5da5..a55aa330 100644
--- a/android/app/src/main/res/drawable/ic_notification.xml
+++ b/android/app/src/main/res/drawable/ic_notification.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- Status-bar icon for Minstrel's own notifications (M489 #5347): Lucide's
+<!-- Status-bar icon for Minstrel's own notifications: Lucide's
      bell, stroked in white. The system tints it; only the alpha is used. -->
 <vector xmlns:android="http://schemas.android.com/apk/res/android"
     android:width="24dp"
diff --git a/android/app/src/main/res/xml/network_security_config.xml b/android/app/src/main/res/xml/network_security_config.xml
index 11f3b9db..966f66af 100644
--- a/android/app/src/main/res/xml/network_security_config.xml
+++ b/android/app/src/main/res/xml/network_security_config.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!--
-  Replaces a bare android:usesCleartextTraffic="true" on <application> (#2439).
+  Used instead of a bare android:usesCleartextTraffic="true" on <application>.
 
   Cleartext is still permitted app-wide, and it has to be. Two independent
   reasons, neither of which can be narrowed to a domain list:
@@ -16,13 +16,12 @@
   A <domain-config> would be the way to scope this, but it matches literal
   hostnames rather than CIDR ranges, and both sets of hosts above are unknowable
   until runtime. So a permissive base-config is an honest description of our
-  situation — the gain over the manifest attribute is that the reasoning now
-  lives somewhere.
+  situation — the gain over the manifest attribute is that the reasoning
+  lives here.
 
   The LAN/WAN line this file cannot draw is drawn in code instead:
   api/CleartextGuard.kt refuses plain http:// to the Minstrel server whenever
-  the connection lands on a public address (family baseline #5105, practice
-  13). LAN servers and UPnP speakers are unaffected.
+  the connection lands on a public address. LAN servers and UPnP speakers are unaffected.
 
   Worth stating because it looks worse than it is: this is NOT a tamper risk for
   the in-app updater. An APK altered in transit and re-signed is rejected by the
@@ -33,7 +32,7 @@
   Adding <certificates src="user" /> would let self-hosters use HTTPS with their
   own private CA — attractive for this product, and what Mihon does — but it
   also makes the app trust every CA on the device, including a corporate MITM
-  proxy. That's an operator decision, not a default worth assuming.
+  proxy. That's an admin's decision, not a default worth assuming.
 -->
 <network-security-config xmlns:tools="http://schemas.android.com/tools">
     <base-config
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/admin/data/AdminRequestsRepositoryTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/admin/data/AdminRequestsRepositoryTest.kt
index 729a9e3c..9aae6bb9 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/admin/data/AdminRequestsRepositoryTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/admin/data/AdminRequestsRepositoryTest.kt
@@ -11,7 +11,7 @@ import retrofit2.Retrofit
 import kotlin.test.assertEquals
 
 /**
- * The admin queue names who asked from the row itself (#6265): the server
+ * The admin queue names who asked from the row itself: the server
  * sends the requester's username, so the screen needs no users-list fetch.
  */
 class AdminRequestsRepositoryTest {
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/api/AuthCookieInterceptorTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/api/AuthCookieInterceptorTest.kt
index c198776b..fb685099 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/api/AuthCookieInterceptorTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/api/AuthCookieInterceptorTest.kt
@@ -30,7 +30,7 @@ class AuthCookieInterceptorTest {
     fun setup() {
         server = MockWebServer().apply { start() }
 
-        // AuthStore is Room-backed in production (slice 10). The test only
+        // AuthStore is Room-backed in production. The test only
         // exercises the in-memory state mutations of set*; the DAO writes
         // happen on the scope and don't affect the synchronous read path
         // the interceptor uses. UnconfinedTestDispatcher executes the
@@ -115,11 +115,10 @@ class AuthCookieInterceptorTest {
         assertEquals("session=existing", authStore.sessionCookie.value)
     }
 
-    // Drift #568 regression guard: requests to external hosts must NOT
-    // carry the Minstrel session cookie even when the auth store has
-    // one. The shared OkHttpClient is also used by Coil for image
-    // fetches to artwork.musicbrainz.org and the like; leaking the
-    // session cookie to those hosts is a posture violation.
+    // Requests to external hosts must NOT carry the Minstrel session
+    // cookie even when the auth store has one. The shared OkHttpClient
+    // also serves Coil's image fetches to artwork.musicbrainz.org and the
+    // like, and the session cookie must never reach those hosts.
     @Test
     fun `does NOT attach cookie to non-placeholder host`() {
         authStore.setSessionCookie("session=secret")
@@ -134,9 +133,9 @@ class AuthCookieInterceptorTest {
         assertNull(recorded.getHeader("Cookie"))
     }
 
-    // Drift #569 regression guard: a 401 from an external host must
-    // NOT wipe the user's Minstrel session. A misbehaving CDN that's
-    // 401-ing on artwork URLs used to silently sign the user out.
+    // A 401 from an external host must NOT wipe the user's Minstrel
+    // session: a CDN 401-ing on artwork URLs would otherwise silently
+    // sign the user out.
     @Test
     fun `does NOT clear cookie on 401 from non-placeholder host`() {
         authStore.setSessionCookie("session=keep")
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/api/CleartextGuardTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/api/CleartextGuardTest.kt
index 77f78910..b911bede 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/api/CleartextGuardTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/api/CleartextGuardTest.kt
@@ -13,7 +13,7 @@ import kotlin.test.assertEquals
 import kotlin.test.assertFalse
 import kotlin.test.assertTrue
 
-/** Plain http:// to the Minstrel server only on a private address (#5105, practice 13). */
+/** Plain http:// to the Minstrel server only on a private address. */
 class CleartextGuardTest {
     private lateinit var server: MockWebServer
 
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/auth/AuthStoreSessionVaultTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/auth/AuthStoreSessionVaultTest.kt
index 2980d7d8..9dcce27d 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/auth/AuthStoreSessionVaultTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/auth/AuthStoreSessionVaultTest.kt
@@ -18,10 +18,10 @@ import kotlin.test.assertEquals
 import kotlin.test.assertNull
 
 /**
- * The session cookie moved out of the Room row into a Keystore-backed vault
- * (M462 #4985). What matters is that nobody is signed out by it: an install
- * upgrading with a cookie in the row keeps it, a device whose Keystore will
- * not work keeps the old storage, and a sign-in or 401 that lands while the
+ * The session cookie lives in a Keystore-backed vault, not the Room row.
+ * What matters is that nobody is signed out by the move: an install with
+ * a cookie still in the row keeps it, a device whose Keystore will not
+ * work keeps the row storage, and a sign-in or 401 that lands while the
  * one-time move runs is never overwritten by the value it read.
  */
 @OptIn(ExperimentalCoroutinesApi::class)
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/cache/mutations/SupersededToggleIdsTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/cache/mutations/SupersededToggleIdsTest.kt
index 3a223b45..c055e4fb 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/cache/mutations/SupersededToggleIdsTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/cache/mutations/SupersededToggleIdsTest.kt
@@ -143,7 +143,7 @@ class SupersededToggleIdsTest {
     )
 
     // There is one preference per user, so any two queued changes to it
-    // collapse, and only the newest is sent (#4998).
+    // collapse, and only the newest is sent.
     @Test
     fun `only the newest queued normalization change survives`() {
         val rows = listOf(
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/cache/sync/SyncControllerTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/cache/sync/SyncControllerTest.kt
index 2d2b2665..5cd31ff4 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/cache/sync/SyncControllerTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/cache/sync/SyncControllerTest.kt
@@ -25,9 +25,10 @@ import kotlin.test.assertEquals
 import kotlin.test.assertNull
 
 /**
- * The server returns at most 1000 changes a call (#5654). One page per
- * trigger left the cache behind the change log, so deletes from duplicate
- * merges never arrived; a pass pulls pages until the server answers 204.
+ * The server returns at most 1000 changes a call. One page per trigger
+ * would leave the cache behind the change log, so deletes from duplicate
+ * merges would never arrive; a pass pulls pages until the server answers
+ * 204.
  */
 class SyncControllerTest {
     private val api: SyncApi = mockk()
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/connectivity/ReachabilityMachineTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/connectivity/ReachabilityMachineTest.kt
index d1f7fb68..953fb028 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/connectivity/ReachabilityMachineTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/connectivity/ReachabilityMachineTest.kt
@@ -54,16 +54,15 @@ class ReachabilityMachineTest {
         val m = machine()
         m.onLinkChange(up = true)
         m.onOpFailure(nowMs = 1_000)
-        // Spacing matters as of #1209: these must be far enough apart to be
-        // separate evidence rather than one event's worth of fallout. This
-        // test previously used 1_500 — 500ms — which is now deliberately
-        // treated as a burst and does NOT corroborate.
+        // These must be far enough apart to be separate evidence rather
+        // than one event's worth of fallout: 500ms apart is a burst and
+        // does NOT corroborate.
         m.onOpFailure(nowMs = 1_000 + CORROBORATION_MIN_SPACING_MS)
         m.onProbeFailure(nowMs = 1_000 + CORROBORATION_MIN_SPACING_MS + 500)
         assertEquals(ServerHealth.ServerDown, m.health())
     }
 
-    // The #1209 mechanism: an OS network handoff fails every in-flight request
+    // An OS network handoff fails every in-flight request
     // at once. That must NOT reach ServerDown, because ServerDown makes
     // OfflineGatedDataSource refuse uncached tracks outright — the app would
     // decline to play music that plays fine, for a blip already over.
@@ -108,8 +107,8 @@ class ReachabilityMachineTest {
         val m = machine()
         m.onLinkChange(up = true)
         m.onOpFailure(nowMs = 0)
-        // Spaced so this test exercises STALENESS, not the burst rule — with
-        // 1_000 it would have passed for the wrong reason after #1209.
+        // Spaced so this test exercises STALENESS, not the burst rule —
+        // closer failures would pass it for the wrong reason.
         m.onOpFailure(nowMs = CORROBORATION_MIN_SPACING_MS)
         // both op failures are now older than the corroboration window:
         m.onProbeFailure(nowMs = CORROBORATION_MIN_SPACING_MS + CORROBORATION_WINDOW_MS + 1)
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/diagnostics/TransportFlapDetectorTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/diagnostics/TransportFlapDetectorTest.kt
index 490e4615..b066b1d2 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/diagnostics/TransportFlapDetectorTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/diagnostics/TransportFlapDetectorTest.kt
@@ -10,7 +10,7 @@ import kotlin.test.assertNull
  * The rule deciding when renderer transport changes are worth recording as an
  * episode. Worth pinning because both failure directions are costly: too eager
  * and every track transition writes a summary that buries the real one, too
- * shy and the operator's stutter goes unmeasured for another month.
+ * shy and a real stutter goes unmeasured.
  */
 class TransportFlapDetectorTest {
 
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/metadata/MetadataProviderTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/metadata/MetadataProviderTest.kt
index 4d0e8cb9..8894b089 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/metadata/MetadataProviderTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/metadata/MetadataProviderTest.kt
@@ -40,7 +40,7 @@ class MetadataProviderTest {
     }
 
     // A row the server no longer has (a duplicate merge) is dropped, or the
-    // freshness sweep asks for it every 30 minutes forever (#5654).
+    // freshness sweep asks for it every 30 minutes forever.
     @Test
     fun `a 404 drops the cached row`() = runTest {
         coEvery { library.refreshTrack("t1") } throws httpError(404)
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/models/ArtistSuggestionReasonTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/models/ArtistSuggestionReasonTest.kt
index 0000c507..e002c3e6 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/models/ArtistSuggestionReasonTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/models/ArtistSuggestionReasonTest.kt
@@ -4,7 +4,7 @@ import org.junit.jupiter.api.Test
 import kotlin.test.assertEquals
 
 /**
- * The card's subtitle line (#2377). Wording is kept in lockstep with the web
+ * The card's subtitle line. Wording is kept in lockstep with the web
  * client's reasonText() in SuggestionFeed.svelte — these assertions are the
  * record of what that wording IS, so a change on one client without the other
  * shows up as a failure rather than as silent divergence between the two
@@ -60,7 +60,7 @@ class ArtistSuggestionReasonTest {
         )
     }
 
-    // The COMMON case: most candidates have no cached tags (#2376), so the card
+    // The COMMON case: most candidates have no cached tags, so the card
     // must fall back to seed attribution rather than going blank.
     @Test
     fun `no matched tags falls back to seed attribution`() {
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/models/SuggestionSnoozeRefTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/models/SuggestionSnoozeRefTest.kt
index 2dc598ec..d777af99 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/models/SuggestionSnoozeRefTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/models/SuggestionSnoozeRefTest.kt
@@ -5,7 +5,7 @@ import org.junit.jupiter.api.Test
 import kotlin.test.assertEquals
 
 /**
- * `returnsIn` phrasing for the parked-suggestions list (#2375). The clock is
+ * `returnsIn` phrasing for the parked-suggestions list. The clock is
  * injected rather than frozen, so these assertions are stable.
  */
 class SuggestionSnoozeRefTest {
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/notifications/data/NotificationSettingsRepositoryTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/notifications/data/NotificationSettingsRepositoryTest.kt
index bd034ae1..4ec205c1 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/notifications/data/NotificationSettingsRepositoryTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/notifications/data/NotificationSettingsRepositoryTest.kt
@@ -24,7 +24,7 @@ import java.io.IOException
 import kotlin.test.assertEquals
 import kotlin.test.assertFalse
 
-/** Settings follow snippet #5107: shown at once, never overwritten or reordered by an older change. */
+/** Settings are offline-first: shown at once, never overwritten or reordered by an older change. */
 class NotificationSettingsRepositoryTest {
     private val json = Json { ignoreUnknownKeys = true }
     private val api: NotificationsApi = mockk(relaxed = true)
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/notifications/data/NotificationsRepositoryTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/notifications/data/NotificationsRepositoryTest.kt
index cc3e7343..1b8807ca 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/notifications/data/NotificationsRepositoryTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/notifications/data/NotificationsRepositoryTest.kt
@@ -24,7 +24,7 @@ import kotlin.test.assertEquals
 import kotlin.test.assertNull
 
 /**
- * Reads are offline-first (rule 100): the device marks the row at once, and a
+ * Reads are offline-first: the device marks the row at once, and a
  * read the server has not taken is queued, except when the server says the
  * notice is gone.
  */
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/player/DropUnavailableTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/player/DropUnavailableTest.kt
index fd332b5a..fa27cb36 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/player/DropUnavailableTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/player/DropUnavailableTest.kt
@@ -6,7 +6,7 @@ import kotlin.test.assertEquals
 import kotlin.test.assertTrue
 
 /**
- * The queue filter for #2704. The index arithmetic is the part worth pinning:
+ * The queue filter for server-missing tracks. The index arithmetic is the part worth pinning:
  * getting it wrong starts playback on the wrong track, which is a subtler and
  * more annoying bug than the one being fixed.
  */
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/player/RemotePlayerStateTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/player/RemotePlayerStateTest.kt
index b597187a..e444e0b7 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/player/RemotePlayerStateTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/player/RemotePlayerStateTest.kt
@@ -74,7 +74,7 @@ class RemotePlayerStateTest {
         val state = RemotePlayerState()
         state.setPlayIntent(true)
         state.applyError(RuntimeException("connect timeout"))
-        // isPlaying is cleared by the error, but the operator's intent persists.
+        // isPlaying is cleared by the error, but the user's intent persists.
         assertFalse(state.isPlaying)
         assertTrue(state.lastPlayIntent)
     }
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/player/output/SonosAlbumPlayTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/player/output/SonosAlbumPlayTest.kt
index d5e28f69..6d4e67e7 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/player/output/SonosAlbumPlayTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/player/output/SonosAlbumPlayTest.kt
@@ -6,7 +6,7 @@ import kotlin.test.assertEquals
 
 /**
  * The Sonos queue plays straight through, so a track's album play is judged
- * from its neighbours in the list sent (M464 #5002).
+ * from its neighbours in the list sent.
  */
 class SonosAlbumPlayTest {
 
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/player/output/upnp/SoapClientTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/player/output/upnp/SoapClientTest.kt
index ad052e72..d0decd5e 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/player/output/upnp/SoapClientTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/player/output/upnp/SoapClientTest.kt
@@ -16,7 +16,7 @@ import kotlin.test.assertTrue
  * outgoing SOAP envelope + verify the SOAPACTION header shape, and
  * to drive the `<s:Fault>` response path.
  *
- * kxml2 is on the test classpath (Task 4), so
+ * kxml2 is on the test classpath, so
  * `XmlPullParserFactory.newInstance()` resolves on the JVM.
  */
 class SoapClientTest {
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/player/ui/QueueDragMathTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/player/ui/QueueDragMathTest.kt
index db08bd35..deeb9c10 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/player/ui/QueueDragMathTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/player/ui/QueueDragMathTest.kt
@@ -4,7 +4,7 @@ import org.junit.jupiter.api.Test
 import kotlin.test.assertEquals
 
 /**
- * The queue drag math (#2436). The delta cases mirror web's
+ * The queue drag math. The delta cases mirror web's
  * queue-row-math.test.ts one for one, so a change to either client's
  * rounding shows up as a disagreement here rather than as a drop that lands
  * one row off on one platform only.
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/playlists/data/PlaylistTrackAvailabilityTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/playlists/data/PlaylistTrackAvailabilityTest.kt
index 318e7e05..ae19726f 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/playlists/data/PlaylistTrackAvailabilityTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/playlists/data/PlaylistTrackAvailabilityTest.kt
@@ -9,7 +9,7 @@ import kotlin.test.assertTrue
 /**
  * A playlist row can outlive its audio two ways — the track was removed
  * from the library, or the track is still there but its file is missing
- * (#2527). Both must be unplayable, and neither may be silently dropped
+ *. Both must be unplayable, and neither may be silently dropped
  * from the list the user curated.
  */
 class PlaylistTrackAvailabilityTest {
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/settings/data/NormalizationRepositoryTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/settings/data/NormalizationRepositoryTest.kt
index 6853887d..f47f0160 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/settings/data/NormalizationRepositoryTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/settings/data/NormalizationRepositoryTest.kt
@@ -17,7 +17,7 @@ import retrofit2.Retrofit
 import java.io.IOException
 
 /**
- * The normalization preference is written offline-first (rule 100): the
+ * The normalization preference is written offline-first: the
  * device shows the change at once, and a change the server has not seen
  * yet is never overwritten or reordered.
  */
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/shared/UpdateVeilControllerTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/shared/UpdateVeilControllerTest.kt
index 58c98cf6..733fc8e4 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/shared/UpdateVeilControllerTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/shared/UpdateVeilControllerTest.kt
@@ -30,7 +30,7 @@ private const val DRAIN_MS = 3_000L
 /**
  * The veil's job is to go up only when content actually changes, and then to
  * stay up until the screen has stopped moving. Each test pins one of the ways
- * the original fixed-delay implementation got that wrong (issue #2327).
+ * a fixed-delay veil gets that wrong.
  *
  * The controller is built on `backgroundScope` throughout: its consumer
  * loop runs forever, so hanging it off the test's own scope would stop
@@ -40,8 +40,7 @@ private const val DRAIN_MS = 3_000L
  * `advanceTimeBy`: **`advanceUntilIdle()` is useless here.** It advances
  * only while *foreground* work remains, and everything this controller
  * does lives in `backgroundScope` — so it returns having run nothing, and
- * assertions land on a session that never started (CI run 3163 failed all
- * seven of these with "expected 3, actual 0" and friends). Drive the clock
+ * assertions land on a session that never started. Drive the clock
  * deliberately instead; don't "simplify" these back to advanceUntilIdle.
  */
 @OptIn(ExperimentalCoroutinesApi::class)
diff --git a/android/app/src/test/java/com/fabledsword/minstrel/theme/BundledFontsTest.kt b/android/app/src/test/java/com/fabledsword/minstrel/theme/BundledFontsTest.kt
index e061ba24..20ad44d3 100644
--- a/android/app/src/test/java/com/fabledsword/minstrel/theme/BundledFontsTest.kt
+++ b/android/app/src/test/java/com/fabledsword/minstrel/theme/BundledFontsTest.kt
@@ -9,11 +9,11 @@ import kotlin.test.assertTrue
  * Guards that the typefaces ship inside the APK instead of being fetched at
  * runtime.
  *
- * Until 2026-09-09 these were resolved through the Play Services font
- * provider. That needs a network the deployed app is not guaranteed, and a
- * provider that devices without Play Services do not have at all. Both
- * failures are silent — text just renders in the platform default, which
- * reads as a styling regression rather than a missing dependency.
+ * Resolving them through the Play Services font provider needs a network
+ * the deployed app is not guaranteed, and a provider that devices without
+ * Play Services do not have at all. Both failures are silent — text just
+ * renders in the platform default, which reads as a styling regression
+ * rather than a missing dependency.
  *
  * Expectations are read out of Typography.kt itself rather than hardcoded, so
  * this cannot drift away from what the app actually declares: adding a face
diff --git a/android/gradle/libs.versions.toml b/android/gradle/libs.versions.toml
index a551209c..1f6a799d 100644
--- a/android/gradle/libs.versions.toml
+++ b/android/gradle/libs.versions.toml
@@ -5,7 +5,7 @@
 #   - Kotlin 2.3.x: AGP 9's built-in Kotlin path; the older kotlin-android
 #     plugin can't cast AGP 9's ApplicationExtension to the removed
 #     BaseExtension, and KSP 1.x isn't compatible with built-in Kotlin
-#   - KSP 2.3.x (PR #2674, merged Oct 2025): adds AGP 9 built-in Kotlin
+#   - KSP 2.3.x: adds AGP 9 built-in Kotlin
 #     support, so we don't need the kotlin-android plugin at all
 agp = "9.0.1"
 kotlin = "2.3.21"