Second on-device feedback round: eight fixes, and a measured retry policy

The ghost bookcase was an inset bug, not a data bug. LocationsScreen's list
branch dropped the Scaffold's innerPadding while its empty-state branch applied
it, so the first bookcase row rendered under the top app bar and was invisible.
Both of the user's bookcases were always real; they just could not see the first
one, so they made a second. Every other screen was checked for the same class of
bug — Locations was the only one.

Metadata lookup is now designed against a measurement rather than a guess
(docs/METADATA-SOURCES.md § "Measured again 2026-09-09"):

  - Google Books keyless is dead for everyone, permanently. The user's
    residential-IP test returned a quota error naming a shared anonymous PROJECT,
    not an IP, so the earlier "your phone may well get answers" guess is wrong and
    is now marked CORRECTED in place. Because combine() turns any Failed-with-no-
    Found into Unavailable, that standing failure meant every Open Library hiccup
    surfaced as "one or more sources couldn't be reached". The API key is
    deliberately deferred by the user; this commit leaves the source broken.

  - Our own timeouts were manufacturing failures. Over 30 live requests, 13%
    failed — all fast TLS resets under 2.5s — while successes ran to a median of
    4.3s and a max of 22.0s. Two of 26 successes exceeded the old 12s callTimeout,
    so ~8% of lookups that were about to work were cancelled and reported as
    unreachable. Timeouts are now 25s/20s/20s.

That asymmetry (cheap failures, expensive successes) is what RetryPolicy encodes.
It retries TRANSPORT and SERVER_ERROR with a 250ms/750ms jittered backoff, and
deliberately does not retry TIMEOUT (the budget is already spent) or RATE_LIMITED
(hammering a quota is how an intermittent block becomes a permanent one — this
project's IP has already been refused outright once during research).

SourceResult.Failed now carries a FailureKind alongside its human reason, and the
reason names the specific failure ("tls connection reset, 3 attempts") instead of
a generic "network error". That string was already threaded to the UI and dropped
on the floor; LookupFailedSheet now renders it. It is the only diagnostic channel
we have from a real phone, so nothing may parse it.

Also from the same feedback round:
  - Grouped ModalBottomSheet shelf picker, replacing two near-duplicate flat
    dropdowns that listed every bookcase x shelf pair. Sections per bookcase,
    empty bookcases say so, and the most recently used shelf is pinned on top.
  - The recent shelf persists across sessions (SettingsStore.LAST_SHELF_ID) and is
    cleared on sign-out. It is offered, never pre-selected: the user weighed that
    and chose one tap over the risk of silently mis-shelving a book.
  - Locations dialogs and the manual-ISBN dialog auto-focus their first field.
  - The library filter menu offers "Add a bookcase to enable filtering" instead of
    a lone "All books" that is already the active state and cannot be changed.
  - The Locations button is Material Symbols' "shelves" (a bookcase) instead of
    Warehouse (a barn). material-icons-extended 1.7.8 has no bookcase glyph.
  - The scan sheet drops "you can lower the book" — the ISBN echo already says it.

assembleDebug exit 0; testDebugUnitTest 172 tests, 1 skipped, 0 failures (was
138); verifyPaparazziDebug exit 0; assembleRelease exit 0, signed with the real
release key; zero "always 'false'" warnings on a --rerun-tasks rebuild.

Three soft spots are recorded in docs/HANDOFF.md and are NOT verified: the
ghost-bookcase Paparazzi snapshot renders a lookalike of the screen rather than
the screen, the auto-focus calls swallow their own failure and no emulator exists
here, and the picker opens as a sheet stacked on the save sheet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LSnVqWdiQNEcPFRq1hGZAi

README.md

@@ -0,0 +1,179 @@
+# Bookshelf
+
+A private, self-hosted home library app for two people. You scan the
+barcodes on your books; it looks up the metadata, stores it on your own
+server, and keeps both people's phones in sync. No cloud service, no public
+registration, no ads, no accounts you don't control.
+
+## The shared-library model
+
+Bookshelf is built for exactly one household: two people who both want to
+know what's on the shelves and where. There's no concept of "my books" vs.
+"your books" — every book belongs to the one shared library, and either
+person can scan, edit, move, or delete anything in it.
+
+- **Self-hosted.** You run a small [PocketBase](https://pocketbase.io/)
+  server on your own hardware (a NUC, an old laptop, a Raspberry Pi — see
+  [`server/deploy/`](server/deploy/)). Nobody else's data touches it, and it
+  touches nobody else's.
+- **Private by construction.** The server has no public sign-up
+  (`createRule = null` on the `users` collection in PocketBase — only a
+  superuser can create an account, via `server/create-user.sh`), and every
+  read/write to books, shelves, and bookcases requires a logged-in user.
+- **Two named accounts.** Create one account per person with
+  `server/create-user.sh`. That's the whole user model — there is no admin
+  UI, no roles, no invitations.
+
+## Architecture
+
+**Android app** (Kotlin, Jetpack Compose, Material 3) talking to a
+**PocketBase** backend over HTTPS.
+
+```
+app/     Android Gradle project (org.modg.bookshelf)
+server/  PocketBase schema, provisioning scripts, deploy docs
+docs/    SPEC.md — the authoritative product/technical spec this was built from
+```
+
+### Offline-first, Room-backed
+
+Every screen reads from a local [Room](https://developer.android.com/training/data-storage/room)
+database, never directly from the network — the app has to be fully usable
+(browse, search, edit notes, move books between shelves) with the home
+server unreachable, which residential NAT/dynamic IP setups make a routine
+occurrence, not an edge case. Every write lands in Room first and is
+synced to the server later; nothing blocks on network I/O, and a sync
+failure surfaces as a quiet status line, never a crash or a blocking dialog.
+
+Deletion is always a soft tombstone (`deleted = true`), never a hard delete,
+on both the client and the server — so a delete on one phone propagates to
+the other on next sync instead of just disappearing from one copy.
+
+### Sync: push-then-pull, last-write-wins
+
+Each sync cycle (on app start, pull-to-refresh, and a ~6-hourly WorkManager
+job) does two passes, in this order:
+
+1. **Push** every locally-changed record (tracked via a `syncState` column:
+   `PENDING_CREATE` / `PENDING_UPDATE` / `PENDING_DELETE`) to PocketBase.
+   New records use a client-generated 15-character id, sent as-is on create —
+   PocketBase accepts client-supplied ids, so an id never has to be remapped
+   after the fact. A `PENDING_DELETE` is pushed as a `PATCH {deleted: true}`,
+   never an actual record delete.
+2. **Pull** everything changed on the server since the last-seen cursor
+   (`updated > cursor`, paginated to exhaustion), so the two devices'
+   changes reconcile in one direction after the local push.
+
+**Conflict rule: last-write-wins on the server's `updated` timestamp.**
+If both phones edit the same book while offline, whichever write reaches
+the server later simply overwrites the earlier one — there is no merge, no
+per-field reconciliation, and no conflict UI. This is a deliberate
+simplification for a two-person household doing infrequent concurrent edits,
+not a limitation either of you should expect to fight with day-to-day, but
+it does mean a same-book edit race can silently lose one side's change.
+
+Book covers get the same treatment as everything else: the app downloads
+the cover from the metadata source and re-uploads it to PocketBase's own
+`cover` file field, so the household's library doesn't rot when an external
+cover URL eventually 404s. If offline, the cover is queued locally and
+uploaded on the next sync.
+
+### Metadata lookup
+
+Scanning a barcode looks the ISBN up against
+[Open Library](https://openlibrary.org/dev/docs/api/books), falling back to
+[Google Books](https://developers.google.com/books) if Open Library has
+nothing. The two results are merged (prefer whichever has a title; fill in
+blanks from the other); if both come up empty, the app offers manual entry
+pre-filled with the scanned ISBN instead of a dead end.
+
+## Building
+
+Requirements: JDK 21, Android SDK (compileSdk/targetSdk 37, build-tools
+37.0.0). No emulator is required or used in this project's own verification —
+see "Current limitations" below.
+
+```sh
+cd app
+./gradlew assembleDebug        # debug APK
+./gradlew testDebugUnitTest    # JVM unit tests (Robolectric + Paparazzi)
+./gradlew recordPaparazziDebug # re-record screenshot goldens under src/test/snapshots
+./gradlew assembleRelease      # release APK — see "Signing" below
+```
+
+### Signing a release build
+
+`app/app/build.gradle.kts` reads signing credentials from
+`app/keystore.properties` (gitignored, alongside the `.jks` keystore it
+points at) if that file exists:
+
+```properties
+storeFile=release-keystore.jks
+storePassword=...
+keyAlias=bookshelf
+keyPassword=...
+```
+
+Without that file, `assembleRelease` still succeeds — the release build type
+simply comes out unsigned (debug-signed by AGP's defaults), so anyone who
+clones this repo can build and run it without needing the household's actual
+release key. Only the machine(s) that own `keystore.properties` produce an
+APK you'd actually want to install permanently (Android treats a
+signing-key change as a different app for update purposes, so hang on to
+that keystore).
+
+## Deploying the server
+
+See [`server/README.md`](server/README.md) for the schema and provisioning
+scripts, and [`server/deploy/`](server/deploy/) for running PocketBase
+long-term (systemd or Docker), reaching it from outside your home network
+(Tailscale is the recommended option — no ports opened on your router, no
+TLS cert management), and backups. In short:
+
+```sh
+cd server
+./setup-schema.sh http://127.0.0.1:8090 <superuser-email> <superuser-password>
+./create-user.sh you@example.com "a strong password" "Your Name"
+./create-user.sh partner@example.com "a different strong password" "Partner Name"
+```
+
+Enter the server's URL (must be `https://`, unless it's Tailscale-only —
+see the deploy README) on the app's first-run setup screen; it's never
+hardcoded into the build.
+
+## Installing the APK
+
+Build (or ask whoever holds the release keystore to build)
+`app/app/build/outputs/apk/release/app-release.apk`, copy it to the phone,
+and open it. Android will prompt to allow installs from that source the
+first time. There's no Play Store listing — this app is not, and was never
+meant to be, publicly distributed.
+
+## Current limitations
+
+Read this before assuming more polish than exists:
+
+- **The app has never run on a physical device or emulator.** This
+  environment has no KVM, so there is no Android emulator available.
+  Everything here was verified via `./gradlew assembleDebug`,
+  `testDebugUnitTest` (JVM/Robolectric unit tests), and Paparazzi screenshot
+  rendering (`src/test/snapshots/images/`) — real logic paths (ISBN
+  checksums, metadata merging, sync conflict resolution, DAO queries) are
+  unit-tested, and every screen has been rendered to a static PNG in both
+  light and dark theme, but nothing has been tap-tested on an actual screen.
+  Camera/barcode scanning in particular has only been exercised through unit
+  tests of the pure logic (`IsbnBarcodeAnalyzer`/`ScanCodeFilter`), never a
+  live camera.
+- **Sync has been round-tripped against a real PocketBase exactly once**
+  (a live-server test covering auth, push with client-generated ids, pull,
+  last-write-wins, tombstones, and a byte-for-byte cover round-trip — see
+  `server/live-sync-test.sh`). It has not been exercised over an actual flaky
+  residential connection, nor with two devices genuinely racing each other.
+- **Conflict resolution is last-write-wins with no merge and no UI** for it,
+  as described above — acceptable for this app's scale, but worth knowing
+  before relying on it under real concurrent edits.
+- **No Room foreign keys** between books/shelves/bookcases (a deliberate
+  simplification) — an orphaned `shelfId` on a book is handled in queries,
+  not prevented by the schema.
+- **No automated instrumented/UI tests** — only JVM unit tests and Paparazzi
+  screenshots. There is no CI pipeline in this repo.

app/.gitignore

@@ -10,3 +10,6 @@
 local.properties
 **/build/
 .kotlin/
+keystore.properties
+*.jks
+*.keystore

app/app/build.gradle.kts

@@ -1,3 +1,5 @@
+import java.util.Properties
+
 plugins {
     alias(libs.plugins.android.application)
     // NOTE: no org.jetbrains.kotlin.android plugin — AGP 9's Kotlin support is
@@ -8,6 +10,17 @@ plugins {
     alias(libs.plugins.paparazzi)
 }
 
+// Release signing is optional: `keystore.properties` (gitignored, alongside the
+// keystore it points at) only exists on machines that own the release key. Anyone
+// else still gets a working `assembleRelease` — it just comes out debug-signed.
+val keystorePropertiesFile = rootProject.file("keystore.properties")
+val keystoreProperties = Properties().apply {
+    if (keystorePropertiesFile.exists()) {
+        keystorePropertiesFile.inputStream().use { load(it) }
+    }
+}
+val hasReleaseKeystore = keystorePropertiesFile.exists()
+
 android {
     namespace = "org.modg.bookshelf"
     compileSdk = 37
@@ -23,10 +36,24 @@ android {
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
     }
 
+    signingConfigs {
+        if (hasReleaseKeystore) {
+            create("release") {
+                storeFile = rootProject.file(keystoreProperties["storeFile"] as String)
+                storePassword = keystoreProperties["storePassword"] as String
+                keyAlias = keystoreProperties["keyAlias"] as String
+                keyPassword = keystoreProperties["keyPassword"] as String
+            }
+        }
+    }
+
     buildTypes {
         release {
             isMinifyEnabled = false
             proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+            if (hasReleaseKeystore) {
+                signingConfig = signingConfigs.getByName("release")
+            }
         }
     }
 

app/app/src/main/AndroidManifest.xml

@@ -28,6 +28,7 @@
         <activity
             android:name=".MainActivity"
             android:exported="true"
+            android:windowSoftInputMode="adjustResize"
             android:theme="@style/Theme.Bookshelf">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />

app/app/src/main/java/org/modg/bookshelf/AppContainer.kt

@@ -1,6 +1,7 @@
 package org.modg.bookshelf
 
 import android.content.Context
+import java.util.concurrent.TimeUnit
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.sync.Mutex
@@ -86,11 +87,32 @@ class AppContainer(private val context: Context) {
 
     val authRepository by lazy { AuthRepository(apiProvider, settingsStore) }
 
-    // A bare client — deliberately NOT [okHttpClient] above, which carries our
+    // Deliberately NOT [okHttpClient] above, which carries our PocketBase bearer
-    // PocketBase bearer token via PbAuthInterceptor. Open Library/Google Books
+    // token via PbAuthInterceptor. Open Library/Google Books are third-party
-    // are third-party services; that token must never leave this device's
+    // services; that token must never leave this device's requests to our own
-    // requests to our own server.
+    // server. A call timeout is load-bearing here: with none, a stalled
-    private val metadataHttpClient: OkHttpClient by lazy { OkHttpClient() }
+    // connection hangs on OkHttp's default (unbounded) socket timeouts, and the
+    // user is standing at a bookshelf waiting on it.
+    //
+    // These were 12s/10s/10s and were MANUFACTURING failures. Measuring the exact
+    // Open Library call 30 times on 2026-09-09 (docs/METADATA-SOURCES.md) found
+    // successful requests with a median of 4.3s but a long tail — p90 9.2s, max
+    // 22.0s, and one connect phase alone of 19.6s. Two of 26 successes exceeded the
+    // old 12s call timeout, so ~8% of lookups that were about to work were being
+    // cancelled and reported to the user as "couldn't be reached".
+    //
+    // Raising these does NOT slow the failure path: every observed failure was a
+    // TLS-stage reset returning in under 2.5s, and a socket that is going to break
+    // breaks long before any of these limits. The timeouts only ever bound the
+    // slow-success tail, which is precisely what we want to stop truncating.
+    // 25s > the 22.0s worst observed success, with room to spare.
+    private val metadataHttpClient: OkHttpClient by lazy {
+        OkHttpClient.Builder()
+            .callTimeout(25, TimeUnit.SECONDS)
+            .connectTimeout(20, TimeUnit.SECONDS)
+            .readTimeout(20, TimeUnit.SECONDS)
+            .build()
+    }
 
     val metadataRepository by lazy { MetadataRepository(metadataHttpClient, json) }
 

app/app/src/main/java/org/modg/bookshelf/data/metadata/GoogleBooksClient.kt

@@ -10,7 +10,8 @@ import okhttp3.Request
 
 /**
  * Google Books lookup — SPEC.md "Book metadata lookup" fallback source. No API key.
- * Never throws: network/parse failures fail soft and return null.
+ * Never throws: every outcome, including transport failure, comes back as a
+ * [SourceResult] rather than a swallowed null.
  */
 class GoogleBooksClient(
     private val httpClient: OkHttpClient,
@@ -18,29 +19,51 @@ class GoogleBooksClient(
 ) {
     private val json = Json(from = json) { ignoreUnknownKeys = true }
 
-    suspend fun lookup(isbn13: String): BookMetadata? = withContext(Dispatchers.IO) {
+    /**
-        val body = fetchBody(isbn13) ?: return@withContext null
+     * Retries transient failures per [RetryPolicy]. Note this source's standing
-        parseResponse(body)
+     * failure — keyless requests share one exhausted global quota and answer 429,
-    }
+     * which [RetryPolicy] deliberately does NOT retry, so today this costs nothing
+     * and changes nothing here. See docs/METADATA-SOURCES.md.
+     */
+    suspend fun lookup(isbn13: String): SourceResult =
+        withContext(Dispatchers.IO) { withRetry { fetch(isbn13) } }
 
-    private fun fetchBody(isbn13: String): String? = try {
+    /** Single un-retried attempt, for tests that need to count calls. */
+    internal suspend fun lookupOnce(isbn13: String): SourceResult =
+        withContext(Dispatchers.IO) { fetch(isbn13) }
+
+    private fun fetch(isbn13: String): SourceResult = try {
         val request = Request.Builder()
             .url("https://www.googleapis.com/books/v1/volumes?q=isbn:$isbn13")
             .build()
         httpClient.newCall(request).execute().use { response ->
-            if (!response.isSuccessful) null else response.body?.string()
+            classify(response.code, response.body.string())
         }
     } catch (e: IOException) {
-        null
+        SourceResult.fromException(e)
+    }
+
+    /**
+     * Package-visible pure function — no socket involved — so it's exhaustively
+     * unit-testable offline (2xx-with-record, 2xx-without-record, 404, 429, 500,
+     * malformed body). [parseResponse] is defined in terms of this so the two
+     * can never disagree about what a body means.
+     */
+    internal fun classify(httpCode: Int, body: String?): SourceResult {
+        if (httpCode !in 200..299) return SourceResult.fromHttpCode(httpCode)
+        if (body.isNullOrBlank()) return SourceResult.Failed("empty body", FailureKind.MALFORMED)
+        return try {
+            val dto = json.decodeFromString(GoogleBooksResponseDto.serializer(), body)
+            val metadata = dto.items.firstOrNull()?.volumeInfo?.toBookMetadata()
+            if (metadata != null) SourceResult.Found(metadata) else SourceResult.NotFound
+        } catch (e: SerializationException) {
+            SourceResult.Failed("malformed json", FailureKind.MALFORMED)
+        } catch (e: IllegalArgumentException) {
+            SourceResult.Failed("malformed json", FailureKind.MALFORMED)
+        }
     }
 
     /** Package-visible for offline fixture tests — parses a raw response body with no network involved. */
-    internal fun parseResponse(body: String): BookMetadata? = try {
+    internal fun parseResponse(body: String): BookMetadata? =
-        val dto = json.decodeFromString(GoogleBooksResponseDto.serializer(), body)
+        (classify(200, body) as? SourceResult.Found)?.metadata
-        dto.items.firstOrNull()?.volumeInfo?.toBookMetadata()
-    } catch (e: SerializationException) {
-        null
-    } catch (e: IllegalArgumentException) {
-        null
-    }
 }

app/app/src/main/java/org/modg/bookshelf/data/metadata/LookupResult.kt

@@ -0,0 +1,18 @@
+package org.modg.bookshelf.data.metadata
+
+/**
+ * The combined outcome of a metadata lookup across both sources (SPEC.md "Book
+ * metadata lookup"). Produced by [MetadataRepository.lookup] from the two
+ * [SourceResult]s per [MetadataRepository.combine]'s rules:
+ *   - any source [SourceResult.Found]                     -> [Found]
+ *   - every source [SourceResult.NotFound]                 -> [NotFound]
+ *   - otherwise (at least one [SourceResult.Failed], none Found) -> [Unavailable]
+ *
+ * The last rule is the whole point: one reachable source answering "no" is not
+ * authoritative while the other source couldn't be asked at all.
+ */
+sealed interface LookupResult {
+    data class Found(val metadata: BookMetadata) : LookupResult
+    data object NotFound : LookupResult
+    data class Unavailable(val reason: String) : LookupResult
+}

app/app/src/main/java/org/modg/bookshelf/data/metadata/MetadataRepository.kt

@@ -7,9 +7,10 @@ import okhttp3.OkHttpClient
 
 /**
  * Single entry point for book metadata lookup (SPEC.md "Book metadata lookup").
- * Queries both sources concurrently and merges per [MetadataMerger]. Returns null
+ * Queries both sources concurrently and combines their [SourceResult]s into one
- * if [isbn] doesn't checksum-validate or if both sources miss — callers (the scan
+ * [LookupResult] per [combine]. [isbn] must already be a checksum-valid ISBN-10/13
- * screen) must then fall back to manual entry pre-filled with the scanned ISBN.
+ * by the time it reaches here — the scan layer is responsible for that, and an
+ * invalid one is a programming error at this layer, not a lookup outcome.
  */
 class MetadataRepository(
     private val openLibraryClient: OpenLibraryClient,
@@ -20,12 +21,55 @@ class MetadataRepository(
         GoogleBooksClient(httpClient, json),
     )
 
-    suspend fun lookup(isbn: String): BookMetadata? {
+    suspend fun lookup(isbn: String): LookupResult {
-        val isbn13 = IsbnUtils.toIsbn13(isbn) ?: return null
+        val isbn13 = checkNotNull(IsbnUtils.toIsbn13(isbn)) {
+            "MetadataRepository.lookup requires an already-validated ISBN-10/13; got: $isbn"
+        }
         return coroutineScope {
             val openLibrary = async { openLibraryClient.lookup(isbn13) }
             val googleBooks = async { googleBooksClient.lookup(isbn13) }
-            MetadataMerger.merge(openLibrary.await(), googleBooks.await())
+            combine(openLibrary.await(), googleBooks.await(), isbn13)
         }
     }
+
+    companion object {
+        /**
+         * Combines the two sources' outcomes per SPEC.md's three-way rule: any Found
+         * wins (merged via [MetadataMerger] and given the last-resort cover), all
+         * NotFound is an honest miss, and anything else — at least one Failed and
+         * nothing Found — is Unavailable, because a source that couldn't be reached
+         * must never be reported as a book that doesn't exist. Package-visible and
+         * pure (no I/O) so the full 3x3 matrix is unit-testable offline.
+         */
+        internal fun combine(openLibrary: SourceResult, googleBooks: SourceResult, isbn13: String): LookupResult {
+            val merged = MetadataMerger.merge(
+                (openLibrary as? SourceResult.Found)?.metadata,
+                (googleBooks as? SourceResult.Found)?.metadata,
+            )
+            if (merged != null) {
+                val withCover = if (merged.coverUrl.isNullOrBlank()) {
+                    merged.copy(coverUrl = byIsbnCoverUrl(isbn13))
+                } else {
+                    merged
+                }
+                return LookupResult.Found(withCover)
+            }
+            val failures = listOfNotNull(
+                (openLibrary as? SourceResult.Failed)?.reason?.let { "open library: $it" },
+                (googleBooks as? SourceResult.Failed)?.reason?.let { "google books: $it" },
+            )
+            return if (failures.isNotEmpty()) LookupResult.Unavailable(failures.joinToString("; ")) else LookupResult.NotFound
+        }
+
+        /**
+         * Last resort when neither source reported cover art, per SPEC's cover chain.
+         * `default=false` is load-bearing: without it this endpoint answers 200 with a
+         * 1x1 transparent GIF for editions it has no art for, which an image loader
+         * treats as a successful load and paints as an invisible cover. With it, a
+         * miss is a 404, so [org.modg.bookshelf.ui.components.BookCover] can fall back
+         * to its placeholder.
+         */
+        fun byIsbnCoverUrl(isbn13: String): String =
+            "https://covers.openlibrary.org/b/isbn/$isbn13-L.jpg?default=false"
+    }
 }

app/app/src/main/java/org/modg/bookshelf/data/metadata/OpenLibraryClient.kt

@@ -12,7 +12,8 @@ import okhttp3.Request
 
 /**
  * Open Library lookup — SPEC.md "Book metadata lookup" primary source.
- * Never throws: network/parse failures fail soft and return null.
+ * Never throws: every outcome, including transport failure, comes back as a
+ * [SourceResult] rather than a swallowed null.
  */
 class OpenLibraryClient(
     private val httpClient: OkHttpClient,
@@ -21,30 +22,50 @@ class OpenLibraryClient(
     // Real responses carry fields this DTO doesn't model; never let an unknown key throw.
     private val json = Json(from = json) { ignoreUnknownKeys = true }
 
-    suspend fun lookup(isbn13: String): BookMetadata? = withContext(Dispatchers.IO) {
+    /**
-        val body = fetchBody(isbn13) ?: return@withContext null
+     * Retries transient failures per [RetryPolicy]. Measured against the live API,
-        parseResponse(body, isbn13)
+     * 13% of requests fail at the TLS stage in well under a second while successful
-    }
+     * ones take seconds — so a retry is nearly free and removes most of that 13%.
+     */
+    suspend fun lookup(isbn13: String): SourceResult =
+        withContext(Dispatchers.IO) { withRetry { fetch(isbn13) } }
 
-    private fun fetchBody(isbn13: String): String? = try {
+    /** Single un-retried attempt, for tests that need to count calls. */
+    internal suspend fun lookupOnce(isbn13: String): SourceResult =
+        withContext(Dispatchers.IO) { fetch(isbn13) }
+
+    private fun fetch(isbn13: String): SourceResult = try {
         val request = Request.Builder()
             .url("https://openlibrary.org/api/books?bibkeys=ISBN:$isbn13&format=json&jscmd=data")
             .build()
         httpClient.newCall(request).execute().use { response ->
-            if (!response.isSuccessful) null else response.body?.string()
+            classify(response.code, response.body.string(), isbn13)
         }
     } catch (e: IOException) {
-        null
+        SourceResult.fromException(e)
+    }
+
+    /**
+     * Package-visible pure function — no socket involved — so it's exhaustively
+     * unit-testable offline (2xx-with-record, 2xx-without-record, 404, 429, 500,
+     * malformed body). [parseResponse] is defined in terms of this so the two
+     * can never disagree about what a body means.
+     */
+    internal fun classify(httpCode: Int, body: String?, isbn13: String): SourceResult {
+        if (httpCode !in 200..299) return SourceResult.fromHttpCode(httpCode)
+        if (body.isNullOrBlank()) return SourceResult.Failed("empty body", FailureKind.MALFORMED)
+        return try {
+            val root = json.parseToJsonElement(body).jsonObject
+            val entry = root["ISBN:$isbn13"]?.jsonObject ?: return SourceResult.NotFound
+            SourceResult.Found(json.decodeFromJsonElement<OpenLibraryBookDto>(entry).toBookMetadata(isbn13))
+        } catch (e: SerializationException) {
+            SourceResult.Failed("malformed json", FailureKind.MALFORMED)
+        } catch (e: IllegalArgumentException) {
+            SourceResult.Failed("malformed json", FailureKind.MALFORMED)
+        }
     }
 
     /** Package-visible for offline fixture tests — parses a raw response body with no network involved. */
-    internal fun parseResponse(body: String, isbn13: String): BookMetadata? = try {
+    internal fun parseResponse(body: String, isbn13: String): BookMetadata? =
-        val root = json.parseToJsonElement(body).jsonObject
+        (classify(200, body, isbn13) as? SourceResult.Found)?.metadata
-        val entry = root["ISBN:$isbn13"]?.jsonObject ?: return null
-        json.decodeFromJsonElement<OpenLibraryBookDto>(entry).toBookMetadata(isbn13)
-    } catch (e: SerializationException) {
-        null
-    } catch (e: IllegalArgumentException) {
-        null
-    }
 }

app/app/src/main/java/org/modg/bookshelf/data/metadata/OpenLibraryDtos.kt

@@ -18,6 +18,7 @@ data class OpenLibraryBookDto(
     @SerialName("publish_date") val publishDate: String? = null,
     @SerialName("number_of_pages") val numberOfPages: Int? = null,
     val identifiers: OpenLibraryIdentifiersDto? = null,
+    val cover: OpenLibraryCoverDto? = null,
 )
 
 @Serializable
@@ -26,13 +27,33 @@ data class OpenLibraryAuthorDto(val name: String? = null)
 @Serializable
 data class OpenLibraryPublisherDto(val name: String? = null)
 
+/**
+ * Present only when Open Library actually holds cover art for the edition, and so
+ * the only trustworthy "has a cover" signal from this API. A synthesized by-ISBN
+ * covers.openlibrary.org URL is NOT evidence of one: for an edition with no art it
+ * answers 200 with a 43-byte 1x1 transparent GIF (verified 2026-09-09), which any
+ * image loader reports as a successful load — the cover then renders as nothing at
+ * all and no error placeholder ever fires. Only `?default=false` turns that into a
+ * 404; see [MetadataRepository] for the last-resort URL that uses it.
+ */
+@Serializable
+data class OpenLibraryCoverDto(
+    val small: String? = null,
+    val medium: String? = null,
+    val large: String? = null,
+)
+
 @Serializable
 data class OpenLibraryIdentifiersDto(
     @SerialName("isbn_10") val isbn10: List<String> = emptyList(),
     @SerialName("isbn_13") val isbn13: List<String> = emptyList(),
 )
 
-/** Maps the OL DTO to the source-agnostic [BookMetadata], deriving the cover URL per SPEC. */
+/**
+ * Maps the OL DTO to the source-agnostic [BookMetadata]. [coverUrl] stays null unless
+ * OL reports real cover art, so that the SPEC merge rule can fall through to Google
+ * Books' thumbnail instead of pinning a URL that resolves to a blank image.
+ */
 fun OpenLibraryBookDto.toBookMetadata(lookupIsbn13: String): BookMetadata = BookMetadata(
     isbn13 = identifiers?.isbn13?.firstOrNull() ?: lookupIsbn13,
     isbn10 = identifiers?.isbn10?.firstOrNull(),
@@ -43,5 +64,5 @@ fun OpenLibraryBookDto.toBookMetadata(lookupIsbn13: String): BookMetadata = Book
     publishedDate = publishDate,
     pageCount = numberOfPages,
     description = null,
-    coverUrl = "https://covers.openlibrary.org/b/isbn/$lookupIsbn13-L.jpg",
+    coverUrl = cover?.large?.takeIf { it.isNotBlank() } ?: cover?.medium?.takeIf { it.isNotBlank() },
 )

app/app/src/main/java/org/modg/bookshelf/data/metadata/RetryPolicy.kt

@@ -0,0 +1,110 @@
+package org.modg.bookshelf.data.metadata
+
+import kotlin.random.Random
+import kotlinx.coroutines.delay
+
+/**
+ * When a failed lookup attempt is worth repeating, and how long to wait first.
+ *
+ * Grounded in a measurement of the live Open Library API from 2026-09-09 — 30
+ * requests, the exact call [OpenLibraryClient] makes (see docs/METADATA-SOURCES.md):
+ *
+ *   - 13% of requests failed, every one of them a TLS-stage connection reset.
+ *   - Failures were FAST: 0.23s, 0.31s, 0.59s, 2.46s.
+ *   - Successes were SLOW and long-tailed: median 4.3s, p90 9.2s, max 22.0s.
+ *
+ * That asymmetry drives every constant here. A retry costs roughly a fifth of a
+ * second of the user's time and turns a 13% failure rate into ~1.7% at two
+ * attempts and ~0.2% at three, which is why the backoff is short rather than the
+ * conventional exponential-with-seconds. It is also why [isRetryable] refuses to
+ * repeat a [FailureKind.TIMEOUT]: a timeout means we already spent the full budget
+ * on that attempt, so repeating it risks tripling the wait for a user standing at
+ * a bookshelf, and the measurement says slow requests usually eventually succeed
+ * rather than fail — the fix for those is a generous timeout, not another attempt.
+ */
+object RetryPolicy {
+
+    /** One original attempt plus two retries. Beyond this the marginal gain is noise. */
+    const val MAX_ATTEMPTS = 3
+
+    /**
+     * Stop starting NEW attempts once this much time has gone into a single source.
+     * A backstop against pathological cases (every attempt hitting the slow tail),
+     * not a normal-path limit. It is deliberately checked only BETWEEN attempts —
+     * an in-flight request is never cancelled, because the 22-second request in the
+     * sample was a successful one and killing it would manufacture exactly the
+     * failure this whole change exists to remove.
+     */
+    const val TOTAL_BUDGET_MILLIS = 30_000L
+
+    /**
+     * [FailureKind.TRANSPORT] and [FailureKind.SERVER_ERROR] are transient and
+     * cheap to re-ask. The rest are not:
+     *  - TIMEOUT      — the budget is already spent; see the class KDoc.
+     *  - RATE_LIMITED — the source is explicitly asking us to stop. Hammering a
+     *                   quota is how an intermittent block becomes a permanent one,
+     *                   and METADATA-SOURCES.md records that happening to this
+     *                   project's IP during research. When the Google Books API key
+     *                   lands, revisit this: a keyed 429 is a per-second rate limit
+     *                   and IS worth one Retry-After-respecting retry, unlike
+     *                   today's keyless daily-quota 429, which never clears.
+     *  - CLIENT_ERROR — an identical request gets an identical answer.
+     *  - MALFORMED    — same bytes, same parse failure.
+     */
+    fun isRetryable(kind: FailureKind): Boolean =
+        kind == FailureKind.TRANSPORT || kind == FailureKind.SERVER_ERROR
+
+    /**
+     * Backoff before attempt number [nextAttempt] (2-based: the wait before the
+     * first retry is `backoffMillis(2)`). 250ms then 750ms, plus up to 40% jitter
+     * so that two sources — or two phones in the same house — cannot fall into
+     * lockstep and hammer a recovering server in unison.
+     */
+    fun backoffMillis(nextAttempt: Int, random: Random = Random.Default): Long {
+        val base = when (nextAttempt) {
+            2 -> 250L
+            else -> 750L
+        }
+        return base + random.nextLong(0, (base * 0.4).toLong().coerceAtLeast(1))
+    }
+}
+
+/**
+ * Runs [attempt] until it succeeds, fails un-retryably, or runs out of attempts or
+ * budget. Returns the LAST result, so the caller always sees a real outcome rather
+ * than a synthesised one.
+ *
+ * A [SourceResult.Failed] that survives retrying has its attempt count appended to
+ * [SourceResult.Failed.reason] ("tls connection reset, 3 attempts"). That string is
+ * shown to the user on the scan sheet and is the only diagnostic we get back from a
+ * real phone — "failed once" and "failed three times in a row" are very different
+ * stories about the network, and without this they are indistinguishable.
+ *
+ * [sleep] and [nowMillis] are injectable purely so tests can run the real policy
+ * with no wall-clock delay; production callers use the defaults.
+ */
+suspend fun withRetry(
+    maxAttempts: Int = RetryPolicy.MAX_ATTEMPTS,
+    budgetMillis: Long = RetryPolicy.TOTAL_BUDGET_MILLIS,
+    random: Random = Random.Default,
+    nowMillis: () -> Long = { System.currentTimeMillis() },
+    sleep: suspend (Long) -> Unit = { delay(it) },
+    attempt: suspend () -> SourceResult,
+): SourceResult {
+    val started = nowMillis()
+    var last: SourceResult = attempt()
+    var attemptsMade = 1
+
+    while (attemptsMade < maxAttempts) {
+        val failure = last as? SourceResult.Failed ?: return last
+        if (!RetryPolicy.isRetryable(failure.kind)) break
+        if (nowMillis() - started >= budgetMillis) break
+
+        sleep(RetryPolicy.backoffMillis(attemptsMade + 1, random))
+        last = attempt()
+        attemptsMade++
+    }
+
+    val failure = last as? SourceResult.Failed ?: return last
+    return if (attemptsMade > 1) failure.copy(reason = "${failure.reason}, $attemptsMade attempts") else failure
+}

app/app/src/main/java/org/modg/bookshelf/data/metadata/SourceResult.kt

@@ -0,0 +1,101 @@
+package org.modg.bookshelf.data.metadata
+
+import java.io.IOException
+import java.io.InterruptedIOException
+import java.net.ConnectException
+import java.net.SocketException
+import java.net.SocketTimeoutException
+import java.net.UnknownHostException
+import javax.net.ssl.SSLException
+import javax.net.ssl.SSLHandshakeException
+
+/**
+ * Why a source failed, in the only terms that matter to a caller: is it worth
+ * asking again? [RetryPolicy] is the single place that decides, so the answer
+ * cannot drift between the two clients.
+ */
+enum class FailureKind {
+    /** Never got an answer: DNS, refused connection, reset socket, failed TLS handshake. */
+    TRANSPORT,
+
+    /** We gave up waiting. Distinct from [TRANSPORT] because the budget is already spent. */
+    TIMEOUT,
+
+    /** HTTP 429. The source is telling us to stop asking; asking harder is the wrong move. */
+    RATE_LIMITED,
+
+    /** HTTP 5xx — the source's problem, and usually a passing one. */
+    SERVER_ERROR,
+
+    /** HTTP 4xx other than 429. Repeating an identical request cannot change the answer. */
+    CLIENT_ERROR,
+
+    /** 2xx whose body we could not parse. Deterministic: the same bytes will fail again. */
+    MALFORMED,
+}
+
+/**
+ * Per-source lookup outcome (SPEC.md "Book metadata lookup": "Lookup outcome is
+ * THREE-WAY, never a bare null"). [OpenLibraryClient] and [GoogleBooksClient] each
+ * produce one of these instead of collapsing "couldn't be reached" and "answered,
+ * doesn't have it" into the same `null`. [MetadataRepository] combines the two
+ * source results into a [LookupResult].
+ */
+sealed interface SourceResult {
+    data class Found(val metadata: BookMetadata) : SourceResult
+
+    /** The source answered (2xx) and, in good faith, has no record for this ISBN. */
+    data object NotFound : SourceResult
+
+    /**
+     * The source could not be asked, or its answer couldn't be trusted. [reason] is
+     * a short diagnostic ("http 429", "tls reset", "malformed json") that is shown
+     * to the user as supplementary detail on the scan sheet and is our ONLY
+     * diagnostic channel from a real phone — so it names the specific failure, not
+     * a generic one. [kind] is the same fact in a form [RetryPolicy] can act on;
+     * nothing should ever parse [reason] to recover it.
+     */
+    data class Failed(val reason: String, val kind: FailureKind = FailureKind.TRANSPORT) : SourceResult
+
+    companion object {
+        /**
+         * Maps a thrown [IOException] to a specific failure. Both clients call this
+         * so they can never disagree, and so a new exception type gets classified
+         * once rather than twice.
+         *
+         * Measured against the live Open Library API on 2026-09-09 (30 requests):
+         * every observed failure was a TLS-stage `Connection reset by peer`, and all
+         * four came back in under 2.5s while successful requests took a median of
+         * 4.3s. Failures are cheap and fast; that asymmetry is the whole reason
+         * retrying is worth doing, and why the timeouts are set as generously as
+         * they are in `AppContainer.metadataHttpClient`.
+         *
+         * Order matters: [SocketTimeoutException] is an [InterruptedIOException] and
+         * [SSLHandshakeException] is an [SSLException], so the specific arms come
+         * first. OkHttp reports a blown `callTimeout` as a bare
+         * [InterruptedIOException], which is why that arm exists at all.
+         */
+        fun fromException(e: IOException): Failed = when (e) {
+            is SocketTimeoutException -> Failed("timeout", FailureKind.TIMEOUT)
+            is InterruptedIOException -> Failed("timeout", FailureKind.TIMEOUT)
+            is UnknownHostException -> Failed("dns lookup failed", FailureKind.TRANSPORT)
+            is SSLHandshakeException -> Failed("tls handshake failed", FailureKind.TRANSPORT)
+            is SSLException -> Failed("tls connection reset", FailureKind.TRANSPORT)
+            is ConnectException -> Failed("connection refused", FailureKind.TRANSPORT)
+            is SocketException -> Failed("connection reset", FailureKind.TRANSPORT)
+            else -> Failed("network error (${e.javaClass.simpleName})", FailureKind.TRANSPORT)
+        }
+
+        /**
+         * Maps a non-2xx HTTP status to a specific failure. 429 is called out
+         * separately from the rest of 4xx because it is the one client error that is
+         * about us rather than about the request, and because it is currently
+         * Google Books' permanent state — see docs/METADATA-SOURCES.md.
+         */
+        fun fromHttpCode(code: Int): Failed = when {
+            code == 429 -> Failed("http 429 (rate limited)", FailureKind.RATE_LIMITED)
+            code in 500..599 -> Failed("http $code (server error)", FailureKind.SERVER_ERROR)
+            else -> Failed("http $code", FailureKind.CLIENT_ERROR)
+        }
+    }
+}

app/app/src/main/java/org/modg/bookshelf/data/prefs/SettingsStore.kt

@@ -24,15 +24,25 @@ class SettingsStore(private val context: Context) {
         val SERVER_URL = stringPreferencesKey("server_url")
         val AUTH_TOKEN = stringPreferencesKey("auth_token")
         val USER_ID = stringPreferencesKey("user_id")
+        val USER_EMAIL = stringPreferencesKey("user_email")
         val LAST_SYNC_TIME = longPreferencesKey("last_sync_time")
+        val LAST_SHELF_ID = stringPreferencesKey("last_shelf_id")
         fun cursor(collection: String) = stringPreferencesKey("cursor_$collection")
     }
 
     val serverUrl: Flow<String?> = context.dataStore.data.map { it[Keys.SERVER_URL] }
     val authToken: Flow<String?> = context.dataStore.data.map { it[Keys.AUTH_TOKEN] }
     val userId: Flow<String?> = context.dataStore.data.map { it[Keys.USER_ID] }
+    val userEmail: Flow<String?> = context.dataStore.data.map { it[Keys.USER_EMAIL] }
     val lastSyncTime: Flow<Long?> = context.dataStore.data.map { it[Keys.LAST_SYNC_TIME] }
 
+    /**
+     * The shelf most recently assigned to a book — SPEC "remember the most recently
+     * used shelf" (shelving a box of books usually means one shelf, over and over).
+     * Never written for "Not shelved"; see [SettingsStore] callers.
+     */
+    val lastShelfId: Flow<String?> = context.dataStore.data.map { it[Keys.LAST_SHELF_ID] }
+
     fun cursorFor(collection: String): Flow<String?> =
         context.dataStore.data.map { it[Keys.cursor(collection)] }
 
@@ -48,6 +58,10 @@ class SettingsStore(private val context: Context) {
         context.dataStore.edit { it[Keys.USER_ID] = userId }
     }
 
+    suspend fun setUserEmail(email: String) {
+        context.dataStore.edit { it[Keys.USER_EMAIL] = email }
+    }
+
     suspend fun setCursor(collection: String, cursor: String) {
         context.dataStore.edit { it[Keys.cursor(collection)] = cursor }
     }
@@ -56,11 +70,25 @@ class SettingsStore(private val context: Context) {
         context.dataStore.edit { it[Keys.LAST_SYNC_TIME] = epochMillis }
     }
 
-    /** Sign out: drop the token/user identity but keep the server URL — no need to re-enter it. */
+    suspend fun setLastShelfId(shelfId: String) {
+        context.dataStore.edit { it[Keys.LAST_SHELF_ID] = shelfId }
+    }
+
+    suspend fun clearLastShelfId() {
+        context.dataStore.edit { it.remove(Keys.LAST_SHELF_ID) }
+    }
+
+    /**
+     * Sign out: drop the token/user identity but keep the server URL — no need to
+     * re-enter it. Also drops the remembered shelf: a shared library's other
+     * account shouldn't have its shelving habit leak into this one's session.
+     */
     suspend fun clearAuth() {
         context.dataStore.edit {
             it.remove(Keys.AUTH_TOKEN)
             it.remove(Keys.USER_ID)
+            it.remove(Keys.USER_EMAIL)
+            it.remove(Keys.LAST_SHELF_ID)
         }
     }
 

app/app/src/main/java/org/modg/bookshelf/data/repo/AuthRepository.kt

@@ -35,6 +35,7 @@ class AuthRepository(
             val response = api.authWithPassword(AuthWithPasswordRequest(identity = email, password = password))
             settingsStore.setAuthToken(response.token)
             settingsStore.setUserId(response.record.id)
+            settingsStore.setUserEmail(email)
             Result.success(Unit)
         } catch (e: Exception) {
             Result.failure(e)

app/app/src/main/java/org/modg/bookshelf/ui/components/BookCover.kt

@@ -3,15 +3,20 @@ package org.modg.bookshelf.ui.components
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxHeight
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.outlined.AutoStories
 import androidx.compose.material.icons.outlined.BrokenImage
 import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
@@ -27,9 +32,12 @@ const val BookCoverAspectRatio = 2f / 3f
 /**
  * A book cover image, always drawn at [BookCoverAspectRatio]. Covers are the
  * hero of this app's design — real art fills the whole shape edge to edge.
- * When there's no [coverUrl], or the load fails, we fall back to the same
+ * When there's no [coverUrl], or the load fails, or one is still in flight, we
- * restrained "letterpress" placeholder: a paper-toned panel with a debossed
+ * fall back to the same restrained "letterpress" placeholder: a paper-toned panel
- * spine motif rather than a broken-image icon or empty grey box.
+ * with a debossed spine motif rather than a broken-image icon or empty grey box.
+ * The placeholder is drawn in EVERY non-success state on purpose — a cover slot
+ * that renders nothing at all leaves the title floating in blank space, which is
+ * exactly what a transparent 1x1 stand-in cover used to produce.
  */
 @Composable
 fun BookCover(
@@ -52,11 +60,16 @@ fun BookCover(
                 modifier = Modifier.fillMaxSize(),
                 contentScale = ContentScale.Crop,
             ) {
-                when (painter.state) {
+                // painter.state is a StateFlow<State>, NOT a State. Branching on it
+                // directly compiles (a `when` used as a statement needs no else) but
+                // every branch is always false, so the slot draws nothing at all —
+                // no cover and no placeholder. Collect it before matching.
+                val state by painter.state.collectAsState()
+                when (state) {
                     is AsyncImagePainter.State.Error -> CoverPlaceholder(errored = true)
                     is AsyncImagePainter.State.Loading,
                     is AsyncImagePainter.State.Empty,
-                        -> CoverPlaceholder(errored = false, loading = true)
+                        -> CoverPlaceholder(errored = false)
                     is AsyncImagePainter.State.Success -> SubcomposeAsyncImageContent()
                 }
             }
@@ -65,25 +78,39 @@ fun BookCover(
 }
 
 @Composable
-private fun CoverPlaceholder(errored: Boolean, loading: Boolean = false) {
+private fun CoverPlaceholder(errored: Boolean) {
     val paperAlt = MaterialTheme.colorScheme.surfaceVariant
     val ink = MaterialTheme.colorScheme.onSurfaceVariant
+    val spine = MaterialTheme.colorScheme.primary
+    val gold = MaterialTheme.colorScheme.secondary
     Box(
         modifier = Modifier
             .fillMaxSize()
             .background(paperAlt)
-            .border(width = 1.dp, color = ink.copy(alpha = 0.15f))
+            .border(width = 1.dp, color = ink.copy(alpha = 0.22f)),
-            .padding(2.dp)
-            .border(width = 1.dp, color = ink.copy(alpha = 0.1f)),
         contentAlignment = Alignment.Center,
     ) {
-        if (!loading) {
+        // A bound: a mahogany spine strip down the left edge with a gold hairline
-            Icon(
+        // beside it. This is what makes an art-less cover still read as a book.
-                imageVector = if (errored) Icons.Outlined.BrokenImage else Icons.Outlined.AutoStories,
+        Row(modifier = Modifier.fillMaxSize()) {
-                contentDescription = null,
+            Box(
-                tint = ink.copy(alpha = if (errored) 0.35f else 0.28f),
+                modifier = Modifier
-                modifier = Modifier.fillMaxSize(0.32f),
+                    .fillMaxHeight()
+                    .width(10.dp)
+                    .background(spine.copy(alpha = 0.35f)),
+            )
+            Box(
+                modifier = Modifier
+                    .fillMaxHeight()
+                    .width(1.dp)
+                    .background(gold.copy(alpha = 0.55f)),
             )
         }
+        Icon(
+            imageVector = if (errored) Icons.Outlined.BrokenImage else Icons.Outlined.AutoStories,
+            contentDescription = null,
+            tint = ink.copy(alpha = 0.4f),
+            modifier = Modifier.fillMaxSize(0.3f),
+        )
     }
 }

app/app/src/main/java/org/modg/bookshelf/ui/components/BookshelfScaffold.kt

@@ -2,7 +2,6 @@ package org.modg.bookshelf.ui.components
 
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.PaddingValues
-import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.material3.CenterAlignedTopAppBar
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.FloatingActionButton
@@ -18,6 +17,12 @@ import androidx.compose.ui.Modifier
  * screen title and a gold hairline rule underneath, plus optional nav/action
  * slots, FAB, and a bottom [SyncStatusBar] slot. Screens should reach for
  * this instead of a bare [Scaffold] so the chrome stays consistent.
+ *
+ * [syncStatusBar] goes in the Scaffold's own bottom-bar slot rather than in a
+ * hand-rolled Column under the content: that is what makes the height it
+ * occupies show up in the [PaddingValues] handed to [content], so a screen that
+ * applies them can't scroll its last row underneath the status line. The bar
+ * takes the navigation-bar inset itself (see [SyncStatusBar]).
  */
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
@@ -49,14 +54,8 @@ fun BookshelfScaffold(
             }
         },
         floatingActionButton = floatingActionButton,
+        bottomBar = syncStatusBar,
         containerColor = MaterialTheme.colorScheme.surface,
-        content = { innerPadding ->
+        content = content,
-            Column(modifier = Modifier.fillMaxSize()) {
-                Column(modifier = Modifier.weight(1f)) {
-                    content(innerPadding)
-                }
-                syncStatusBar()
-            }
-        },
     )
 }

app/app/src/main/java/org/modg/bookshelf/ui/components/ShelfPickerSheet.kt

@@ -0,0 +1,180 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.outlined.Check
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.ModalBottomSheet
+import androidx.compose.material3.Text
+import androidx.compose.material3.rememberModalBottomSheetState
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.font.FontStyle
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import org.modg.bookshelf.data.local.BookcaseEntity
+import org.modg.bookshelf.data.local.ShelfEntity
+
+/**
+ * The grouped shelf picker shared by the scan screen's save sheet and the
+ * detail screen's location picker. Replaces the old flat "Bookcase • Shelf"
+ * [androidx.compose.material3.DropdownMenu] — which stopped being usable once
+ * a library had more than a couple of bookcases — with a scrolling
+ * [ModalBottomSheet] grouped one section per bookcase. A bookcase is not
+ * itself a place a book can sit, so its header is a non-selectable label;
+ * only the shelves listed under it are choices.
+ */
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun ShelfPickerSheet(
+    bookcases: List<BookcaseEntity>,
+    shelves: List<ShelfEntity>,
+    selectedShelfId: String?,
+    recentShelfId: String?,
+    onShelfSelected: (String?) -> Unit,
+    onDismissRequest: () -> Unit,
+) {
+    ModalBottomSheet(onDismissRequest = onDismissRequest, sheetState = rememberModalBottomSheetState()) {
+        ShelfPickerContent(
+            bookcases = bookcases,
+            shelves = shelves,
+            selectedShelfId = selectedShelfId,
+            recentShelfId = recentShelfId,
+            onShelfSelected = { shelfId ->
+                onShelfSelected(shelfId)
+                onDismissRequest()
+            },
+        )
+    }
+}
+
+/**
+ * The picker's contents, split out from [ShelfPickerSheet] so it can be rendered
+ * directly (Paparazzi has no real Window/scrim behind a headless [ModalBottomSheet],
+ * same problem [org.modg.bookshelf.ui.screens.ScanScreenPaparazziTest]'s class doc
+ * describes for the camera preview). Internal rather than private so that test can
+ * reach it.
+ */
+@Composable
+internal fun ShelfPickerContent(
+    bookcases: List<BookcaseEntity>,
+    shelves: List<ShelfEntity>,
+    selectedShelfId: String?,
+    recentShelfId: String?,
+    onShelfSelected: (String?) -> Unit,
+) {
+    val recent = resolveRecentShelf(recentShelfId, shelves, bookcases)
+    val recentShelf = recent?.first
+    val recentBookcase = recent?.second
+
+    Column(
+        modifier = Modifier
+            .fillMaxWidth()
+            .verticalScroll(rememberScrollState())
+            .padding(horizontal = 16.dp, vertical = 8.dp),
+    ) {
+        // Omitted entirely when there is no remembered shelf, or it no longer exists
+        // (deleted since it was last used) — a dangling "Recent" entry would be worse
+        // than no shortcut at all.
+        if (recentShelf != null && recentBookcase != null) {
+            SectionHeader(text = "Recent")
+            ShelfRow(
+                label = "${recentBookcase.name} • ${recentShelf.label}",
+                selected = selectedShelfId == recentShelf.id,
+                onClick = { onShelfSelected(recentShelf.id) },
+            )
+            GoldDivider(modifier = Modifier.padding(vertical = 12.dp))
+        }
+
+        ShelfRow(
+            label = "Not shelved",
+            selected = selectedShelfId == null,
+            onClick = { onShelfSelected(null) },
+        )
+
+        bookcases.sortedBy { it.position }.forEach { bookcase ->
+            GoldDivider(modifier = Modifier.padding(vertical = 12.dp))
+            SectionHeader(text = bookcase.name)
+            val bookcaseShelves = shelves.filter { it.bookcaseId == bookcase.id }.sortedBy { it.position }
+            if (bookcaseShelves.isEmpty()) {
+                // So an empty bookcase reads as "no shelves yet", not a rendering bug.
+                Text(
+                    text = "No shelves yet",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    fontStyle = FontStyle.Italic,
+                    modifier = Modifier.padding(vertical = 8.dp),
+                )
+            } else {
+                bookcaseShelves.forEach { shelf ->
+                    ShelfRow(
+                        label = shelf.label,
+                        selected = selectedShelfId == shelf.id,
+                        onClick = { onShelfSelected(shelf.id) },
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun SectionHeader(text: String) {
+    Text(
+        text = text,
+        style = MaterialTheme.typography.titleSmall,
+        color = MaterialTheme.colorScheme.onSurfaceVariant,
+        modifier = Modifier.padding(top = 8.dp, bottom = 4.dp),
+    )
+}
+
+@Composable
+private fun ShelfRow(label: String, selected: Boolean, onClick: () -> Unit) {
+    Row(
+        modifier = Modifier
+            .fillMaxWidth()
+            .clickable(onClick = onClick)
+            .padding(vertical = 12.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        Text(
+            text = label,
+            style = MaterialTheme.typography.bodyLarge,
+            fontWeight = if (selected) FontWeight.Bold else FontWeight.Normal,
+            color = if (selected) MaterialTheme.colorScheme.primary else MaterialTheme.colorScheme.onSurface,
+            modifier = Modifier.weight(1f),
+        )
+        if (selected) {
+            Icon(
+                imageVector = Icons.Outlined.Check,
+                contentDescription = null,
+                tint = MaterialTheme.colorScheme.primary,
+            )
+        }
+    }
+}
+
+/**
+ * Resolves [recentShelfId] to the shelf + bookcase it names, or null when there is
+ * nothing remembered, or the remembered shelf was deleted since — the two cases the
+ * "Recent" section must be omitted for. Pure so it's directly unit-testable without
+ * standing up Compose.
+ */
+internal fun resolveRecentShelf(
+    recentShelfId: String?,
+    shelves: List<ShelfEntity>,
+    bookcases: List<BookcaseEntity>,
+): Pair<ShelfEntity, BookcaseEntity>? {
+    val shelf = recentShelfId?.let { id -> shelves.find { it.id == id } } ?: return null
+    val bookcase = bookcases.find { it.id == shelf.bookcaseId } ?: return null
+    return shelf to bookcase
+}

app/app/src/main/java/org/modg/bookshelf/ui/components/SyncStatusBar.kt

@@ -11,6 +11,7 @@ import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.navigationBarsPadding
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.shape.CircleShape
@@ -38,8 +39,13 @@ enum class SyncStatus {
 }
 
 /**
- * A slim, quiet status line — never a blocking banner or dialog. Sits at the
+ * A slim, quiet status line — never a blocking banner or dialog. Sits in
- * bottom of [BookshelfScaffold] screens.
+ * [BookshelfScaffold]'s bottom-bar slot.
+ *
+ * The app draws edge to edge, so this is the one composable that sits against
+ * the very bottom of the display: it owns the navigation-bar inset itself, and
+ * its horizontal padding is deliberately wider than the app's usual 16dp so the
+ * dot and label clear a phone's rounded display corners.
  */
 @Composable
 fun SyncStatusBar(
@@ -51,7 +57,8 @@ fun SyncStatusBar(
         modifier = modifier
             .fillMaxWidth()
             .background(MaterialTheme.colorScheme.surfaceContainerLow)
-            .padding(horizontal = 16.dp, vertical = 8.dp),
+            .navigationBarsPadding()
+            .padding(horizontal = 28.dp, vertical = 8.dp),
         verticalAlignment = Alignment.CenterVertically,
         horizontalArrangement = Arrangement.spacedBy(8.dp),
     ) {

app/app/src/main/java/org/modg/bookshelf/ui/detail/DetailScreen.kt

@@ -19,8 +19,6 @@ import androidx.compose.material.icons.outlined.ExpandLess
 import androidx.compose.material.icons.outlined.ExpandMore
 import androidx.compose.material.icons.outlined.LocationOn
 import androidx.compose.material.icons.outlined.Save
-import androidx.compose.material3.DropdownMenu
-import androidx.compose.material3.DropdownMenuItem
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
@@ -56,6 +54,7 @@ import org.modg.bookshelf.ui.components.BookCover
 import org.modg.bookshelf.ui.components.BookshelfScaffold
 import org.modg.bookshelf.ui.components.GoldDivider
 import org.modg.bookshelf.ui.components.PaperSurface
+import org.modg.bookshelf.ui.components.ShelfPickerSheet
 
 /**
  * SPEC.md "detail" screen. [book] filters `deleted = 0`, so once the user
@@ -76,6 +75,7 @@ fun DetailScreen(
                 DetailViewModel(
                     bookRepository = container.bookRepository,
                     locationRepository = container.locationRepository,
+                    settingsStore = container.settingsStore,
                     bookId = bookId,
                 )
             }
@@ -85,6 +85,7 @@ fun DetailScreen(
     val book by viewModel.book.collectAsState()
     val bookcases by viewModel.bookcases.collectAsState()
     val shelves by viewModel.shelves.collectAsState()
+    val recentShelfId by viewModel.recentShelfId.collectAsState()
 
     var retainedBook by remember { mutableStateOf<BookEntity?>(null) }
     LaunchedEffect(book) { book?.let { retainedBook = it } }
@@ -163,6 +164,7 @@ fun DetailScreen(
                             book = display,
                             bookcases = bookcases,
                             shelves = shelves,
+                            recentShelfId = recentShelfId,
                             onShelfSelected = viewModel::saveLocation,
                         )
                     }
@@ -271,9 +273,10 @@ internal fun LocationSection(
     book: BookEntity,
     bookcases: List<BookcaseEntity>,
     shelves: List<ShelfEntity>,
+    recentShelfId: String?,
     onShelfSelected: (String?) -> Unit,
 ) {
-    var menuExpanded by remember { mutableStateOf(false) }
+    var pickerOpen by remember { mutableStateOf(false) }
     val currentShelf = shelves.find { it.id == book.shelfId }
     val currentBookcase = currentShelf?.let { shelf -> bookcases.find { it.id == shelf.bookcaseId } }
     val label = if (currentShelf != null && currentBookcase != null) {
@@ -291,25 +294,20 @@ internal fun LocationSection(
         ) {
             Icon(Icons.Outlined.LocationOn, contentDescription = null, tint = MaterialTheme.colorScheme.secondary)
             Text(text = label, style = MaterialTheme.typography.bodyLarge, modifier = Modifier.weight(1f))
-            Box {
+            TextButton(onClick = { pickerOpen = true }) { Text("Change") }
-                TextButton(onClick = { menuExpanded = true }) { Text("Change") }
-                DropdownMenu(expanded = menuExpanded, onDismissRequest = { menuExpanded = false }) {
-                    DropdownMenuItem(
-                        text = { Text("Not shelved") },
-                        onClick = { onShelfSelected(null); menuExpanded = false },
-                    )
-                    bookcases.forEach { bookcase ->
-                        shelves.filter { it.bookcaseId == bookcase.id }.forEach { shelf ->
-                            DropdownMenuItem(
-                                text = { Text("${bookcase.name} • ${shelf.label}") },
-                                onClick = { onShelfSelected(shelf.id); menuExpanded = false },
-                            )
-                        }
-                    }
-                }
-            }
         }
     }
+
+    if (pickerOpen) {
+        ShelfPickerSheet(
+            bookcases = bookcases,
+            shelves = shelves,
+            selectedShelfId = book.shelfId,
+            recentShelfId = recentShelfId,
+            onShelfSelected = onShelfSelected,
+            onDismissRequest = { pickerOpen = false },
+        )
+    }
 }
 
 @Composable

app/app/src/main/java/org/modg/bookshelf/ui/detail/DetailViewModel.kt

@@ -9,6 +9,7 @@ import kotlinx.coroutines.launch
 import org.modg.bookshelf.data.local.BookEntity
 import org.modg.bookshelf.data.local.BookcaseEntity
 import org.modg.bookshelf.data.local.ShelfEntity
+import org.modg.bookshelf.data.prefs.SettingsStore
 import org.modg.bookshelf.data.repo.BookRepository
 import org.modg.bookshelf.data.repo.LocationRepository
 import org.modg.bookshelf.data.repo.decodeAuthors
@@ -44,6 +45,7 @@ data class BookEditForm(
 class DetailViewModel(
     private val bookRepository: BookRepository,
     private val locationRepository: LocationRepository,
+    private val settingsStore: SettingsStore,
     private val bookId: String,
 ) : ViewModel() {
 
@@ -61,6 +63,10 @@ class DetailViewModel(
     val shelves: StateFlow<List<ShelfEntity>> = locationRepository.observeShelves()
         .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())
 
+    /** The shelf most recently assigned to any book, across sessions — surfaced as the picker's "Recent" shortcut. */
+    val recentShelfId: StateFlow<String?> = settingsStore.lastShelfId
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)
+
     fun saveNotes(notes: String) {
         val current = book.value ?: return
         viewModelScope.launch { bookRepository.save(current.copy(notes = notes.ifBlank { null })) }
@@ -68,7 +74,17 @@ class DetailViewModel(
 
     fun saveLocation(shelfId: String?) {
         val current = book.value ?: return
-        viewModelScope.launch { bookRepository.save(current.copy(shelfId = shelfId)) }
+        viewModelScope.launch { performSaveLocation(current, shelfId) }
+    }
+
+    /**
+     * The actual save-location logic, split out from [saveLocation] so tests can await it
+     * directly (as a plain suspend call) instead of racing [viewModelScope]'s launch.
+     */
+    internal suspend fun performSaveLocation(current: BookEntity, shelfId: String?) {
+        bookRepository.save(current.copy(shelfId = shelfId))
+        // "Not shelved" (null) must never overwrite the memory — it isn't a shelf.
+        if (shelfId != null) settingsStore.setLastShelfId(shelfId)
     }
 
     fun saveEdit(form: BookEditForm) {

app/app/src/main/java/org/modg/bookshelf/ui/library/LibraryScreen.kt

@@ -18,7 +18,6 @@ import androidx.compose.material.icons.outlined.QrCodeScanner
 import androidx.compose.material.icons.outlined.Search
 import androidx.compose.material.icons.outlined.Settings
 import androidx.compose.material.icons.outlined.Sort
-import androidx.compose.material.icons.outlined.Warehouse
 import androidx.compose.material3.DropdownMenu
 import androidx.compose.material3.DropdownMenuItem
 import androidx.compose.material3.ExperimentalMaterial3Api
@@ -37,12 +36,15 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.res.painterResource
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
 import androidx.lifecycle.viewmodel.compose.viewModel
 import androidx.lifecycle.viewmodel.initializer
 import androidx.lifecycle.viewmodel.viewModelFactory
 import org.modg.bookshelf.AppContainer
+import org.modg.bookshelf.R
 import org.modg.bookshelf.data.local.BookEntity
 import org.modg.bookshelf.data.local.BookcaseEntity
 import org.modg.bookshelf.data.local.ShelfEntity
@@ -96,7 +98,7 @@ fun LibraryScreen(
         title = "Bookshelf",
         actions = {
             IconButton(onClick = onLocationsClick) {
-                Icon(Icons.Outlined.Warehouse, contentDescription = "Bookcases & shelves")
+                Icon(painterResource(R.drawable.ic_shelves), contentDescription = "Bookcases & shelves")
             }
             IconButton(onClick = onSettingsClick) {
                 Icon(Icons.Outlined.Settings, contentDescription = "Settings")
@@ -201,20 +203,28 @@ internal fun LibraryToolbar(
                 Icon(Icons.Outlined.FilterList, contentDescription = "Filter by bookcase or shelf")
             }
             DropdownMenu(expanded = filterMenuExpanded, onDismissRequest = { filterMenuExpanded = false }) {
-                DropdownMenuItem(
+                if (bookcases.isEmpty() && shelves.isEmpty()) {
-                    text = { Text("All books") },
-                    onClick = { onFilterChange(LibraryFilter.All); filterMenuExpanded = false },
-                )
-                bookcases.forEach { bookcase ->
                     DropdownMenuItem(
-                        text = { Text(bookcase.name, style = MaterialTheme.typography.titleSmall) },
+                        text = { Text("Add a bookcase to enable filtering") },
-                        onClick = { onFilterChange(LibraryFilter.Bookcase(bookcase.id)); filterMenuExpanded = false },
+                        enabled = false,
+                        onClick = {},
                     )
-                    shelves.filter { it.bookcaseId == bookcase.id }.forEach { shelf ->
+                } else {
+                    DropdownMenuItem(
+                        text = { Text("All books") },
+                        onClick = { onFilterChange(LibraryFilter.All); filterMenuExpanded = false },
+                    )
+                    bookcases.forEach { bookcase ->
                         DropdownMenuItem(
-                            text = { Text("    ${shelf.label}") },
+                            text = { Text(bookcase.name, style = MaterialTheme.typography.titleSmall) },
-                            onClick = { onFilterChange(LibraryFilter.Shelf(shelf.id)); filterMenuExpanded = false },
+                            onClick = { onFilterChange(LibraryFilter.Bookcase(bookcase.id)); filterMenuExpanded = false },
                         )
+                        shelves.filter { it.bookcaseId == bookcase.id }.forEach { shelf ->
+                            DropdownMenuItem(
+                                text = { Text("    ${shelf.label}") },
+                                onClick = { onFilterChange(LibraryFilter.Shelf(shelf.id)); filterMenuExpanded = false },
+                            )
+                        }
                     }
                 }
             }
@@ -264,9 +274,14 @@ internal fun LibraryBookCard(book: BookEntity, onClick: () -> Unit) {
             contentDescription = book.title,
             modifier = Modifier.fillMaxWidth(),
         )
+        // titleSmall's 24sp line height is right for a paragraph and wrong here: on a
+        // wrapped two-line title it opened a bigger gap between the title's own lines
+        // than between the title and the author beneath it, so the author read as part
+        // of the title block. Tighten the leading and give the author its own gap, so
+        // the card groups as one title + one byline.
         Text(
             text = book.title,
-            style = MaterialTheme.typography.titleSmall,
+            style = MaterialTheme.typography.titleSmall.copy(lineHeight = 20.sp),
             color = MaterialTheme.colorScheme.onSurface,
             maxLines = 2,
             overflow = TextOverflow.Ellipsis,
@@ -280,6 +295,7 @@ internal fun LibraryBookCard(book: BookEntity, onClick: () -> Unit) {
                 color = MaterialTheme.colorScheme.onSurfaceVariant,
                 maxLines = 1,
                 overflow = TextOverflow.Ellipsis,
+                modifier = Modifier.padding(top = 4.dp),
             )
         }
     }

app/app/src/main/java/org/modg/bookshelf/ui/locations/LocationsScreen.kt

@@ -32,12 +32,15 @@ import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.focus.FocusRequester
+import androidx.compose.ui.focus.focusRequester
 import androidx.compose.ui.unit.dp
 import androidx.lifecycle.viewmodel.compose.viewModel
 import androidx.lifecycle.viewmodel.initializer
@@ -94,7 +97,12 @@ fun LocationsScreen(
                     action = { PrimaryButton(text = "Add a bookcase", onClick = viewModel::openAddBookcase) },
                 )
             } else {
-                LazyColumn(contentPadding = PaddingValues(bottom = 96.dp)) {
+                LazyColumn(
+                    contentPadding = PaddingValues(
+                        top = innerPadding.calculateTopPadding(),
+                        bottom = innerPadding.calculateBottomPadding() + 96.dp,
+                    ),
+                ) {
                     items(state.bookcases, key = { it.bookcase.id }) { bookcaseUi ->
                         BookcaseRow(
                             bookcaseUi = bookcaseUi,
@@ -268,12 +276,22 @@ private fun BookcaseEditDialog(
 ) {
     var name by remember { mutableStateOf(editing?.name.orEmpty()) }
     var note by remember { mutableStateOf(editing?.note.orEmpty()) }
+    val nameFocusRequester = remember { FocusRequester() }
+    LaunchedEffect(Unit) {
+        runCatching { nameFocusRequester.requestFocus() }
+    }
     AlertDialog(
         onDismissRequest = onDismiss,
         title = { Text(text = title, style = MaterialTheme.typography.titleLarge) },
         text = {
             Column(verticalArrangement = Arrangement.spacedBy(8.dp)) {
-                OutlinedTextField(value = name, onValueChange = { name = it }, label = { Text("Name") }, singleLine = true)
+                OutlinedTextField(
+                    value = name,
+                    onValueChange = { name = it },
+                    label = { Text("Name") },
+                    singleLine = true,
+                    modifier = Modifier.focusRequester(nameFocusRequester),
+                )
                 OutlinedTextField(value = note, onValueChange = { note = it }, label = { Text("Note (optional)") }, singleLine = true)
             }
         },
@@ -292,11 +310,21 @@ private fun ShelfEditDialog(
     onSubmit: (label: String) -> Unit,
 ) {
     var label by remember { mutableStateOf(editing?.label.orEmpty()) }
+    val labelFocusRequester = remember { FocusRequester() }
+    LaunchedEffect(Unit) {
+        runCatching { labelFocusRequester.requestFocus() }
+    }
     AlertDialog(
         onDismissRequest = onDismiss,
         title = { Text(text = title, style = MaterialTheme.typography.titleLarge) },
         text = {
-            OutlinedTextField(value = label, onValueChange = { label = it }, label = { Text("Label") }, singleLine = true)
+            OutlinedTextField(
+                value = label,
+                onValueChange = { label = it },
+                label = { Text("Label") },
+                singleLine = true,
+                modifier = Modifier.focusRequester(labelFocusRequester),
+            )
         },
         confirmButton = {
             TextButton(onClick = { onSubmit(label) }, enabled = label.isNotBlank()) { Text("Save") }

app/app/src/main/java/org/modg/bookshelf/ui/scan/ScanCodeFilter.kt

@@ -2,11 +2,31 @@ package org.modg.bookshelf.ui.scan
 
 import org.modg.bookshelf.data.metadata.IsbnUtils
 
+/** What a single decoded barcode read means, once debouncing has been applied. */
+sealed interface ScanOutcome {
+    /** A checksum-valid ISBN-13, ready for metadata lookup. */
+    data class Isbn(val isbn13: String) : ScanOutcome
+
+    /**
+     * Decoded fine, but its checksum rules it out as a book ISBN (SPEC.md
+     * "Barcode scanning": "ignore non-book barcodes" — but not silently, see
+     * [rawValue]). Carries the raw value so the camera screen can echo back what
+     * it read.
+     */
+    data class NotAnIsbn(val rawValue: String) : ScanOutcome
+
+    /** A debounced repeat of the last code (valid or not) — emit no UI at all. */
+    data object Ignored : ScanOutcome
+}
+
 /**
- * Pure decode-to-ISBN pipeline shared by the analyzer and its tests: normalizes a raw
+ * Pure decode-to-outcome pipeline shared by the analyzer and its tests: normalizes
- * barcode value, validates the ISBN-13 checksum (this is what makes EAN_8/UPC_A reads
+ * a raw barcode value, classifies it as a valid ISBN-13 or not (this is what makes
- * fall out as "non-book barcodes" per SPEC.md "Barcode scanning" — they can never be
+ * EAN_8/UPC_A reads fall out as "non-book barcodes" per SPEC.md "Barcode scanning"
- * 13 digits), and debounces repeat reads of the same code.
+ * — they can never be 13 digits), and debounces repeats of the same code, whether
+ * or not it validated. The debounce is what keeps a non-book barcode sitting in
+ * frame — which decodes on nearly every analyzed frame — from flickering a
+ * rejection message instead of showing it once.
  */
 class ScanCodeFilter(
     private val debounceMillis: Long = 2000L,
@@ -15,15 +35,19 @@ class ScanCodeFilter(
     private var lastCode: String? = null
     private var lastEmitMillis: Long = Long.MIN_VALUE
 
-    /** Returns the normalized ISBN-13 if [rawValue] is a valid, non-debounced hit; null otherwise. */
+    /** Classifies [rawValue] per [ScanOutcome], applying the debounce window. */
-    fun accept(rawValue: String?): String? {
+    fun accept(rawValue: String?): ScanOutcome {
-        val normalized = IsbnUtils.normalize(rawValue ?: return null)
+        val raw = rawValue ?: return ScanOutcome.Ignored
-        if (!IsbnUtils.isValidIsbn13(normalized)) return null
+        val normalized = IsbnUtils.normalize(raw)
         val now = nowMillis()
-        if (normalized == lastCode && now - lastEmitMillis < debounceMillis) return null
+        if (normalized == lastCode && now - lastEmitMillis < debounceMillis) return ScanOutcome.Ignored
         lastCode = normalized
         lastEmitMillis = now
-        return normalized
+        return if (IsbnUtils.isValidIsbn13(normalized)) {
+            ScanOutcome.Isbn(normalized)
+        } else {
+            ScanOutcome.NotAnIsbn(raw)
+        }
     }
 
     /** Allows the next scan of any code (including a repeat) to emit immediately, e.g. after Skip. */

app/app/src/main/java/org/modg/bookshelf/ui/scan/ScanModels.kt

@@ -2,6 +2,7 @@ package org.modg.bookshelf.ui.scan
 
 import org.modg.bookshelf.data.local.BookEntity
 import org.modg.bookshelf.data.metadata.BookMetadata
+import org.modg.bookshelf.data.metadata.LookupResult
 
 /** SPEC.md scan screen: "Duplicate-ISBN warning if already owned." */
 sealed interface DuplicateStatus {
@@ -18,16 +19,39 @@ object DuplicateCheck {
 /** What the scan bottom sheet is currently showing. */
 sealed interface ScanSheetState {
     data object Hidden : ScanSheetState
-    data object Loading : ScanSheetState
+
+    /**
+     * Carries [isbn13] so the sheet can name the code it just read. A bare spinner
+     * doesn't tell the user the barcode was recognised, and they keep holding the
+     * book up to the camera; echoing the number back is the signal that they can
+     * lower it.
+     */
+    data class Loading(val isbn13: String) : ScanSheetState
     data class Found(val isbn13: String, val metadata: BookMetadata, val duplicate: DuplicateStatus) : ScanSheetState
-    data class NotFound(val isbn13: String) : ScanSheetState
+
+    /**
+     * Every source answered and none had the book (SPEC: an honest "no", not a
+     * cover story for a failed request). [viaLookupFailure] is true only when the
+     * user reached this form through [LookupFailed]'s "Enter by hand" escape hatch
+     * rather than a genuine miss, so the sheet's copy can stop short of claiming
+     * the book is unknown.
+     */
+    data class NotFound(val isbn13: String, val viaLookupFailure: Boolean = false) : ScanSheetState
+
+    /**
+     * At least one source couldn't be reached (non-2xx, timeout, transport error)
+     * and neither had the book — SPEC: "must NOT claim the book is unknown". Offers
+     * retry, manual entry, and skip instead of a manual-entry form captioned as a miss.
+     */
+    data class LookupFailed(val isbn13: String, val reason: String) : ScanSheetState
 }
 
 /** Combines a metadata lookup result with duplicate status into the sheet state to show. */
 object ScanMetadataOutcome {
-    fun from(isbn13: String, metadata: BookMetadata?, duplicate: DuplicateStatus): ScanSheetState = when (metadata) {
+    fun from(isbn13: String, result: LookupResult, duplicate: DuplicateStatus): ScanSheetState = when (result) {
-        null -> ScanSheetState.NotFound(isbn13)
+        is LookupResult.Found -> ScanSheetState.Found(isbn13, result.metadata, duplicate)
-        else -> ScanSheetState.Found(isbn13, metadata, duplicate)
+        is LookupResult.NotFound -> ScanSheetState.NotFound(isbn13)
+        is LookupResult.Unavailable -> ScanSheetState.LookupFailed(isbn13, result.reason)
     }
 }
 

app/app/src/main/java/org/modg/bookshelf/ui/scan/ScanScreen.kt

@@ -18,6 +18,7 @@ import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.automirrored.outlined.ArrowBack
 import androidx.compose.material.icons.outlined.FlashOff
@@ -43,7 +44,11 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.focus.FocusRequester
+import androidx.compose.ui.focus.focusRequester
 import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.platform.LocalSoftwareKeyboardController
+import androidx.compose.ui.text.input.KeyboardType
 import androidx.compose.ui.platform.LocalLifecycleOwner
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.viewinterop.AndroidView
@@ -58,11 +63,13 @@ import org.modg.bookshelf.AppContainer
 import org.modg.bookshelf.data.local.BookcaseEntity
 import org.modg.bookshelf.data.local.ShelfEntity
 import org.modg.bookshelf.data.metadata.BookMetadata
+import org.modg.bookshelf.data.metadata.IsbnUtils
 import org.modg.bookshelf.ui.components.BookCover
 import org.modg.bookshelf.ui.components.BookshelfScaffold
 import org.modg.bookshelf.ui.components.EmptyState
 import org.modg.bookshelf.ui.components.PrimaryButton
 import org.modg.bookshelf.ui.components.SecondaryButton
+import org.modg.bookshelf.ui.components.ShelfPickerSheet
 
 /**
  * SPEC.md "scan" screen: camera + reticle, on-hit bottom sheet, continuous
@@ -82,6 +89,7 @@ fun ScanScreen(
                     bookRepository = container.bookRepository,
                     locationRepository = container.locationRepository,
                     metadataRepository = container.metadataRepository,
+                    settingsStore = container.settingsStore,
                 )
             }
         },
@@ -89,10 +97,12 @@ fun ScanScreen(
 
     val sheetState by viewModel.sheetState.collectAsState()
     val sessionState by viewModel.sessionState.collectAsState()
+    val rejectedMessage by viewModel.rejectedMessage.collectAsState()
     val torchEnabled by viewModel.scannerController.torchEnabled.collectAsState()
     val bookcases by viewModel.bookcases.collectAsState()
     val shelves by viewModel.shelves.collectAsState()
     val selectedShelfId by viewModel.selectedShelfId.collectAsState()
+    val recentShelfId by viewModel.recentShelfId.collectAsState()
 
     val permissionState = rememberPermissionState(Manifest.permission.CAMERA)
     LaunchedEffect(Unit) {
@@ -128,6 +138,12 @@ fun ScanScreen(
                 CameraPreview(controller = viewModel.scannerController, torchEnabled = torchEnabled)
                 ScanReticle(modifier = Modifier.align(Alignment.Center))
                 SessionBadge(count = sessionState.savedCount, modifier = Modifier.align(Alignment.TopCenter).padding(16.dp))
+                rejectedMessage?.let { message ->
+                    RejectedBarcodeBanner(
+                        message = message,
+                        modifier = Modifier.align(Alignment.BottomCenter).padding(24.dp),
+                    )
+                }
             } else {
                 PermissionDeniedContent(onRequestAgain = { permissionState.launchPermissionRequest() })
             }
@@ -137,9 +153,7 @@ fun ScanScreen(
     when (val state = sheetState) {
         is ScanSheetState.Hidden -> Unit
         is ScanSheetState.Loading -> ModalBottomSheet(onDismissRequest = { }, sheetState = rememberModalBottomSheetState()) {
-            Box(modifier = Modifier.fillMaxWidth().padding(32.dp), contentAlignment = Alignment.Center) {
+            SearchingSheet(isbn13 = state.isbn13)
-                CircularProgressIndicator()
-            }
         }
         is ScanSheetState.Found -> ModalBottomSheet(
             onDismissRequest = { viewModel.dismissSheet() },
@@ -151,6 +165,7 @@ fun ScanScreen(
                 bookcases = bookcases,
                 shelves = shelves,
                 selectedShelfId = selectedShelfId,
+                recentShelfId = recentShelfId,
                 onShelfSelected = viewModel::selectShelf,
                 onSave = { viewModel.save(state.isbn13, state.metadata) },
                 onSkip = { viewModel.skip() },
@@ -162,14 +177,28 @@ fun ScanScreen(
         ) {
             ManualEntrySheet(
                 isbn13 = state.isbn13,
+                authoritative = !state.viaLookupFailure,
                 bookcases = bookcases,
                 shelves = shelves,
                 selectedShelfId = selectedShelfId,
+                recentShelfId = recentShelfId,
                 onShelfSelected = viewModel::selectShelf,
                 onSave = { title, authors -> viewModel.saveManualEntry(state.isbn13, title, authors) },
                 onSkip = { viewModel.skip() },
             )
         }
+        is ScanSheetState.LookupFailed -> ModalBottomSheet(
+            onDismissRequest = { viewModel.dismissSheet() },
+            sheetState = rememberModalBottomSheetState(),
+        ) {
+            LookupFailedSheet(
+                isbn13 = state.isbn13,
+                reason = state.reason,
+                onRetry = { viewModel.retryLookup(state.isbn13) },
+                onEnterByHand = { viewModel.enterByHand(state.isbn13) },
+                onSkip = { viewModel.skip() },
+            )
+        }
     }
 
     if (showManualEntry) {
@@ -238,6 +267,33 @@ internal fun ScanReticle(modifier: Modifier = Modifier) {
     }
 }
 
+/**
+ * Shown the moment a barcode is decoded, while the metadata lookup runs. It names
+ * the ISBN it read, because a lone spinner reads as "still working on it" — echoing
+ * the number back is what tells the user the barcode was actually recognised.
+ */
+@Composable
+internal fun SearchingSheet(isbn13: String) {
+    Column(
+        modifier = Modifier.fillMaxWidth().padding(horizontal = 24.dp, vertical = 32.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+    ) {
+        CircularProgressIndicator()
+        Text(
+            text = "Searching…",
+            style = MaterialTheme.typography.titleMedium,
+            color = MaterialTheme.colorScheme.onSurface,
+            modifier = Modifier.padding(top = 20.dp),
+        )
+        Text(
+            text = "ISBN $isbn13",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.padding(top = 4.dp),
+        )
+    }
+}
+
 @Composable
 internal fun SessionBadge(count: Int, modifier: Modifier = Modifier) {
     if (count == 0) return
@@ -267,6 +323,7 @@ internal fun FoundBookSheet(
     bookcases: List<BookcaseEntity>,
     shelves: List<ShelfEntity>,
     selectedShelfId: String?,
+    recentShelfId: String?,
     onShelfSelected: (String?) -> Unit,
     onSave: () -> Unit,
     onSkip: () -> Unit,
@@ -299,6 +356,7 @@ internal fun FoundBookSheet(
             bookcases = bookcases,
             shelves = shelves,
             selectedShelfId = selectedShelfId,
+            recentShelfId = recentShelfId,
             onShelfSelected = onShelfSelected,
         )
         Row(modifier = Modifier.fillMaxWidth().padding(top = 16.dp), horizontalArrangement = Arrangement.spacedBy(12.dp)) {
@@ -308,12 +366,20 @@ internal fun FoundBookSheet(
     }
 }
 
+/**
+ * Shown when every source answered and none had the book — SPEC: word this as the
+ * authoritative negative it is, not as a generic failure. [authoritative] is false
+ * only when this form was reached via [LookupFailedSheet]'s "Enter by hand", where
+ * the lookup never completed and the copy must not imply the book is unknown.
+ */
 @Composable
 internal fun ManualEntrySheet(
     isbn13: String,
+    authoritative: Boolean,
     bookcases: List<BookcaseEntity>,
     shelves: List<ShelfEntity>,
     selectedShelfId: String?,
+    recentShelfId: String?,
     onShelfSelected: (String?) -> Unit,
     onSave: (title: String, authors: List<String>) -> Unit,
     onSkip: () -> Unit,
@@ -322,9 +388,12 @@ internal fun ManualEntrySheet(
     var authors by remember { mutableStateOf("") }
 
     Column(modifier = Modifier.fillMaxWidth().padding(16.dp)) {
-        Text(text = "No match found", style = MaterialTheme.typography.titleLarge)
         Text(
-            text = "ISBN $isbn13 — enter the details by hand.",
+            text = if (authoritative) "Not in Open Library or Google Books" else "Enter the details by hand",
+            style = MaterialTheme.typography.titleLarge,
+        )
+        Text(
+            text = if (authoritative) "ISBN $isbn13 — enter the details by hand." else "ISBN $isbn13",
             style = MaterialTheme.typography.bodyMedium,
             color = MaterialTheme.colorScheme.onSurfaceVariant,
             modifier = Modifier.padding(bottom = 12.dp),
@@ -345,6 +414,7 @@ internal fun ManualEntrySheet(
             bookcases = bookcases,
             shelves = shelves,
             selectedShelfId = selectedShelfId,
+            recentShelfId = recentShelfId,
             onShelfSelected = onShelfSelected,
         )
         Row(modifier = Modifier.fillMaxWidth().padding(top = 16.dp), horizontalArrangement = Arrangement.spacedBy(12.dp)) {
@@ -361,14 +431,73 @@ internal fun ManualEntrySheet(
     }
 }
 
+/**
+ * Shown when a lookup couldn't be completed — SPEC: "a retry affordance, with
+ * manual entry as the escape hatch; it must NOT claim the book is unknown." No
+ * shelf picker here: saving isn't offered from this sheet, only a path onward to
+ * one that does (Retry, or the manual-entry form via "Enter by hand"). [reason]
+ * is [MetadataRepository]'s diagnostic string (e.g. "open library: network error;
+ * google books: http 429") — the only channel we have back from a lookup failure
+ * on a real phone, so it must actually reach the screen instead of being dropped.
+ */
+@Composable
+internal fun LookupFailedSheet(
+    isbn13: String,
+    reason: String,
+    onRetry: () -> Unit,
+    onEnterByHand: () -> Unit,
+    onSkip: () -> Unit,
+) {
+    Column(modifier = Modifier.fillMaxWidth().padding(16.dp)) {
+        Text(text = "Couldn't complete the lookup", style = MaterialTheme.typography.titleLarge)
+        Text(
+            text = "ISBN $isbn13 — one or more sources couldn't be reached. " +
+                "This doesn't mean the book is unknown.",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.padding(top = 8.dp),
+        )
+        Text(
+            text = reason,
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            modifier = Modifier.padding(top = 4.dp, bottom = 16.dp),
+        )
+        PrimaryButton(text = "Retry", onClick = onRetry, modifier = Modifier.fillMaxWidth())
+        Row(modifier = Modifier.fillMaxWidth().padding(top = 12.dp), horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+            SecondaryButton(text = "Enter by hand", onClick = onEnterByHand, modifier = Modifier.weight(1f))
+            SecondaryButton(text = "Skip", onClick = onSkip, modifier = Modifier.weight(1f))
+        }
+    }
+}
+
+/**
+ * Transient banner for a decoded-but-rejected barcode (SPEC.md "Barcode scanning":
+ * "A rejected barcode is NOT silent"). [ScanViewModel] owns the debounce (via
+ * [ScanCodeFilter]) and the auto-clear timer behind [message] — this composable
+ * just renders whatever it's handed.
+ */
+@Composable
+internal fun RejectedBarcodeBanner(message: String, modifier: Modifier = Modifier) {
+    Text(
+        text = message,
+        style = MaterialTheme.typography.labelLarge,
+        color = MaterialTheme.colorScheme.onErrorContainer,
+        modifier = modifier
+            .background(MaterialTheme.colorScheme.errorContainer, RoundedCornerShape(20.dp))
+            .padding(horizontal = 16.dp, vertical = 8.dp),
+    )
+}
+
 @Composable
 internal fun ShelfPicker(
     bookcases: List<BookcaseEntity>,
     shelves: List<ShelfEntity>,
     selectedShelfId: String?,
+    recentShelfId: String?,
     onShelfSelected: (String?) -> Unit,
 ) {
-    var expanded by remember { mutableStateOf(false) }
+    var pickerOpen by remember { mutableStateOf(false) }
     val currentShelf = shelves.find { it.id == selectedShelfId }
     val currentBookcase = currentShelf?.let { shelf -> bookcases.find { it.id == shelf.bookcaseId } }
     val label = if (currentShelf != null && currentBookcase != null) {
@@ -378,40 +507,64 @@ internal fun ShelfPicker(
     }
 
     Box(modifier = Modifier.padding(top = 12.dp)) {
-        SecondaryButton(text = label, onClick = { expanded = true })
+        SecondaryButton(text = label, onClick = { pickerOpen = true })
-        androidx.compose.material3.DropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
+    }
-            androidx.compose.material3.DropdownMenuItem(
+
-                text = { Text("Not shelved") },
+    if (pickerOpen) {
-                onClick = { onShelfSelected(null); expanded = false },
+        ShelfPickerSheet(
-            )
+            bookcases = bookcases,
-            bookcases.forEach { bookcase ->
+            shelves = shelves,
-                shelves.filter { it.bookcaseId == bookcase.id }.forEach { shelf ->
+            selectedShelfId = selectedShelfId,
-                    androidx.compose.material3.DropdownMenuItem(
+            recentShelfId = recentShelfId,
-                        text = { Text("${bookcase.name} • ${shelf.label}") },
+            onShelfSelected = onShelfSelected,
-                        onClick = { onShelfSelected(shelf.id); expanded = false },
+            onDismissRequest = { pickerOpen = false },
-                    )
+        )
-                }
-            }
-        }
     }
 }
 
 @Composable
 private fun ManualIsbnDialog(onDismiss: () -> Unit, onSubmit: (String) -> Unit) {
     var text by remember { mutableStateOf("") }
+    // Validate here rather than letting ScanViewModel.manualIsbnEntered drop an
+    // unparseable ISBN on the floor. A typed-in check digit is easy to get wrong,
+    // and a dialog whose button does nothing is the same silent failure this whole
+    // screen was just rebuilt to eliminate.
+    val isbn13 = remember(text) { IsbnUtils.toIsbn13(text) }
+    val malformed = text.isNotBlank() && isbn13 == null
+    val focusRequester = remember { FocusRequester() }
+    val keyboardController = LocalSoftwareKeyboardController.current
+    // The dialog opens with the field unfocused otherwise — this is the only entry
+    // point into the field, so make it ready to type into immediately.
+    LaunchedEffect(Unit) {
+        runCatching { focusRequester.requestFocus() }
+        keyboardController?.show()
+    }
     AlertDialog(
         onDismissRequest = onDismiss,
         title = { Text("Enter ISBN") },
         text = {
-            OutlinedTextField(
+            Column {
-                value = text,
+                OutlinedTextField(
-                onValueChange = { text = it },
+                    value = text,
-                label = { Text("ISBN-10 or ISBN-13") },
+                    onValueChange = { text = it },
-                singleLine = true,
+                    label = { Text("ISBN-10 or ISBN-13") },
-            )
+                    singleLine = true,
+                    isError = malformed,
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                    modifier = Modifier.focusRequester(focusRequester),
+                )
+                if (malformed) {
+                    Text(
+                        text = "That isn't a valid ISBN — check the digits.",
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.error,
+                        modifier = Modifier.padding(top = 4.dp),
+                    )
+                }
+            }
         },
         confirmButton = {
-            PrimaryButton(text = "Look up", onClick = { onSubmit(text) }, enabled = text.isNotBlank())
+            PrimaryButton(text = "Look up", onClick = { onSubmit(text) }, enabled = isbn13 != null)
         },
         dismissButton = {
             SecondaryButton(text = "Cancel", onClick = onDismiss)

app/app/src/main/java/org/modg/bookshelf/ui/scan/ScanViewModel.kt

@@ -2,6 +2,8 @@ package org.modg.bookshelf.ui.scan
 
 import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
@@ -13,6 +15,7 @@ import org.modg.bookshelf.data.local.ShelfEntity
 import org.modg.bookshelf.data.metadata.BookMetadata
 import org.modg.bookshelf.data.metadata.IsbnUtils
 import org.modg.bookshelf.data.metadata.MetadataRepository
+import org.modg.bookshelf.data.prefs.SettingsStore
 import org.modg.bookshelf.data.repo.BookRepository
 import org.modg.bookshelf.data.repo.LocationRepository
 
@@ -26,6 +29,7 @@ class ScanViewModel(
     private val bookRepository: BookRepository,
     locationRepository: LocationRepository,
     private val metadataRepository: MetadataRepository,
+    private val settingsStore: SettingsStore,
     val scannerController: ScannerController = ScannerController(),
 ) : ViewModel() {
 
@@ -35,6 +39,11 @@ class ScanViewModel(
     private val _sessionState = MutableStateFlow(ScanSessionState())
     val sessionState: StateFlow<ScanSessionState> = _sessionState.asStateFlow()
 
+    private val _rejectedMessage = MutableStateFlow<String?>(null)
+    /** Transient "read but not a book barcode" message for the camera overlay; auto-clears. */
+    val rejectedMessage: StateFlow<String?> = _rejectedMessage.asStateFlow()
+    private var rejectedMessageClearJob: Job? = null
+
     val bookcases: StateFlow<List<BookcaseEntity>> = locationRepository.observeBookcases()
         .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())
     val shelves: StateFlow<List<ShelfEntity>> = locationRepository.observeShelves()
@@ -44,18 +53,49 @@ class ScanViewModel(
     private val _selectedShelfId = MutableStateFlow<String?>(null)
     val selectedShelfId: StateFlow<String?> = _selectedShelfId.asStateFlow()
 
+    /** The shelf most recently assigned to any book, across sessions — surfaced as the picker's "Recent" shortcut. */
+    val recentShelfId: StateFlow<String?> = settingsStore.lastShelfId
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)
+
     init {
         viewModelScope.launch {
             scannerController.scanResults.collect { isbn13 -> onScanned(isbn13) }
         }
+        viewModelScope.launch {
+            scannerController.rejectedCodes.collect { rawValue -> showRejectedMessage(rawValue) }
+        }
     }
 
     private suspend fun onScanned(isbn13: String) {
         if (_sheetState.value !is ScanSheetState.Hidden) return // a sheet is already up for a previous hit
-        _sheetState.value = ScanSheetState.Loading
+        runLookup(isbn13)
+    }
+
+    private suspend fun runLookup(isbn13: String) {
+        _sheetState.value = ScanSheetState.Loading(isbn13)
         val duplicate = DuplicateCheck.check(bookRepository.findByIsbn13(isbn13))
-        val metadata = metadataRepository.lookup(isbn13)
+        val result = metadataRepository.lookup(isbn13)
-        _sheetState.value = ScanMetadataOutcome.from(isbn13, metadata, duplicate)
+        _sheetState.value = ScanMetadataOutcome.from(isbn13, result, duplicate)
+    }
+
+    /** [ScanSheetState.LookupFailed]'s Retry — re-enters loading and re-runs the same lookup. */
+    fun retryLookup(isbn13: String) {
+        viewModelScope.launch { runLookup(isbn13) }
+    }
+
+    /** [ScanSheetState.LookupFailed]'s "Enter by hand" — falls through to the manual-entry form. */
+    fun enterByHand(isbn13: String) {
+        _sheetState.value = ScanSheetState.NotFound(isbn13, viaLookupFailure = true)
+    }
+
+    /** Throttled per [ScanCodeFilter]'s debounce; this just owns the auto-clear timer on top. */
+    private fun showRejectedMessage(rawValue: String) {
+        rejectedMessageClearJob?.cancel()
+        _rejectedMessage.value = "Read $rawValue — not a book barcode"
+        rejectedMessageClearJob = viewModelScope.launch {
+            delay(REJECTED_MESSAGE_MILLIS)
+            _rejectedMessage.value = null
+        }
     }
 
     /** The manual-ISBN-entry escape hatch (SPEC: for when a barcode won't scan). */
@@ -70,35 +110,53 @@ class ScanViewModel(
 
     /** Save from a successful metadata lookup. */
     fun save(isbn13: String, metadata: BookMetadata) {
-        viewModelScope.launch {
+        viewModelScope.launch { performSave(isbn13, metadata) }
-            bookRepository.createBook(
+    }
-                title = metadata.title ?: "Untitled",
+
-                subtitle = metadata.subtitle,
+    /**
-                authors = metadata.authors,
+     * The actual save-from-metadata logic, split out from [save] so tests can await it
-                isbn13 = metadata.isbn13 ?: isbn13,
+     * directly (as a plain suspend call) instead of racing [viewModelScope]'s launch.
-                isbn10 = metadata.isbn10,
+     */
-                publisher = metadata.publisher,
+    internal suspend fun performSave(isbn13: String, metadata: BookMetadata) {
-                publishedDate = metadata.publishedDate,
+        val shelfId = _selectedShelfId.value
-                pageCount = metadata.pageCount,
+        bookRepository.createBook(
-                description = metadata.description,
+            title = metadata.title ?: "Untitled",
-                coverSourceUrl = metadata.coverUrl,
+            subtitle = metadata.subtitle,
-                shelfId = _selectedShelfId.value,
+            authors = metadata.authors,
-            )
+            isbn13 = metadata.isbn13 ?: isbn13,
-            recordSave()
+            isbn10 = metadata.isbn10,
-        }
+            publisher = metadata.publisher,
+            publishedDate = metadata.publishedDate,
+            pageCount = metadata.pageCount,
+            description = metadata.description,
+            coverSourceUrl = metadata.coverUrl,
+            shelfId = shelfId,
+        )
+        rememberShelf(shelfId)
+        recordSave()
     }
 
     /** Save from the manual-entry form shown when metadata lookup misses (SPEC: pre-filled with the scanned ISBN). */
     fun saveManualEntry(isbn13: String, title: String, authors: List<String>) {
-        viewModelScope.launch {
+        viewModelScope.launch { performSaveManualEntry(isbn13, title, authors) }
-            bookRepository.createBook(
+    }
-                title = title.ifBlank { "Untitled" },
+
-                authors = authors,
+    /** Same split as [performSave], for [saveManualEntry]. */
-                isbn13 = isbn13,
+    internal suspend fun performSaveManualEntry(isbn13: String, title: String, authors: List<String>) {
-                shelfId = _selectedShelfId.value,
+        val shelfId = _selectedShelfId.value
-            )
+        bookRepository.createBook(
-            recordSave()
+            title = title.ifBlank { "Untitled" },
-        }
+            authors = authors,
+            isbn13 = isbn13,
+            shelfId = shelfId,
+        )
+        rememberShelf(shelfId)
+        recordSave()
+    }
+
+    /** "Not shelved" (null) must never overwrite the memory — it isn't a shelf. */
+    private suspend fun rememberShelf(shelfId: String?) {
+        if (shelfId != null) settingsStore.setLastShelfId(shelfId)
     }
 
     private fun recordSave() {
@@ -114,4 +172,9 @@ class ScanViewModel(
         _sheetState.value = ScanSheetState.Hidden
         scannerController.resetDebounce()
     }
+
+    private companion object {
+        /** How long a rejected-barcode message stays on screen before it auto-clears. */
+        const val REJECTED_MESSAGE_MILLIS = 3000L
+    }
 }

app/app/src/main/java/org/modg/bookshelf/ui/scan/ScannerController.kt

@@ -19,6 +19,14 @@ class ScannerController(
     /** Emits a debounced, checksum-valid ISBN-13 each time [IsbnBarcodeAnalyzer] sees a new book barcode. */
     val scanResults: SharedFlow<String> = _scanResults.asSharedFlow()
 
+    private val _rejectedCodes = MutableSharedFlow<String>(extraBufferCapacity = 1)
+    /**
+     * Emits the raw value of a debounced, non-book barcode read (SPEC.md "Barcode
+     * scanning": "A rejected barcode is NOT silent"). [ScanOutcome.Ignored] reads
+     * (debounced repeats) never reach here.
+     */
+    val rejectedCodes: SharedFlow<String> = _rejectedCodes.asSharedFlow()
+
     private val _torchEnabled = MutableStateFlow(false)
     val torchEnabled: StateFlow<Boolean> = _torchEnabled.asStateFlow()
 
@@ -27,7 +35,11 @@ class ScannerController(
 
     /** Called by [IsbnBarcodeAnalyzer] for every decoded barcode's raw value. */
     fun onBarcodeScanned(rawValue: String?) {
-        codeFilter.accept(rawValue)?.let { _scanResults.tryEmit(it) }
+        when (val outcome = codeFilter.accept(rawValue)) {
+            is ScanOutcome.Isbn -> _scanResults.tryEmit(outcome.isbn13)
+            is ScanOutcome.NotAnIsbn -> _rejectedCodes.tryEmit(outcome.rawValue)
+            ScanOutcome.Ignored -> Unit
+        }
     }
 
     fun toggleTorch() {

app/app/src/main/java/org/modg/bookshelf/ui/settings/SettingsScreen.kt

@@ -76,7 +76,7 @@ fun SettingsScreen(
                 GoldDivider(modifier = Modifier.padding(vertical = 16.dp))
 
                 SectionHeading("Account")
-                InfoRow(label = "Signed in as", value = state.userId ?: "Unknown")
+                InfoRow(label = "Signed in as", value = state.userEmail ?: "Unknown")
                 SecondaryButton(
                     text = "Sign out",
                     onClick = { confirmSignOut = true },

app/app/src/main/java/org/modg/bookshelf/ui/settings/SettingsViewModel.kt

@@ -17,7 +17,7 @@ import org.modg.bookshelf.ui.components.SyncStatus
 
 data class SettingsUiState(
     val serverUrl: String? = null,
-    val userId: String? = null,
+    val userEmail: String? = null,
     val bookCount: Int = 0,
     val coverCount: Int = 0,
     val lastSyncTime: Long? = null,
@@ -35,7 +35,7 @@ data class SettingsUiState(
 
 private data class BaseInfo(
     val serverUrl: String?,
-    val userId: String?,
+    val userEmail: String?,
     val bookCount: Int,
     val coverCount: Int,
     val lastSyncTime: Long?,
@@ -54,13 +54,13 @@ class SettingsViewModel(
 
     private val baseInfo = combine(
         authRepository.serverUrl,
-        settingsStore.userId,
+        settingsStore.userEmail,
         bookRepository.observeAll(),
         settingsStore.lastSyncTime,
-    ) { url, userId, books, lastSync ->
+    ) { url, userEmail, books, lastSync ->
         BaseInfo(
             serverUrl = url,
-            userId = userId,
+            userEmail = userEmail,
             bookCount = books.size,
             coverCount = books.count { !it.coverUrl.isNullOrBlank() || !it.localCoverPath.isNullOrBlank() },
             lastSyncTime = lastSync,
@@ -70,7 +70,7 @@ class SettingsViewModel(
     val uiState: StateFlow<SettingsUiState> = combine(baseInfo, isSyncing, syncError) { base, syncing, error ->
         SettingsUiState(
             serverUrl = base.serverUrl,
-            userId = base.userId,
+            userEmail = base.userEmail,
             bookCount = base.bookCount,
             coverCount = base.coverCount,
             lastSyncTime = base.lastSyncTime,

app/app/src/main/java/org/modg/bookshelf/ui/setup/SetupScreen.kt

@@ -4,7 +4,9 @@ import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.safeDrawingPadding
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.text.KeyboardActions
 import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.foundation.rememberScrollState
@@ -15,6 +17,9 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.focus.FocusDirection
+import androidx.compose.ui.platform.LocalFocusManager
+import androidx.compose.ui.text.input.ImeAction
 import androidx.compose.ui.text.input.KeyboardType
 import androidx.compose.ui.text.input.PasswordVisualTransformation
 import androidx.compose.ui.unit.dp
@@ -38,11 +43,23 @@ fun SetupScreen(onSetupComplete: () -> Unit, container: AppContainer) {
         },
     )
     val state by viewModel.uiState.collectAsState()
+    val focusManager = LocalFocusManager.current
+
+    val canSubmit = !state.isSubmitting &&
+        state.serverUrl.isNotBlank() &&
+        state.email.isNotBlank() &&
+        state.password.isNotBlank()
 
     PaperSurface(modifier = Modifier.fillMaxSize()) {
+        // This screen has no Scaffold of its own, so it owns its window insets.
+        // safeDrawingPadding covers the IME as well as the system bars, and it sits
+        // OUTSIDE verticalScroll on purpose: the keyboard then shrinks the scrollable
+        // viewport rather than covering it, so Compose brings the newly focused field
+        // into view instead of leaving Password stranded behind the IME.
         Column(
             modifier = Modifier
                 .fillMaxSize()
+                .safeDrawingPadding()
                 .verticalScroll(rememberScrollState())
                 .padding(24.dp),
             verticalArrangement = Arrangement.Center,
@@ -61,7 +78,11 @@ fun SetupScreen(onSetupComplete: () -> Unit, container: AppContainer) {
                 label = { Text("Server URL") },
                 placeholder = { Text("https://library.example.com") },
                 singleLine = true,
-                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Uri),
+                keyboardOptions = KeyboardOptions(
+                    keyboardType = KeyboardType.Uri,
+                    imeAction = ImeAction.Next,
+                ),
+                keyboardActions = KeyboardActions(onNext = { focusManager.moveFocus(FocusDirection.Down) }),
                 isError = state.urlError != null,
                 modifier = Modifier.fillMaxWidth(),
             )
@@ -81,7 +102,11 @@ fun SetupScreen(onSetupComplete: () -> Unit, container: AppContainer) {
                 onValueChange = viewModel::onEmailChanged,
                 label = { Text("Email") },
                 singleLine = true,
-                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email),
+                keyboardOptions = KeyboardOptions(
+                    keyboardType = KeyboardType.Email,
+                    imeAction = ImeAction.Next,
+                ),
+                keyboardActions = KeyboardActions(onNext = { focusManager.moveFocus(FocusDirection.Down) }),
                 isError = state.credentialsError != null,
                 modifier = Modifier.fillMaxWidth().padding(top = 8.dp),
             )
@@ -91,7 +116,16 @@ fun SetupScreen(onSetupComplete: () -> Unit, container: AppContainer) {
                 label = { Text("Password") },
                 singleLine = true,
                 visualTransformation = PasswordVisualTransformation(),
-                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+                keyboardOptions = KeyboardOptions(
+                    keyboardType = KeyboardType.Password,
+                    imeAction = ImeAction.Done,
+                ),
+                keyboardActions = KeyboardActions(
+                    onDone = {
+                        focusManager.clearFocus()
+                        if (canSubmit) viewModel.submit(onSetupComplete)
+                    },
+                ),
                 isError = state.credentialsError != null,
                 modifier = Modifier.fillMaxWidth().padding(top = 8.dp),
             )
@@ -107,10 +141,7 @@ fun SetupScreen(onSetupComplete: () -> Unit, container: AppContainer) {
             PrimaryButton(
                 text = if (state.isSubmitting) "Signing in…" else "Sign in",
                 onClick = { viewModel.submit(onSetupComplete) },
-                enabled = !state.isSubmitting &&
+                enabled = canSubmit,
-                    state.serverUrl.isNotBlank() &&
-                    state.email.isNotBlank() &&
-                    state.password.isNotBlank(),
                 modifier = Modifier.padding(top = 24.dp),
             )
         }

app/app/src/main/res/drawable/ic_shelves.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Material Symbols "shelves" (Apache 2.0). Source viewBox is
+     "0 -960 960 960"; Android has no viewport origin, so the group
+     translate is load-bearing. Do not flatten it. -->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="960"
+    android:viewportHeight="960">
+    <group android:translateY="960">
+        <path
+            android:fillColor="#FF000000"
+            android:pathData="M120-40v-880h80v80h560v-80h80v880h-80v-80H200v80h-80Zm80-480h80v-160h240v160h240v-240H200v240Zm0 320h240v-160h240v160h80v-240H200v240Zm160-320h80v-80h-80v80Zm160 320h80v-80h-80v80Z" />
+    </group>
+</vector>

app/app/src/test/java/org/modg/bookshelf/data/metadata/GoogleBooksClientTest.kt

@@ -46,6 +46,47 @@ class GoogleBooksClientTest {
         assertNull(client.parseResponse(body))
     }
 
+    // --- classify(): the three-way per-source outcome (SPEC.md "Book metadata lookup"). ---
+
+    @Test
+    fun `classify reports Found for a 2xx response with a record`() {
+        val result = client.classify(200, fixture("googlebooks_success.json"))
+
+        val found = result as? SourceResult.Found
+        checkNotNull(found) { "expected Found, got $result" }
+        assertEquals("Effective Java", found.metadata.title)
+    }
+
+    @Test
+    fun `classify reports NotFound for a 2xx response with no items`() {
+        val result = client.classify(200, fixture("googlebooks_no_items.json"))
+        assertEquals(SourceResult.NotFound, result)
+    }
+
+    @Test
+    fun `classify reports Failed for a 404`() {
+        val result = client.classify(404, null)
+        assertEquals(SourceResult.Failed("http 404", FailureKind.CLIENT_ERROR), result)
+    }
+
+    @Test
+    fun `classify reports Failed for a 429 keyless-quota response, distinctly from NotFound`() {
+        val result = client.classify(429, null)
+        assertEquals(SourceResult.Failed("http 429 (rate limited)", FailureKind.RATE_LIMITED), result)
+    }
+
+    @Test
+    fun `classify reports Failed for a 500`() {
+        val result = client.classify(500, "Internal Server Error")
+        assertEquals(SourceResult.Failed("http 500 (server error)", FailureKind.SERVER_ERROR), result)
+    }
+
+    @Test
+    fun `classify reports Failed for a malformed body even on a 2xx status`() {
+        val result = client.classify(200, fixture("malformed.json"))
+        assertEquals(SourceResult.Failed("malformed json", FailureKind.MALFORMED), result)
+    }
+
     private fun fixture(name: String): String =
         checkNotNull(javaClass.classLoader.getResourceAsStream("fixtures/$name")) { "missing fixture $name" }
             .bufferedReader()

app/app/src/test/java/org/modg/bookshelf/data/metadata/MetadataRepositoryTest.kt

@@ -0,0 +1,99 @@
+package org.modg.bookshelf.data.metadata
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class MetadataRepositoryTest {
+
+    private val isbn13 = "9780201558029"
+    private val openLibraryHit = SourceResult.Found(BookMetadata(title = "Open Library Title", isbn13 = isbn13))
+    private val googleBooksHit = SourceResult.Found(BookMetadata(title = "Google Books Title", isbn13 = isbn13))
+
+    // --- The full 3x3 (Open Library outcome x Google Books outcome) combination matrix
+    // from SPEC.md "Book metadata lookup": any Found wins, all-NotFound is an honest
+    // miss, anything else with a Failed in it is Unavailable — never a false negative. ---
+
+    @Test
+    fun `Found + Found merges and returns Found`() {
+        val result = MetadataRepository.combine(openLibraryHit, googleBooksHit, isbn13)
+        assertTrue(result is LookupResult.Found)
+    }
+
+    @Test
+    fun `Found + NotFound returns Found from the one source that had it`() {
+        val result = MetadataRepository.combine(openLibraryHit, SourceResult.NotFound, isbn13)
+        assertEquals("Open Library Title", (result as LookupResult.Found).metadata.title)
+    }
+
+    @Test
+    fun `Found + Failed returns Found -- a reachable hit is not overruled by the other failing`() {
+        val result = MetadataRepository.combine(openLibraryHit, SourceResult.Failed("http 429"), isbn13)
+        assertEquals("Open Library Title", (result as LookupResult.Found).metadata.title)
+    }
+
+    @Test
+    fun `NotFound + Found returns Found from the one source that had it`() {
+        val result = MetadataRepository.combine(SourceResult.NotFound, googleBooksHit, isbn13)
+        assertEquals("Google Books Title", (result as LookupResult.Found).metadata.title)
+    }
+
+    @Test
+    fun `NotFound + NotFound returns NotFound -- both sources answered and neither had it`() {
+        val result = MetadataRepository.combine(SourceResult.NotFound, SourceResult.NotFound, isbn13)
+        assertEquals(LookupResult.NotFound, result)
+    }
+
+    @Test
+    fun `NotFound + Failed returns Unavailable -- one honest miss is not authoritative alone`() {
+        val result = MetadataRepository.combine(SourceResult.NotFound, SourceResult.Failed("timeout"), isbn13)
+        assertTrue(result is LookupResult.Unavailable)
+    }
+
+    @Test
+    fun `Failed + Found returns Found from the one source that had it`() {
+        val result = MetadataRepository.combine(SourceResult.Failed("http 500"), googleBooksHit, isbn13)
+        assertEquals("Google Books Title", (result as LookupResult.Found).metadata.title)
+    }
+
+    @Test
+    fun `Failed + NotFound returns Unavailable -- one honest miss is not authoritative alone`() {
+        val result = MetadataRepository.combine(SourceResult.Failed("timeout"), SourceResult.NotFound, isbn13)
+        assertTrue(result is LookupResult.Unavailable)
+    }
+
+    @Test
+    fun `Failed + Failed returns Unavailable and preserves both reasons`() {
+        val result = MetadataRepository.combine(SourceResult.Failed("http 429"), SourceResult.Failed("timeout"), isbn13)
+
+        val unavailable = result as? LookupResult.Unavailable
+        checkNotNull(unavailable) { "expected Unavailable, got $result" }
+        assertTrue(unavailable.reason.contains("http 429"))
+        assertTrue(unavailable.reason.contains("timeout"))
+    }
+
+    @Test
+    fun `a Found result without cover art falls back to the by-isbn cover url`() {
+        val bare = SourceResult.Found(BookMetadata(title = "No Cover", isbn13 = isbn13))
+        val result = MetadataRepository.combine(bare, SourceResult.NotFound, isbn13)
+
+        assertEquals(MetadataRepository.byIsbnCoverUrl(isbn13), (result as LookupResult.Found).metadata.coverUrl)
+    }
+
+    /**
+     * `default=false` is the whole point of this URL. Without it covers.openlibrary.org
+     * answers 200 with a 43-byte 1x1 transparent GIF for an edition it holds no art for
+     * — an image loader calls that a successful load, so the cover slot renders empty
+     * and the placeholder never appears. With it, a miss is a 404 the loader can report.
+     */
+    @Test
+    fun `by-isbn cover url disables the blank stand-in image`() {
+        val url = MetadataRepository.byIsbnCoverUrl("9780201558029")
+
+        assertEquals(
+            "https://covers.openlibrary.org/b/isbn/9780201558029-L.jpg?default=false",
+            url,
+        )
+        assertTrue("must opt out of the 1x1 stand-in", url.contains("default=false"))
+    }
+}

app/app/src/test/java/org/modg/bookshelf/data/metadata/OpenLibraryClientTest.kt

@@ -29,7 +29,68 @@ class OpenLibraryClientTest {
         assertEquals(672, result.pageCount)
         assertEquals("9780201558029", result.isbn13)
         assertEquals("0201558025", result.isbn10)
-        assertEquals("https://covers.openlibrary.org/b/isbn/9780201558029-L.jpg", result.coverUrl)
+        assertEquals("https://covers.openlibrary.org/b/id/675832-L.jpg", result.coverUrl)
+    }
+
+    /**
+     * The by-ISBN cover endpoint answers 200 with a 1x1 transparent GIF for editions
+     * with no art, so synthesizing that URL here would hand the UI a cover that loads
+     * "successfully" and paints nothing. No `cover` object means no cover URL, which
+     * is what lets [MetadataMerger] fall through to Google Books' thumbnail.
+     */
+    @Test
+    fun `leaves coverUrl null when the response reports no cover art`() {
+        val body = """
+            {"ISBN:9780201558029": {"title": "Concrete Mathematics", "publishers": [{"name": "AW"}]}}
+        """.trimIndent()
+        val result = checkNotNull(client.parseResponse(body, "9780201558029"))
+
+        assertEquals("Concrete Mathematics", result.title)
+        assertNull(result.coverUrl)
+    }
+
+    @Test
+    fun `falls back to the medium cover when no large one is offered`() {
+        val body = """
+            {"ISBN:9780201558029": {"title": "Concrete Mathematics",
+             "cover": {"small": "https://covers.openlibrary.org/b/id/675832-S.jpg",
+                       "medium": "https://covers.openlibrary.org/b/id/675832-M.jpg"}}}
+        """.trimIndent()
+        val result = checkNotNull(client.parseResponse(body, "9780201558029"))
+
+        assertEquals("https://covers.openlibrary.org/b/id/675832-M.jpg", result.coverUrl)
+    }
+
+    /**
+     * Two real books off the user's shelf that the app failed to identify on its
+     * first on-device run, captured verbatim from the live API on 2026-09-09. Both
+     * are small-press (Bethlehem Books) children's historical fiction — the exact
+     * profile we assumed Open Library would be thin on. It isn't: both carry title,
+     * author, publisher and cover art, and neither exposes an `isbn_13` identifier,
+     * which is why the lookup ISBN has to survive as the fallback. Whatever went
+     * wrong on the phone, it was NOT this parser and NOT Open Library's coverage.
+     */
+    @Test
+    fun `parses the real responses for the two books the app failed to identify`() {
+        val hittite = checkNotNull(
+            client.parseResponse(fixture("openlibrary_hittite_warrior.json"), "9781883937386"),
+        )
+        assertEquals("Hittite warrior", hittite.title)
+        assertEquals(listOf("Joanne S. Williamson"), hittite.authors)
+        assertEquals("Bethlehem Books", hittite.publisher)
+        assertEquals(237, hittite.pageCount)
+        assertEquals("1883937388", hittite.isbn10)
+        // No isbn_13 in the record — the ISBN we looked up has to carry through.
+        assertEquals("9781883937386", hittite.isbn13)
+        assertEquals("https://covers.openlibrary.org/b/id/930599-L.jpg", hittite.coverUrl)
+
+        val shadowHawk = checkNotNull(
+            client.parseResponse(fixture("openlibrary_shadow_hawk.json"), "9781883937676"),
+        )
+        assertEquals("Shadow hawk", shadowHawk.title)
+        assertEquals(listOf("Andre Norton"), shadowHawk.authors)
+        assertEquals("9781883937676", shadowHawk.isbn13)
+        checkNotNull(shadowHawk.coverUrl)
     }
 
     @Test
@@ -44,6 +105,47 @@ class OpenLibraryClientTest {
         assertNull(client.parseResponse(body, "9780201558029"))
     }
 
+    // --- classify(): the three-way per-source outcome (SPEC.md "Book metadata lookup"). ---
+
+    @Test
+    fun `classify reports Found for a 2xx response with a record`() {
+        val result = client.classify(200, fixture("openlibrary_success.json"), "9780201558029")
+
+        val found = result as? SourceResult.Found
+        checkNotNull(found) { "expected Found, got $result" }
+        assertEquals("Concrete Mathematics", found.metadata.title)
+    }
+
+    @Test
+    fun `classify reports NotFound for a 2xx response with no record for that isbn`() {
+        val result = client.classify(200, fixture("openlibrary_not_found.json"), "9780201558029")
+        assertEquals(SourceResult.NotFound, result)
+    }
+
+    @Test
+    fun `classify reports Failed for a 404`() {
+        val result = client.classify(404, null, "9780201558029")
+        assertEquals(SourceResult.Failed("http 404", FailureKind.CLIENT_ERROR), result)
+    }
+
+    @Test
+    fun `classify reports Failed for a 429, distinctly from NotFound`() {
+        val result = client.classify(429, null, "9780201558029")
+        assertEquals(SourceResult.Failed("http 429 (rate limited)", FailureKind.RATE_LIMITED), result)
+    }
+
+    @Test
+    fun `classify reports Failed for a 500`() {
+        val result = client.classify(500, "Internal Server Error", "9780201558029")
+        assertEquals(SourceResult.Failed("http 500 (server error)", FailureKind.SERVER_ERROR), result)
+    }
+
+    @Test
+    fun `classify reports Failed for a malformed body even on a 2xx status`() {
+        val result = client.classify(200, fixture("malformed.json"), "9780201558029")
+        assertEquals(SourceResult.Failed("malformed json", FailureKind.MALFORMED), result)
+    }
+
     private fun fixture(name: String): String =
         checkNotNull(javaClass.classLoader.getResourceAsStream("fixtures/$name")) { "missing fixture $name" }
             .bufferedReader()

app/app/src/test/java/org/modg/bookshelf/data/metadata/RetryPolicyTest.kt

@@ -0,0 +1,191 @@
+package org.modg.bookshelf.data.metadata
+
+import java.io.IOException
+import java.io.InterruptedIOException
+import java.net.ConnectException
+import java.net.SocketException
+import java.net.SocketTimeoutException
+import java.net.UnknownHostException
+import javax.net.ssl.SSLException
+import javax.net.ssl.SSLHandshakeException
+import kotlin.random.Random
+import kotlinx.coroutines.test.runTest
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Covers the retry decision and the loop that acts on it. Every case is driven by
+ * the 2026-09-09 measurement of the live Open Library API recorded in
+ * docs/METADATA-SOURCES.md: fast transient TLS resets (worth repeating) against a
+ * slow but usually-successful long tail (not worth repeating).
+ *
+ * The loop is exercised with an injected clock and sleep, so these assert the real
+ * policy constants with no wall-clock time and no flakiness.
+ */
+class RetryPolicyTest {
+
+    private val transport = SourceResult.Failed("tls connection reset", FailureKind.TRANSPORT)
+    private val found = SourceResult.Found(BookMetadata(title = "Dune"))
+
+    // --- which failures are worth repeating ---
+
+    @Test
+    fun `transport and server errors are retryable`() {
+        assertTrue(RetryPolicy.isRetryable(FailureKind.TRANSPORT))
+        assertTrue(RetryPolicy.isRetryable(FailureKind.SERVER_ERROR))
+    }
+
+    @Test
+    fun `a timeout is not retried -- its budget is already spent`() {
+        assertFalse(RetryPolicy.isRetryable(FailureKind.TIMEOUT))
+    }
+
+    @Test
+    fun `a rate limit is not retried -- hammering a quota is how a block becomes permanent`() {
+        assertFalse(RetryPolicy.isRetryable(FailureKind.RATE_LIMITED))
+    }
+
+    @Test
+    fun `deterministic failures are not retried`() {
+        assertFalse(RetryPolicy.isRetryable(FailureKind.CLIENT_ERROR))
+        assertFalse(RetryPolicy.isRetryable(FailureKind.MALFORMED))
+    }
+
+    // --- the loop ---
+
+    @Test
+    fun `a first-attempt success is returned without retrying`() = runTest {
+        var calls = 0
+        val result = withRetry(sleep = {}) { calls++; found }
+        assertEquals(found, result)
+        assertEquals(1, calls)
+    }
+
+    @Test
+    fun `a transient failure followed by success returns the success`() = runTest {
+        var calls = 0
+        val result = withRetry(sleep = {}) {
+            calls++
+            if (calls == 1) transport else found
+        }
+        assertEquals(found, result)
+        assertEquals(2, calls)
+    }
+
+    @Test
+    fun `retrying stops at MAX_ATTEMPTS and reports how many were made`() = runTest {
+        var calls = 0
+        val result = withRetry(sleep = {}) { calls++; transport }
+        assertEquals(RetryPolicy.MAX_ATTEMPTS, calls)
+        // The attempt count is the whole diagnostic value of the string on a real
+        // phone: one reset and three in a row are different network stories.
+        assertEquals(
+            SourceResult.Failed("tls connection reset, 3 attempts", FailureKind.TRANSPORT),
+            result,
+        )
+    }
+
+    @Test
+    fun `a single failure is reported without an attempt count`() = runTest {
+        val timeout = SourceResult.Failed("timeout", FailureKind.TIMEOUT)
+        var calls = 0
+        val result = withRetry(sleep = {}) { calls++; timeout }
+        assertEquals(1, calls)
+        assertEquals(timeout, result)
+    }
+
+    @Test
+    fun `NotFound is authoritative and is never retried`() = runTest {
+        var calls = 0
+        val result = withRetry(sleep = {}) { calls++; SourceResult.NotFound }
+        assertEquals(SourceResult.NotFound, result)
+        assertEquals(1, calls)
+    }
+
+    @Test
+    fun `an un-retryable failure short-circuits after one attempt`() = runTest {
+        var calls = 0
+        val result = withRetry(sleep = {}) { calls++; SourceResult.fromHttpCode(429) }
+        assertEquals(1, calls)
+        assertEquals(FailureKind.RATE_LIMITED, (result as SourceResult.Failed).kind)
+    }
+
+    @Test
+    fun `the budget stops a new attempt but never cancels one in flight`() = runTest {
+        // Clock jumps past the budget during the first attempt. The result of that
+        // attempt must still be honoured, and no second attempt may start.
+        var now = 0L
+        var calls = 0
+        val result = withRetry(
+            budgetMillis = 1_000L,
+            nowMillis = { now },
+            sleep = {},
+        ) {
+            calls++
+            now += 5_000L
+            transport
+        }
+        assertEquals(1, calls)
+        assertEquals(transport, result)
+    }
+
+    @Test
+    fun `backoff is short and jittered, never zero and never seconds long`() {
+        val r = Random(1234)
+        repeat(200) {
+            val first = RetryPolicy.backoffMillis(2, r)
+            val second = RetryPolicy.backoffMillis(3, r)
+            assertTrue("first retry backoff was $first", first in 250L..349L)
+            assertTrue("second retry backoff was $second", second in 750L..1049L)
+        }
+    }
+
+    // --- exception and status classification ---
+
+    @Test
+    fun `socket timeout and a blown call timeout both classify as TIMEOUT`() {
+        assertEquals(FailureKind.TIMEOUT, SourceResult.fromException(SocketTimeoutException()).kind)
+        // OkHttp reports an exceeded callTimeout as a bare InterruptedIOException.
+        assertEquals(FailureKind.TIMEOUT, SourceResult.fromException(InterruptedIOException()).kind)
+    }
+
+    @Test
+    fun `the observed live failure -- a TLS-stage reset -- classifies as retryable transport`() {
+        val failed = SourceResult.fromException(SSLException("Connection reset by peer"))
+        assertEquals(FailureKind.TRANSPORT, failed.kind)
+        assertTrue(RetryPolicy.isRetryable(failed.kind))
+    }
+
+    @Test
+    fun `each transport exception gets its own reason, not a generic one`() {
+        // The reason string is the only diagnostic we get back from a real phone,
+        // so these must stay distinguishable from each other.
+        val reasons = listOf(
+            SourceResult.fromException(UnknownHostException()).reason,
+            SourceResult.fromException(SSLHandshakeException("h")).reason,
+            SourceResult.fromException(SSLException("r")).reason,
+            SourceResult.fromException(ConnectException()).reason,
+            SourceResult.fromException(SocketException()).reason,
+        )
+        assertEquals(reasons.size, reasons.toSet().size)
+        assertTrue(reasons.none { it.isBlank() })
+    }
+
+    @Test
+    fun `an unrecognised IOException names its own type rather than saying network error`() {
+        val failed = SourceResult.fromException(IOException("boom"))
+        assertEquals(FailureKind.TRANSPORT, failed.kind)
+        assertTrue(failed.reason, failed.reason.contains("IOException"))
+    }
+
+    @Test
+    fun `http statuses map to the kinds that drive retrying`() {
+        assertEquals(FailureKind.RATE_LIMITED, SourceResult.fromHttpCode(429).kind)
+        assertEquals(FailureKind.SERVER_ERROR, SourceResult.fromHttpCode(500).kind)
+        assertEquals(FailureKind.SERVER_ERROR, SourceResult.fromHttpCode(503).kind)
+        assertEquals(FailureKind.CLIENT_ERROR, SourceResult.fromHttpCode(404).kind)
+        assertEquals(FailureKind.CLIENT_ERROR, SourceResult.fromHttpCode(400).kind)
+    }
+}

app/app/src/test/java/org/modg/bookshelf/data/prefs/SettingsStoreTest.kt

@@ -0,0 +1,73 @@
+package org.modg.bookshelf.data.prefs
+
+import androidx.test.core.app.ApplicationProvider
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.test.runTest
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * Covers the "remember the most recently used shelf" feature's persistence layer —
+ * see [org.modg.bookshelf.ui.scan.ScanViewModel] and
+ * [org.modg.bookshelf.ui.detail.DetailViewModel] for the callers that decide *when*
+ * to write, and [org.modg.bookshelf.ui.components.resolveRecentShelf] for how the
+ * picker decides whether the remembered shelf is still offerable.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class SettingsStoreTest {
+
+    private lateinit var settingsStore: SettingsStore
+
+    @Before
+    fun setUp() = runTest {
+        settingsStore = SettingsStore(ApplicationProvider.getApplicationContext())
+        // DataStore's backing file lives in the app's real files dir, which Robolectric
+        // does not reset between test methods in this class — start every test from a
+        // known-clean slate instead of depending on method execution order.
+        settingsStore.clearLastShelfId()
+    }
+
+    @Test
+    fun `last shelf id is null before anything is remembered`() = runTest {
+        assertNull(settingsStore.lastShelfId.first())
+    }
+
+    @Test
+    fun `last shelf id round-trips through the store`() = runTest {
+        settingsStore.setLastShelfId("sh-top")
+
+        assertEquals("sh-top", settingsStore.lastShelfId.first())
+    }
+
+    @Test
+    fun `setting a new last shelf id overwrites the previous one`() = runTest {
+        settingsStore.setLastShelfId("sh-top")
+        settingsStore.setLastShelfId("sh-desk")
+
+        assertEquals("sh-desk", settingsStore.lastShelfId.first())
+    }
+
+    @Test
+    fun `clearLastShelfId drops the remembered shelf`() = runTest {
+        settingsStore.setLastShelfId("sh-top")
+
+        settingsStore.clearLastShelfId()
+
+        assertNull(settingsStore.lastShelfId.first())
+    }
+
+    @Test
+    fun `sign out clears the remembered shelf so it can't leak to the other account`() = runTest {
+        settingsStore.setLastShelfId("sh-top")
+
+        settingsStore.clearAuth()
+
+        assertNull(settingsStore.lastShelfId.first())
+    }
+}

app/app/src/test/java/org/modg/bookshelf/data/repo/AuthRepositoryTest.kt

@@ -0,0 +1,52 @@
+package org.modg.bookshelf.data.repo
+
+import androidx.test.core.app.ApplicationProvider
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.test.runTest
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.modg.bookshelf.data.prefs.SettingsStore
+import org.modg.bookshelf.data.remote.PocketBaseApi
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * Covers the settings-email gap from the wave-4 handoff: Settings used to show the
+ * PocketBase user id because login never persisted the entered email.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class AuthRepositoryTest {
+
+    private lateinit var settingsStore: SettingsStore
+    private lateinit var api: FakePocketBaseApi
+    private lateinit var repository: AuthRepository
+
+    @Before
+    fun setUp() {
+        settingsStore = SettingsStore(ApplicationProvider.getApplicationContext())
+        api = FakePocketBaseApi()
+        repository = AuthRepository(apiProvider = { api as PocketBaseApi }, settingsStore = settingsStore)
+    }
+
+    @Test
+    fun `login persists the entered email so Settings can show it`() = runTest {
+        val result = repository.login(email = "reader@example.com", password = "hunter2")
+
+        assertTrue(result.isSuccess)
+        assertEquals("reader@example.com", settingsStore.userEmail.first())
+    }
+
+    @Test
+    fun `sign out clears the persisted email`() = runTest {
+        repository.login(email = "reader@example.com", password = "hunter2")
+
+        repository.signOut()
+
+        assertNull(settingsStore.userEmail.first())
+    }
+}

app/app/src/test/java/org/modg/bookshelf/ui/components/ShelfPickerSheetPaparazziTest.kt

@@ -0,0 +1,78 @@
+package org.modg.bookshelf.ui.components
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import app.cash.paparazzi.DeviceConfig
+import app.cash.paparazzi.Paparazzi
+import org.junit.Rule
+import org.junit.Test
+import org.modg.bookshelf.data.local.BookcaseEntity
+import org.modg.bookshelf.data.local.ShelfEntity
+import org.modg.bookshelf.data.local.SyncState
+import org.modg.bookshelf.ui.theme.BookshelfTheme
+
+/**
+ * [ShelfPickerSheet]'s grouped picker, replacing the old flat dropdown (SPEC
+ * task: "the state the whole change exists for"). Renders [ShelfPickerContent]
+ * directly rather than the real [androidx.compose.material3.ModalBottomSheet] —
+ * Paparazzi has no real Window/scrim behind a headless sheet, same problem
+ * [org.modg.bookshelf.ui.screens.ScanScreenPaparazziTest]'s class doc describes.
+ * Two bookcases, one of them empty, plus a remembered "Recent" shelf — the
+ * state this whole component exists for.
+ */
+class ShelfPickerSheetPaparazziTest {
+
+    @get:Rule
+    val paparazzi = Paparazzi(deviceConfig = DeviceConfig.PIXEL_6)
+
+    private val livingRoom = BookcaseEntity(
+        id = "bc-living-room", name = "Living Room", note = null, position = 0,
+        createdAt = 1, updatedAt = 1, syncState = SyncState.SYNCED,
+    )
+    private val study = BookcaseEntity(
+        id = "bc-study", name = "Study", note = null, position = 1,
+        createdAt = 1, updatedAt = 1, syncState = SyncState.SYNCED,
+    )
+    private val topShelf = ShelfEntity(
+        id = "sh-top", bookcaseId = livingRoom.id, label = "Top shelf — fiction", position = 0,
+        createdAt = 1, updatedAt = 1, syncState = SyncState.SYNCED,
+    )
+    private val bottomShelf = ShelfEntity(
+        id = "sh-bottom", bookcaseId = livingRoom.id, label = "Bottom shelf — reference", position = 1,
+        createdAt = 1, updatedAt = 1, syncState = SyncState.SYNCED,
+    )
+
+    @Test
+    fun shelfPickerGroupedLight() = snapshotBoth("shelf-picker-grouped") {
+        Content()
+    }
+
+    @Composable
+    private fun Content() = Shell {
+        ShelfPickerContent(
+            bookcases = listOf(livingRoom, study), // "study" has no shelves yet — empty-bookcase state
+            shelves = listOf(topShelf, bottomShelf),
+            selectedShelfId = bottomShelf.id,
+            recentShelfId = topShelf.id, // recent shelf, distinct from the current selection
+            onShelfSelected = {},
+        )
+    }
+
+    @Composable
+    private fun Shell(content: @Composable () -> Unit) {
+        Box(modifier = Modifier.fillMaxWidth()) {
+            Surface(color = MaterialTheme.colorScheme.surface) {
+                content()
+            }
+        }
+    }
+
+    private fun snapshotBoth(name: String, content: @Composable () -> Unit) {
+        paparazzi.snapshot(name = "$name-light") { BookshelfTheme(darkTheme = false) { content() } }
+        paparazzi.snapshot(name = "$name-dark") { BookshelfTheme(darkTheme = true) { content() } }
+    }
+}

app/app/src/test/java/org/modg/bookshelf/ui/components/ShelfPickerSheetTest.kt

@@ -0,0 +1,53 @@
+package org.modg.bookshelf.ui.components
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+import org.modg.bookshelf.data.local.BookcaseEntity
+import org.modg.bookshelf.data.local.ShelfEntity
+import org.modg.bookshelf.data.local.SyncState
+
+/**
+ * [resolveRecentShelf] backs [ShelfPickerSheet]'s "Recent" section: it must be
+ * omitted, not shown dangling, when there is nothing remembered or the
+ * remembered shelf no longer exists (deleted since it was last used).
+ */
+class ShelfPickerSheetTest {
+
+    private val livingRoom = BookcaseEntity(
+        id = "bc-living-room", name = "Living Room", note = null, position = 0,
+        createdAt = 1, updatedAt = 1, syncState = SyncState.SYNCED,
+    )
+    private val topShelf = ShelfEntity(
+        id = "sh-top", bookcaseId = livingRoom.id, label = "Top shelf", position = 0,
+        createdAt = 1, updatedAt = 1, syncState = SyncState.SYNCED,
+    )
+
+    @Test
+    fun `no remembered shelf resolves to null`() {
+        val result = resolveRecentShelf(recentShelfId = null, shelves = listOf(topShelf), bookcases = listOf(livingRoom))
+
+        assertNull(result)
+    }
+
+    @Test
+    fun `a remembered shelf that no longer exists resolves to null`() {
+        val result = resolveRecentShelf(recentShelfId = "sh-deleted", shelves = listOf(topShelf), bookcases = listOf(livingRoom))
+
+        assertNull(result)
+    }
+
+    @Test
+    fun `a remembered shelf whose bookcase was deleted resolves to null`() {
+        val result = resolveRecentShelf(recentShelfId = topShelf.id, shelves = listOf(topShelf), bookcases = emptyList())
+
+        assertNull(result)
+    }
+
+    @Test
+    fun `a remembered shelf that still exists resolves to its shelf and bookcase`() {
+        val result = resolveRecentShelf(recentShelfId = topShelf.id, shelves = listOf(topShelf), bookcases = listOf(livingRoom))
+
+        assertEquals(topShelf to livingRoom, result)
+    }
+}

app/app/src/test/java/org/modg/bookshelf/ui/detail/DetailViewModelTest.kt

@@ -0,0 +1,77 @@
+package org.modg.bookshelf.ui.detail
+
+import androidx.room.Room
+import androidx.test.core.app.ApplicationProvider
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.test.runTest
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.modg.bookshelf.data.local.BookEntity
+import org.modg.bookshelf.data.local.BookshelfDatabase
+import org.modg.bookshelf.data.prefs.SettingsStore
+import org.modg.bookshelf.data.repo.BookRepository
+import org.modg.bookshelf.data.repo.LocationRepository
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * SPEC's "remember the most recently used shelf" from the detail screen's side:
+ * [DetailViewModel.saveLocation] must write a non-null shelf to [SettingsStore],
+ * but "Not shelved" (null) must never overwrite what's already remembered.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class DetailViewModelTest {
+
+    private lateinit var db: BookshelfDatabase
+    private lateinit var settingsStore: SettingsStore
+    private lateinit var viewModel: DetailViewModel
+    private lateinit var book: BookEntity
+    private lateinit var shelfId: String
+
+    @Before
+    fun setUp() = runTest {
+        val context = ApplicationProvider.getApplicationContext<android.content.Context>()
+        db = Room.inMemoryDatabaseBuilder(context, BookshelfDatabase::class.java)
+            .allowMainThreadQueries()
+            .build()
+        settingsStore = SettingsStore(context)
+        val bookRepository = BookRepository(db.bookDao(), context)
+        val locationRepository = LocationRepository(db.bookcaseDao(), db.shelfDao(), db.bookDao())
+        val bookcaseId = locationRepository.createBookcase(name = "Living Room")
+        shelfId = locationRepository.createShelf(bookcaseId, label = "Top shelf")
+        val bookId = bookRepository.createBook(title = "Piranesi")
+        book = checkNotNull(bookRepository.getById(bookId))
+
+        viewModel = DetailViewModel(
+            bookRepository = bookRepository,
+            locationRepository = locationRepository,
+            settingsStore = settingsStore,
+            bookId = bookId,
+        )
+    }
+
+    @After
+    fun tearDown() {
+        db.close()
+    }
+
+    @Test
+    fun `moving a book to a shelf remembers that shelf`() = runTest {
+        viewModel.performSaveLocation(book, shelfId)
+
+        assertEquals(shelfId, settingsStore.lastShelfId.first())
+    }
+
+    @Test
+    fun `marking a book Not shelved does not overwrite the remembered shelf`() = runTest {
+        settingsStore.setLastShelfId(shelfId)
+
+        viewModel.performSaveLocation(book, null)
+
+        assertEquals(shelfId, settingsStore.lastShelfId.first())
+    }
+}

app/app/src/test/java/org/modg/bookshelf/ui/scan/ScanCodeFilterTest.kt

@@ -1,7 +1,6 @@
 package org.modg.bookshelf.ui.scan
 
 import org.junit.Assert.assertEquals
-import org.junit.Assert.assertNull
 import org.junit.Test
 
 class ScanCodeFilterTest {
@@ -9,45 +8,45 @@ class ScanCodeFilterTest {
     @Test
     fun `accepts a checksum-valid isbn13`() {
         val filter = ScanCodeFilter()
-        assertEquals("9780201558029", filter.accept("9780201558029"))
+        assertEquals(ScanOutcome.Isbn("9780201558029"), filter.accept("9780201558029"))
     }
 
     @Test
-    fun `rejects a checksum-invalid isbn13-shaped code`() {
+    fun `rejects a checksum-invalid isbn13-shaped code as not-an-isbn`() {
         val filter = ScanCodeFilter()
-        assertNull(filter.accept("9780201558020"))
+        assertEquals(ScanOutcome.NotAnIsbn("9780201558020"), filter.accept("9780201558020"))
     }
 
     @Test
-    fun `rejects non-book barcode lengths such as EAN-8 or UPC-A`() {
+    fun `rejects non-book barcode lengths such as EAN-8 or UPC-A as not-an-isbn`() {
         val filter = ScanCodeFilter()
-        assertNull(filter.accept("12345670")) // EAN-8 shaped
+        assertEquals(ScanOutcome.NotAnIsbn("12345670"), filter.accept("12345670")) // EAN-8 shaped
-        assertNull(filter.accept("012345678905")) // UPC-A shaped, 12 digits
+        assertEquals(ScanOutcome.NotAnIsbn("012345678905"), filter.accept("012345678905")) // UPC-A shaped, 12 digits
     }
 
     @Test
-    fun `rejects null raw value`() {
+    fun `ignores null raw value`() {
-        assertNull(ScanCodeFilter().accept(null))
+        assertEquals(ScanOutcome.Ignored, ScanCodeFilter().accept(null))
     }
 
     @Test
-    fun `debounces a repeat of the same code within the window`() {
+    fun `debounces a repeat of the same valid code within the window`() {
         var now = 0L
         val filter = ScanCodeFilter(debounceMillis = 2000L, nowMillis = { now })
 
-        assertEquals("9780201558029", filter.accept("9780201558029"))
+        assertEquals(ScanOutcome.Isbn("9780201558029"), filter.accept("9780201558029"))
         now += 500
-        assertNull(filter.accept("9780201558029"))
+        assertEquals(ScanOutcome.Ignored, filter.accept("9780201558029"))
     }
 
     @Test
-    fun `re-emits the same code once the debounce window elapses`() {
+    fun `re-emits the same valid code once the debounce window elapses`() {
         var now = 0L
         val filter = ScanCodeFilter(debounceMillis = 2000L, nowMillis = { now })
 
-        assertEquals("9780201558029", filter.accept("9780201558029"))
+        assertEquals(ScanOutcome.Isbn("9780201558029"), filter.accept("9780201558029"))
         now += 2001
-        assertEquals("9780201558029", filter.accept("9780201558029"))
+        assertEquals(ScanOutcome.Isbn("9780201558029"), filter.accept("9780201558029"))
     }
 
     @Test
@@ -55,9 +54,9 @@ class ScanCodeFilterTest {
         var now = 0L
         val filter = ScanCodeFilter(debounceMillis = 2000L, nowMillis = { now })
 
-        assertEquals("9780201558029", filter.accept("9780201558029"))
+        assertEquals(ScanOutcome.Isbn("9780201558029"), filter.accept("9780201558029"))
         now += 10
-        assertEquals("9780134685991", filter.accept("9780134685991"))
+        assertEquals(ScanOutcome.Isbn("9780134685991"), filter.accept("9780134685991"))
     }
 
     @Test
@@ -65,8 +64,56 @@ class ScanCodeFilterTest {
         var now = 0L
         val filter = ScanCodeFilter(debounceMillis = 2000L, nowMillis = { now })
 
-        assertEquals("9780201558029", filter.accept("9780201558029"))
+        assertEquals(ScanOutcome.Isbn("9780201558029"), filter.accept("9780201558029"))
         filter.reset()
-        assertEquals("9780201558029", filter.accept("9780201558029"))
+        assertEquals(ScanOutcome.Isbn("9780201558029"), filter.accept("9780201558029"))
+    }
+
+    // --- Rejected-code throttle (SPEC.md "Barcode scanning": a non-book barcode sitting
+    // in frame decodes on almost every analyzed frame, so this must not flicker). ---
+
+    @Test
+    fun `a rejected code emits once, then is throttled on every subsequent frame within the window`() {
+        var now = 0L
+        val filter = ScanCodeFilter(debounceMillis = 2000L, nowMillis = { now })
+
+        assertEquals(ScanOutcome.NotAnIsbn("12345670"), filter.accept("12345670"))
+        // Simulate several more analyzed frames, all still within the debounce window.
+        now += 50
+        assertEquals(ScanOutcome.Ignored, filter.accept("12345670"))
+        now += 50
+        assertEquals(ScanOutcome.Ignored, filter.accept("12345670"))
+        now += 1000
+        assertEquals(ScanOutcome.Ignored, filter.accept("12345670"))
+    }
+
+    @Test
+    fun `a rejected code re-emits once the debounce window elapses`() {
+        var now = 0L
+        val filter = ScanCodeFilter(debounceMillis = 2000L, nowMillis = { now })
+
+        assertEquals(ScanOutcome.NotAnIsbn("12345670"), filter.accept("12345670"))
+        now += 2001
+        assertEquals(ScanOutcome.NotAnIsbn("12345670"), filter.accept("12345670"))
+    }
+
+    @Test
+    fun `a rejected code does not suppress a genuinely different valid isbn read right after it`() {
+        var now = 0L
+        val filter = ScanCodeFilter(debounceMillis = 2000L, nowMillis = { now })
+
+        assertEquals(ScanOutcome.NotAnIsbn("12345670"), filter.accept("12345670"))
+        now += 10
+        assertEquals(ScanOutcome.Isbn("9780201558029"), filter.accept("9780201558029"))
+    }
+
+    @Test
+    fun `switching between two different rejected codes does not throttle either`() {
+        var now = 0L
+        val filter = ScanCodeFilter(debounceMillis = 2000L, nowMillis = { now })
+
+        assertEquals(ScanOutcome.NotAnIsbn("12345670"), filter.accept("12345670"))
+        now += 10
+        assertEquals(ScanOutcome.NotAnIsbn("012345678905"), filter.accept("012345678905"))
     }
 }

app/app/src/test/java/org/modg/bookshelf/ui/scan/ScanModelsTest.kt

@@ -5,6 +5,7 @@ import org.junit.Assert.assertTrue
 import org.junit.Test
 import org.modg.bookshelf.data.local.BookEntity
 import org.modg.bookshelf.data.metadata.BookMetadata
+import org.modg.bookshelf.data.metadata.LookupResult
 
 class ScanModelsTest {
 
@@ -25,21 +26,27 @@ class ScanModelsTest {
     }
 
     @Test
-    fun `metadata miss maps to NotFound regardless of duplicate status`() {
+    fun `an authoritative NotFound result maps to NotFound regardless of duplicate status`() {
-        val outcome = ScanMetadataOutcome.from("9780201558029", null, DuplicateStatus.New)
+        val outcome = ScanMetadataOutcome.from("9780201558029", LookupResult.NotFound, DuplicateStatus.New)
         assertEquals(ScanSheetState.NotFound("9780201558029"), outcome)
     }
 
     @Test
-    fun `metadata hit maps to Found carrying the duplicate status through`() {
+    fun `a Found result maps to Found carrying the duplicate status through`() {
         val metadata = BookMetadata(title = "Dune", isbn13 = "9780201558029")
         val duplicate = DuplicateStatus.AlreadyOwned("abc123", "Dune")
 
-        val outcome = ScanMetadataOutcome.from("9780201558029", metadata, duplicate)
+        val outcome = ScanMetadataOutcome.from("9780201558029", LookupResult.Found(metadata), duplicate)
 
         assertEquals(ScanSheetState.Found("9780201558029", metadata, duplicate), outcome)
     }
 
+    @Test
+    fun `an Unavailable result maps to LookupFailed and never claims the book is unknown`() {
+        val outcome = ScanMetadataOutcome.from("9780201558029", LookupResult.Unavailable("http 429"), DuplicateStatus.New)
+        assertEquals(ScanSheetState.LookupFailed("9780201558029", "http 429"), outcome)
+    }
+
     @Test
     fun `session count starts at zero and increments per save, not per skip`() {
         var session = ScanSessionState()

app/app/src/test/java/org/modg/bookshelf/ui/scan/ScanViewModelTest.kt

@@ -0,0 +1,100 @@
+package org.modg.bookshelf.ui.scan
+
+import androidx.room.Room
+import androidx.test.core.app.ApplicationProvider
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.test.runTest
+import kotlinx.serialization.json.Json
+import okhttp3.OkHttpClient
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.modg.bookshelf.data.local.BookshelfDatabase
+import org.modg.bookshelf.data.metadata.BookMetadata
+import org.modg.bookshelf.data.metadata.MetadataRepository
+import org.modg.bookshelf.data.prefs.SettingsStore
+import org.modg.bookshelf.data.repo.BookRepository
+import org.modg.bookshelf.data.repo.LocationRepository
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * SPEC's "remember the most recently used shelf": [ScanViewModel.save] and
+ * [ScanViewModel.saveManualEntry] must write the chosen shelf to [SettingsStore]
+ * so it survives to the next scanning session — except "Not shelved" (null),
+ * which must never overwrite what's already remembered.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+class ScanViewModelTest {
+
+    private lateinit var db: BookshelfDatabase
+    private lateinit var settingsStore: SettingsStore
+    private lateinit var viewModel: ScanViewModel
+    private lateinit var locationRepository: LocationRepository
+    private lateinit var shelfId: String
+
+    @Before
+    fun setUp() = runTest {
+        val context = ApplicationProvider.getApplicationContext<android.content.Context>()
+        db = Room.inMemoryDatabaseBuilder(context, BookshelfDatabase::class.java)
+            .allowMainThreadQueries()
+            .build()
+        settingsStore = SettingsStore(context)
+        locationRepository = LocationRepository(db.bookcaseDao(), db.shelfDao(), db.bookDao())
+        val bookcaseId = locationRepository.createBookcase(name = "Living Room")
+        shelfId = locationRepository.createShelf(bookcaseId, label = "Top shelf")
+
+        viewModel = ScanViewModel(
+            bookRepository = BookRepository(db.bookDao(), context),
+            locationRepository = locationRepository,
+            metadataRepository = MetadataRepository(OkHttpClient(), Json { ignoreUnknownKeys = true }),
+            settingsStore = settingsStore,
+        )
+    }
+
+    @After
+    fun tearDown() {
+        db.close()
+    }
+
+    @Test
+    fun `saving a metadata hit to a shelf remembers that shelf`() = runTest {
+        viewModel.selectShelf(shelfId)
+
+        viewModel.performSave("9780765326355", BookMetadata(title = "The Way of Kings"))
+
+        assertEquals(shelfId, settingsStore.lastShelfId.first())
+    }
+
+    @Test
+    fun `saving a manual entry to a shelf remembers that shelf`() = runTest {
+        viewModel.selectShelf(shelfId)
+
+        viewModel.performSaveManualEntry("9780765326355", "The Way of Kings", listOf("Brandon Sanderson"))
+
+        assertEquals(shelfId, settingsStore.lastShelfId.first())
+    }
+
+    @Test
+    fun `saving as Not shelved does not overwrite the remembered shelf`() = runTest {
+        settingsStore.setLastShelfId(shelfId)
+        viewModel.selectShelf(null)
+
+        viewModel.performSave("9780765326355", BookMetadata(title = "The Way of Kings"))
+
+        assertEquals(shelfId, settingsStore.lastShelfId.first())
+    }
+
+    @Test
+    fun `saving a manual entry as Not shelved does not overwrite the remembered shelf`() = runTest {
+        settingsStore.setLastShelfId(shelfId)
+        viewModel.selectShelf(null)
+
+        viewModel.performSaveManualEntry("9780765326355", "The Way of Kings", emptyList())
+
+        assertEquals(shelfId, settingsStore.lastShelfId.first())
+    }
+}

app/app/src/test/java/org/modg/bookshelf/ui/scan/ScannerControllerTest.kt

@@ -46,6 +46,39 @@ class ScannerControllerTest {
         assertEquals(listOf("9780201558029"), received)
     }
 
+    @Test
+    fun `non-book barcode emits on rejectedCodes, not scanResults`() = runTest {
+        val controller = ScannerController()
+        val scanned = mutableListOf<String>()
+        val rejected = mutableListOf<String>()
+        backgroundScope.launch { controller.scanResults.toList(scanned) }
+        backgroundScope.launch { controller.rejectedCodes.toList(rejected) }
+        runCurrent()
+
+        controller.onBarcodeScanned("012345678905") // UPC-A shaped, fails the ISBN-13 checksum
+        runCurrent()
+
+        assertTrue(scanned.isEmpty())
+        assertEquals(listOf("012345678905"), rejected)
+    }
+
+    @Test
+    fun `a debounced repeat reaches neither scanResults nor rejectedCodes`() = runTest {
+        val controller = ScannerController()
+        val scanned = mutableListOf<String>()
+        val rejected = mutableListOf<String>()
+        backgroundScope.launch { controller.scanResults.toList(scanned) }
+        backgroundScope.launch { controller.rejectedCodes.toList(rejected) }
+        runCurrent()
+
+        controller.onBarcodeScanned("012345678905")
+        controller.onBarcodeScanned("012345678905") // same frame's worth of repeat reads
+        runCurrent()
+
+        assertEquals(listOf("012345678905"), rejected)
+        assertTrue(scanned.isEmpty())
+    }
+
     @Test
     fun `torch toggles from its default off state`() {
         val controller = ScannerController()

app/app/src/test/java/org/modg/bookshelf/ui/screens/DetailScreenPaparazziTest.kt

@@ -0,0 +1,93 @@
+package org.modg.bookshelf.ui.screens
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.outlined.ArrowBack
+import androidx.compose.material.icons.outlined.Delete
+import androidx.compose.material.icons.outlined.Edit
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import app.cash.paparazzi.DeviceConfig
+import app.cash.paparazzi.Paparazzi
+import org.junit.Rule
+import org.junit.Test
+import org.modg.bookshelf.ui.components.BookshelfScaffold
+import org.modg.bookshelf.ui.components.GoldDivider
+import org.modg.bookshelf.ui.components.PaperSurface
+import org.modg.bookshelf.ui.detail.BookHeader
+import org.modg.bookshelf.ui.detail.DescriptionSection
+import org.modg.bookshelf.ui.detail.LocationSection
+import org.modg.bookshelf.ui.detail.NotesSection
+import org.modg.bookshelf.ui.theme.BookshelfTheme
+
+/**
+ * SPEC.md "detail" screen — big cover, metadata, collapsible description,
+ * editable notes, location picker. Rebuilds [org.modg.bookshelf.ui.detail.DetailScreen]'s
+ * shell around its own real internal sections ([BookHeader], [DescriptionSection],
+ * [NotesSection], [LocationSection]) with [ScreenFixtures.detailBook], per the
+ * pattern in [ScreenFixtures].
+ */
+class DetailScreenPaparazziTest {
+
+    @get:Rule
+    val paparazzi = Paparazzi(deviceConfig = DeviceConfig.PIXEL_6)
+
+    @Test
+    fun detailPopulatedLight() = snapshotBoth("detail-populated") { Populated() }
+
+    @Composable
+    private fun Populated() = Shell()
+
+    @Composable
+    private fun Shell() {
+        val book = ScreenFixtures.detailBook
+        BookshelfScaffold(
+            title = book.title,
+            navigationIcon = {
+                IconButton(onClick = {}) { Icon(Icons.AutoMirrored.Outlined.ArrowBack, contentDescription = "Back") }
+            },
+            actions = {
+                IconButton(onClick = {}) { Icon(Icons.Outlined.Edit, contentDescription = "Edit") }
+                IconButton(onClick = {}) { Icon(Icons.Outlined.Delete, contentDescription = "Delete") }
+            },
+        ) { innerPadding ->
+            PaperSurface(modifier = Modifier.fillMaxSize()) {
+                Column(
+                    modifier = Modifier
+                        .padding(innerPadding)
+                        .fillMaxSize()
+                        .verticalScroll(rememberScrollState())
+                        .padding(16.dp),
+                ) {
+                    BookHeader(book = book)
+                    GoldDivider(modifier = Modifier.padding(vertical = 16.dp))
+                    DescriptionSection(description = book.description)
+
+                    GoldDivider(modifier = Modifier.padding(vertical = 16.dp))
+                    NotesSection(book = book, onSave = {})
+
+                    GoldDivider(modifier = Modifier.padding(vertical = 16.dp))
+                    LocationSection(
+                        book = book,
+                        bookcases = ScreenFixtures.bookcases,
+                        shelves = ScreenFixtures.shelves,
+                        recentShelfId = null,
+                        onShelfSelected = {},
+                    )
+                }
+            }
+        }
+    }
+
+    private fun snapshotBoth(name: String, content: @Composable () -> Unit) {
+        paparazzi.snapshot(name = "$name-light") { BookshelfTheme(darkTheme = false) { content() } }
+        paparazzi.snapshot(name = "$name-dark") { BookshelfTheme(darkTheme = true) { content() } }
+    }
+}

app/app/src/test/java/org/modg/bookshelf/ui/screens/LocationsScreenPaparazziTest.kt

@@ -0,0 +1,108 @@
+package org.modg.bookshelf.ui.screens
+
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Add
+import androidx.compose.material.icons.filled.ArrowBack
+import androidx.compose.material3.FloatingActionButton
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import app.cash.paparazzi.DeviceConfig
+import app.cash.paparazzi.Paparazzi
+import org.junit.Rule
+import org.junit.Test
+import org.modg.bookshelf.data.local.BookcaseEntity
+import org.modg.bookshelf.ui.components.BookshelfScaffold
+import org.modg.bookshelf.ui.components.GoldDivider
+import org.modg.bookshelf.ui.components.PaperSurface
+import org.modg.bookshelf.ui.locations.BookcaseRow
+import org.modg.bookshelf.ui.locations.BookcaseUi
+import org.modg.bookshelf.ui.locations.ShelfUi
+import org.modg.bookshelf.ui.theme.BookshelfTheme
+
+/**
+ * SPEC.md "locations" screen — bookcases -> shelves tree with per-shelf book
+ * counts. Rebuilds [org.modg.bookshelf.ui.locations.LocationsScreen]'s shell
+ * around its own real [BookcaseRow] (which nests the real `ShelfRow`), fed
+ * counts derived from [ScreenFixtures.books], per the pattern in [ScreenFixtures].
+ */
+class LocationsScreenPaparazziTest {
+
+    @get:Rule
+    val paparazzi = Paparazzi(deviceConfig = DeviceConfig.PIXEL_6)
+
+    @Test
+    fun locationsPopulatedLight() = snapshotBoth("locations-populated") { Populated() }
+
+    /**
+     * Regression coverage for the ghost-bookcase bug: with the list branch not
+     * folding in the Scaffold's top app bar inset, a single bookcase's row
+     * rendered underneath the app bar and was invisible. This renders exactly
+     * that one-bookcase state; check the recorded PNG shows the bookcase row
+     * fully below the app bar, not clipped/hidden behind it.
+     */
+    @Test
+    fun locationsSingleBookcaseLight() = snapshotBoth("locations-single-bookcase") { SingleBookcase() }
+
+    @Composable
+    private fun Populated() = Shell(ScreenFixtures.bookcases)
+
+    @Composable
+    private fun SingleBookcase() = Shell(listOf(ScreenFixtures.livingRoom))
+
+    @Composable
+    private fun Shell(bookcases: List<BookcaseEntity>) {
+        val bookcaseUis = bookcases.map { bookcase ->
+            BookcaseUi(
+                bookcase = bookcase,
+                shelves = ScreenFixtures.shelves
+                    .filter { it.bookcaseId == bookcase.id }
+                    .map { shelf -> ShelfUi(shelf, ScreenFixtures.books.count { it.shelfId == shelf.id }) },
+            )
+        }
+
+        BookshelfScaffold(
+            title = "Locations",
+            navigationIcon = {
+                IconButton(onClick = {}) { Icon(Icons.Filled.ArrowBack, contentDescription = "Back") }
+            },
+            floatingActionButton = {
+                FloatingActionButton(onClick = {}) { Icon(Icons.Filled.Add, contentDescription = "Add bookcase") }
+            },
+        ) { innerPadding ->
+            PaperSurface(modifier = Modifier.fillMaxWidth()) {
+                LazyColumn(contentPadding = PaddingValues(top = innerPadding.calculateTopPadding(), bottom = 96.dp)) {
+                    items(bookcaseUis, key = { it.bookcase.id }) { bookcaseUi ->
+                        BookcaseRow(
+                            bookcaseUi = bookcaseUi,
+                            onEdit = {},
+                            onDelete = {},
+                            onMoveUp = {},
+                            onMoveDown = {},
+                            onAddShelf = {},
+                            onShelfClick = {},
+                            onEditShelf = {},
+                            onDeleteShelf = {},
+                            onMoveShelfBooks = {},
+                            onShelfMoveUp = {},
+                            onShelfMoveDown = {},
+                        )
+                        GoldDivider(modifier = Modifier.padding(vertical = 4.dp))
+                    }
+                }
+            }
+        }
+    }
+
+    private fun snapshotBoth(name: String, content: @Composable () -> Unit) {
+        paparazzi.snapshot(name = "$name-light") { BookshelfTheme(darkTheme = false) { content() } }
+        paparazzi.snapshot(name = "$name-dark") { BookshelfTheme(darkTheme = true) { content() } }
+    }
+}

app/app/src/test/java/org/modg/bookshelf/ui/screens/ScanScreenPaparazziTest.kt

@@ -0,0 +1,179 @@
+package org.modg.bookshelf.ui.screens
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.outlined.ArrowBack
+import androidx.compose.material.icons.outlined.FlashOff
+import androidx.compose.material.icons.outlined.Keyboard
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.dp
+import app.cash.paparazzi.DeviceConfig
+import app.cash.paparazzi.Paparazzi
+import org.junit.Rule
+import org.junit.Test
+import org.modg.bookshelf.data.metadata.BookMetadata
+import org.modg.bookshelf.ui.components.BookshelfScaffold
+import org.modg.bookshelf.ui.scan.DuplicateStatus
+import org.modg.bookshelf.ui.scan.FoundBookSheet
+import org.modg.bookshelf.ui.scan.LookupFailedSheet
+import org.modg.bookshelf.ui.scan.RejectedBarcodeBanner
+import org.modg.bookshelf.ui.scan.ScanReticle
+import org.modg.bookshelf.ui.scan.SearchingSheet
+import org.modg.bookshelf.ui.scan.SessionBadge
+import org.modg.bookshelf.ui.theme.BookshelfTheme
+
+/**
+ * SPEC.md "scan" screen — camera + reticle, on-hit bottom sheet.
+ *
+ * Paparazzi has no real camera: [org.modg.bookshelf.ui.scan.ScanScreen]'s
+ * `CameraPreview` binds a live `ProcessCameraProvider`/`PreviewView`, which
+ * cannot run headless (same class of problem [ScreenFixtures] documents for
+ * Room/OkHttp). So this renders the screen's real overlay pieces — [ScanReticle],
+ * [SessionBadge], and the real [FoundBookSheet] — over a plain dark backdrop
+ * standing in for the live viewfinder, per the wave-4 task instructions.
+ */
+class ScanScreenPaparazziTest {
+
+    @get:Rule
+    val paparazzi = Paparazzi(deviceConfig = DeviceConfig.PIXEL_6)
+
+    @Test
+    fun scanReticleLight() = snapshotBoth("scan-reticle") { ReticleOverlay() }
+
+    @Test
+    fun scanFoundSheetLight() = snapshotBoth("scan-found-sheet") { FoundSheetOverlay() }
+
+    /** The state between "barcode decoded" and "metadata back" — see [SearchingSheet]. */
+    @Test
+    fun scanSearchingSheetLight() = snapshotBoth("scan-searching-sheet") { SearchingSheetOverlay() }
+
+    /** Neither source could be reached — see [LookupFailedSheet]. Must not read as "not found". */
+    @Test
+    fun scanLookupFailedSheetLight() = snapshotBoth("scan-lookup-failed-sheet") { LookupFailedSheetOverlay() }
+
+    /** A decoded barcode that failed the ISBN-13 checksum — see [RejectedBarcodeBanner]. */
+    @Test
+    fun scanRejectedBarcodeLight() = snapshotBoth("scan-rejected-barcode") { RejectedBarcodeOverlay() }
+
+    @Composable
+    private fun ReticleOverlay() = Shell {
+        Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+            ScanReticle(modifier = Modifier.align(Alignment.Center))
+            SessionBadge(count = 3, modifier = Modifier.align(Alignment.TopCenter).padding(16.dp))
+        }
+    }
+
+    @Composable
+    private fun FoundSheetOverlay() = Shell {
+        Box(modifier = Modifier.fillMaxSize()) {
+            Surface(
+                modifier = Modifier.align(Alignment.BottomCenter).fillMaxWidth(),
+                shape = RoundedCornerShape(topStart = 16.dp, topEnd = 16.dp),
+                color = MaterialTheme.colorScheme.surface,
+            ) {
+                FoundBookSheet(
+                    metadata = BookMetadata(
+                        isbn13 = "9780765326355",
+                        title = "The Way of Kings",
+                        authors = listOf("Brandon Sanderson"),
+                        publisher = "Tor",
+                        publishedDate = "2010",
+                        pageCount = 1007,
+                    ),
+                    duplicate = DuplicateStatus.New,
+                    bookcases = ScreenFixtures.bookcases,
+                    shelves = ScreenFixtures.shelves,
+                    selectedShelfId = ScreenFixtures.deskShelf.id,
+                    recentShelfId = null,
+                    onShelfSelected = {},
+                    onSave = {},
+                    onSkip = {},
+                )
+            }
+        }
+    }
+
+    @Composable
+    private fun SearchingSheetOverlay() = Shell {
+        Box(modifier = Modifier.fillMaxSize()) {
+            Surface(
+                modifier = Modifier.align(Alignment.BottomCenter).fillMaxWidth(),
+                shape = RoundedCornerShape(topStart = 16.dp, topEnd = 16.dp),
+                color = MaterialTheme.colorScheme.surface,
+            ) {
+                SearchingSheet(isbn13 = "9780765326355")
+            }
+        }
+    }
+
+    @Composable
+    private fun LookupFailedSheetOverlay() = Shell {
+        Box(modifier = Modifier.fillMaxSize()) {
+            Surface(
+                modifier = Modifier.align(Alignment.BottomCenter).fillMaxWidth(),
+                shape = RoundedCornerShape(topStart = 16.dp, topEnd = 16.dp),
+                color = MaterialTheme.colorScheme.surface,
+            ) {
+                LookupFailedSheet(
+                    isbn13 = "9780765326355",
+                    reason = "open library: network error; google books: http 429",
+                    onRetry = {},
+                    onEnterByHand = {},
+                    onSkip = {},
+                )
+            }
+        }
+    }
+
+    @Composable
+    private fun RejectedBarcodeOverlay() = Shell {
+        Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+            ScanReticle(modifier = Modifier.align(Alignment.Center))
+            RejectedBarcodeBanner(
+                message = "Read 012345678905 — not a book barcode",
+                modifier = Modifier.align(Alignment.BottomCenter).padding(24.dp),
+            )
+        }
+    }
+
+    @Composable
+    private fun Shell(overlay: @Composable () -> Unit) {
+        BookshelfScaffold(
+            title = "Scan",
+            navigationIcon = {
+                IconButton(onClick = {}) { Icon(Icons.AutoMirrored.Outlined.ArrowBack, contentDescription = "Back") }
+            },
+            actions = {
+                IconButton(onClick = {}) { Icon(Icons.Outlined.FlashOff, contentDescription = "Toggle flashlight") }
+                IconButton(onClick = {}) { Icon(Icons.Outlined.Keyboard, contentDescription = "Enter ISBN manually") }
+            },
+        ) { innerPadding ->
+            Box(
+                modifier = Modifier
+                    .padding(innerPadding)
+                    .fillMaxSize()
+                    // Static stand-in for the live CameraX viewfinder — see class doc.
+                    .background(Color(0xFF1A1A1A)),
+            ) {
+                overlay()
+            }
+        }
+    }
+
+    private fun snapshotBoth(name: String, content: @Composable () -> Unit) {
+        paparazzi.snapshot(name = "$name-light") { BookshelfTheme(darkTheme = false) { content() } }
+        paparazzi.snapshot(name = "$name-dark") { BookshelfTheme(darkTheme = true) { content() } }
+    }
+}

app/app/src/test/java/org/modg/bookshelf/ui/screens/SettingsScreenPaparazziTest.kt

@@ -0,0 +1,89 @@
+package org.modg.bookshelf.ui.screens
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.ArrowBack
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import app.cash.paparazzi.DeviceConfig
+import app.cash.paparazzi.Paparazzi
+import org.junit.Rule
+import org.junit.Test
+import org.modg.bookshelf.ui.components.BookshelfScaffold
+import org.modg.bookshelf.ui.components.GoldDivider
+import org.modg.bookshelf.ui.components.PaperSurface
+import org.modg.bookshelf.ui.components.PrimaryButton
+import org.modg.bookshelf.ui.components.SecondaryButton
+import org.modg.bookshelf.ui.components.SyncStatus
+import org.modg.bookshelf.ui.components.SyncStatusBar
+import org.modg.bookshelf.ui.settings.InfoRow
+import org.modg.bookshelf.ui.settings.SectionHeading
+import org.modg.bookshelf.ui.settings.formatLastSync
+import org.modg.bookshelf.ui.theme.BookshelfTheme
+
+/**
+ * SPEC.md "settings" screen — server, account (now showing the signed-in
+ * email per the wave-4 fix), sync status, book/cover counts. Rebuilds
+ * [org.modg.bookshelf.ui.settings.SettingsScreen]'s shell around its own real
+ * [SectionHeading]/[InfoRow]/[formatLastSync], per the pattern in [ScreenFixtures].
+ */
+class SettingsScreenPaparazziTest {
+
+    @get:Rule
+    val paparazzi = Paparazzi(deviceConfig = DeviceConfig.PIXEL_6)
+
+    @Test
+    fun settingsPopulatedLight() = snapshotBoth("settings-populated") { Populated() }
+
+    @Composable
+    private fun Populated() = Shell()
+
+    @Composable
+    private fun Shell() {
+        val lastSync = System.currentTimeMillis() - 2 * 60 * 1000L
+        BookshelfScaffold(
+            title = "Settings",
+            navigationIcon = {
+                IconButton(onClick = {}) { Icon(Icons.Filled.ArrowBack, contentDescription = "Back") }
+            },
+            syncStatusBar = {
+                SyncStatusBar(status = SyncStatus.Synced, label = "Synced • ${formatLastSync(lastSync)}")
+            },
+        ) { innerPadding ->
+            PaperSurface(modifier = Modifier.fillMaxWidth()) {
+                Column(modifier = Modifier.padding(innerPadding).padding(16.dp)) {
+                    SectionHeading("Server")
+                    InfoRow(label = "URL", value = "https://library.montanaro.home")
+
+                    GoldDivider(modifier = Modifier.padding(vertical = 16.dp))
+
+                    SectionHeading("Account")
+                    InfoRow(label = "Signed in as", value = "reader@example.com")
+                    SecondaryButton(text = "Sign out", onClick = {}, modifier = Modifier.padding(top = 8.dp))
+
+                    GoldDivider(modifier = Modifier.padding(vertical = 16.dp))
+
+                    SectionHeading("Sync")
+                    InfoRow(label = "Last synced", value = formatLastSync(lastSync))
+                    PrimaryButton(text = "Sync now", onClick = {}, modifier = Modifier.padding(top = 8.dp))
+
+                    GoldDivider(modifier = Modifier.padding(vertical = 16.dp))
+
+                    SectionHeading("Library")
+                    InfoRow(label = "Books", value = ScreenFixtures.books.size.toString())
+                    InfoRow(label = "Covers", value = "0")
+                }
+            }
+        }
+    }
+
+    private fun snapshotBoth(name: String, content: @Composable () -> Unit) {
+        paparazzi.snapshot(name = "$name-light") { BookshelfTheme(darkTheme = false) { content() } }
+        paparazzi.snapshot(name = "$name-dark") { BookshelfTheme(darkTheme = true) { content() } }
+    }
+}

app/app/src/test/java/org/modg/bookshelf/ui/screens/SetupScreenPaparazziTest.kt

@@ -0,0 +1,140 @@
+package org.modg.bookshelf.ui.screens
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.input.PasswordVisualTransformation
+import androidx.compose.ui.unit.dp
+import app.cash.paparazzi.DeviceConfig
+import app.cash.paparazzi.Paparazzi
+import org.junit.Rule
+import org.junit.Test
+import org.modg.bookshelf.ui.components.GoldDivider
+import org.modg.bookshelf.ui.components.PaperSurface
+import org.modg.bookshelf.ui.components.PrimaryButton
+import org.modg.bookshelf.ui.theme.BookshelfTheme
+
+/**
+ * SPEC.md "setup" screen — first run, server URL + email + password.
+ * [org.modg.bookshelf.ui.setup.SetupScreen] wires everything straight to
+ * [org.modg.bookshelf.ui.setup.SetupViewModel] with no internal presentational
+ * split, so per [ScreenFixtures]'s established approach this rebuilds the same
+ * layout inline with plain, filled-in state instead of driving a real
+ * ViewModel (whose reachability probe builds an OkHttpClient — see
+ * [ScreenFixtures] for why that blows up under Paparazzi).
+ */
+class SetupScreenPaparazziTest {
+
+    @get:Rule
+    val paparazzi = Paparazzi(deviceConfig = DeviceConfig.PIXEL_6)
+
+    @Test
+    fun setupFilledLight() = snapshotBoth("setup-filled") { Filled() }
+
+    @Composable
+    private fun Filled() = Shell(
+        serverUrl = "https://library.montanaro.home",
+        email = "reader@example.com",
+        password = "hunter2",
+        urlError = null,
+        credentialsError = null,
+    )
+
+    @Composable
+    private fun Shell(
+        serverUrl: String,
+        email: String,
+        password: String,
+        urlError: String?,
+        credentialsError: String?,
+    ) {
+        PaperSurface(modifier = Modifier.fillMaxSize()) {
+            Column(
+                modifier = Modifier
+                    .fillMaxSize()
+                    .verticalScroll(rememberScrollState())
+                    .padding(24.dp),
+                verticalArrangement = Arrangement.Center,
+            ) {
+                Text(text = "Bookshelf", style = MaterialTheme.typography.displaySmall)
+                Text(
+                    text = "Connect to your home library server to get started.",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 8.dp, bottom = 24.dp),
+                )
+
+                OutlinedTextField(
+                    value = serverUrl,
+                    onValueChange = {},
+                    label = { Text("Server URL") },
+                    placeholder = { Text("https://library.example.com") },
+                    singleLine = true,
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Uri),
+                    isError = urlError != null,
+                    modifier = Modifier.fillMaxWidth(),
+                )
+                if (urlError != null) {
+                    Text(
+                        text = urlError,
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.error,
+                        modifier = Modifier.padding(top = 4.dp),
+                    )
+                }
+
+                GoldDivider(modifier = Modifier.padding(vertical = 16.dp))
+
+                OutlinedTextField(
+                    value = email,
+                    onValueChange = {},
+                    label = { Text("Email") },
+                    singleLine = true,
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Email),
+                    isError = credentialsError != null,
+                    modifier = Modifier.fillMaxWidth().padding(top = 8.dp),
+                )
+                OutlinedTextField(
+                    value = password,
+                    onValueChange = {},
+                    label = { Text("Password") },
+                    singleLine = true,
+                    visualTransformation = PasswordVisualTransformation(),
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+                    isError = credentialsError != null,
+                    modifier = Modifier.fillMaxWidth().padding(top = 8.dp),
+                )
+                if (credentialsError != null) {
+                    Text(
+                        text = credentialsError,
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.error,
+                        modifier = Modifier.padding(top = 4.dp),
+                    )
+                }
+
+                PrimaryButton(
+                    text = "Sign in",
+                    onClick = {},
+                    modifier = Modifier.padding(top = 24.dp),
+                )
+            }
+        }
+    }
+
+    private fun snapshotBoth(name: String, content: @Composable () -> Unit) {
+        paparazzi.snapshot(name = "$name-light") { BookshelfTheme(darkTheme = false) { content() } }
+        paparazzi.snapshot(name = "$name-dark") { BookshelfTheme(darkTheme = true) { content() } }
+    }
+}

app/app/src/test/resources/fixtures/openlibrary_hittite_warrior.json

@@ -0,0 +1 @@
+{"ISBN:9781883937386": {"url": "http://openlibrary.org/books/OL395004M/Hittite_warrior", "key": "/books/OL395004M", "title": "Hittite warrior", "authors": [{"url": "http://openlibrary.org/authors/OL244960A/Joanne_S._Williamson", "name": "Joanne S. Williamson"}], "number_of_pages": 237, "pagination": "xvii, 237 p. ;", "by_statement": "Joanne Williamson.", "identifiers": {"goodreads": ["613497"], "librarything": ["33463"], "isbn_10": ["1883937388"], "lccn": ["98073485"], "openlibrary": ["OL395004M"]}, "classifications": {"lc_classifications": ["PZ7.W672 Hi 1999"], "dewey_decimal_class": ["[Fic]"]}, "publishers": [{"name": "Bethlehem Books"}], "publish_places": [{"name": "Warsaw, ND"}], "publish_date": "1999", "subjects": [{"name": "Bible", "url": "https://openlibrary.org/subjects/bible"}, {"name": "Canaanites", "url": "https://openlibrary.org/subjects/canaanites"}, {"name": "Fiction", "url": "https://openlibrary.org/subjects/fiction"}, {"name": "History", "url": "https://openlibrary.org/subjects/history"}, {"name": "History of Biblical events", "url": "https://openlibrary.org/subjects/history_of_biblical_events"}, {"name": "Jews", "url": "https://openlibrary.org/subjects/jews"}, {"name": "Juvenile fiction", "url": "https://openlibrary.org/subjects/juvenile_fiction"}, {"name": "Hittites", "url": "https://openlibrary.org/subjects/hittites"}, {"name": "Middle east, history", "url": "https://openlibrary.org/subjects/middle_east,_history"}, {"name": "Juvenile Fiction", "url": "https://openlibrary.org/subjects/juvenile_fiction"}], "subject_places": [{"name": "Palestine", "url": "https://openlibrary.org/subjects/place:palestine"}], "subject_people": [{"name": "Barak (Biblical figure)", "url": "https://openlibrary.org/subjects/person:barak_(biblical_figure)"}, {"name": "Deborah (Biblical judge)", "url": "https://openlibrary.org/subjects/person:deborah_(biblical_judge)"}, {"name": "Sisera (Biblical figure)", "url": "https://openlibrary.org/subjects/person:sisera_(biblical_figure)"}], "subject_times": [{"name": "To 70 A.D.", "url": "https://openlibrary.org/subjects/time:to_70_a.d."}], "notes": "\"Ages 10-up\"--P. 4 of cover.", "ebooks": [{"preview_url": "https://archive.org/details/hittitewarrior00will", "availability": "borrow", "formats": {}, "borrow_url": "https://openlibrary.org/books/OL395004M/Hittite_warrior/borrow", "checkedout": true}], "cover": {"small": "https://covers.openlibrary.org/b/id/930599-S.jpg", "medium": "https://covers.openlibrary.org/b/id/930599-M.jpg", "large": "https://covers.openlibrary.org/b/id/930599-L.jpg"}}}

app/app/src/test/resources/fixtures/openlibrary_shadow_hawk.json

@@ -0,0 +1 @@
+{"ISBN:9781883937676": {"url": "http://openlibrary.org/books/OL3958151M/Shadow_hawk", "key": "/books/OL3958151M", "title": "Shadow hawk", "authors": [{"url": "http://openlibrary.org/authors/OL27951A/Andre_Norton", "name": "Andre Norton"}], "number_of_pages": 246, "pagination": "246 p. ;", "by_statement": "Andre Norton.", "identifiers": {"librarything": ["34114"], "goodreads": ["83108"], "isbn_10": ["1883937671"], "lccn": ["2001092576"], "oclc": ["52047589"], "openlibrary": ["OL3958151M"]}, "classifications": {"lc_classifications": ["PZ7.N82 Sh 2001"], "dewey_decimal_class": ["[Fic]"]}, "publishers": [{"name": "Bethlehem Books"}, {"name": "Ignatius Press"}], "publish_places": [{"name": "Bathgate, N.D"}, {"name": "San Francisco"}], "publish_date": "2001", "subjects": [{"name": "History", "url": "https://openlibrary.org/subjects/history"}, {"name": "Juvenile fiction", "url": "https://openlibrary.org/subjects/juvenile_fiction"}, {"name": "Egypt in fiction", "url": "https://openlibrary.org/subjects/egypt_in_fiction"}, {"name": "Fiction", "url": "https://openlibrary.org/subjects/fiction"}, {"name": "Children's stories", "url": "https://openlibrary.org/subjects/children's_stories"}, {"name": "Egypt -- History -- To 332 B.C. -- Juvenile fiction.", "url": "https://openlibrary.org/subjects/egypt_--_history_--_to_332_b.c._--_juvenile_fiction."}, {"name": "Fiction, science fiction, general", "url": "https://openlibrary.org/subjects/fiction,_science_fiction,_general"}], "subject_places": [{"name": "Egypt", "url": "https://openlibrary.org/subjects/place:egypt"}], "subject_times": [{"name": "To 332 B.C.", "url": "https://openlibrary.org/subjects/time:to_332_b.c."}], "ebooks": [{"preview_url": "https://archive.org/details/shadowhawk0000nort", "availability": "borrow", "formats": {}, "borrow_url": "https://openlibrary.org/books/OL3958151M/Shadow_hawk/borrow", "checkedout": false}], "cover": {"small": "https://covers.openlibrary.org/b/id/930617-S.jpg", "medium": "https://covers.openlibrary.org/b/id/930617-M.jpg", "large": "https://covers.openlibrary.org/b/id/930617-L.jpg"}}}

docs/HANDOFF.md

@@ -230,3 +230,271 @@ Commit `a022a1b` (32 files, +3081).
 3. No Room foreign keys between books/shelves/bookcases (deliberate, worker C).
 4. No emulator on this box: nothing has ever been *run*, only compiled and unit-tested.
    Paparazzi PNGs are the only evidence of how any of it actually looks.
+
+## Wave 4 — COMPLETE, verified by the orchestrator on 2026-09-08
+This is the last planned wave. All of SPEC's build/verify gates now pass.
+
+| Check | Result |
+|---|---|
+| `./tasks/gw assembleDebug` | **exit 0** |
+| `./tasks/gw testDebugUnitTest` | **exit 0 — 102 tests, 1 skipped, 0 failures, 0 errors** |
+| `./tasks/gw assembleRelease` | **exit 0** |
+| signed APK | `app/app/build/outputs/apk/release/app-release.apk`, 41,777,344 bytes |
+| `apksigner verify --print-certs` | V2 signer `CN=Bookshelf, O=Montanaro` — the real release key, not the debug cert |
+| secrets | `app/release-keystore.jks` + `app/keystore.properties` gitignored and NOT committed — re-verified against the staged file list before committing |
+
+The skipped test is `LiveSyncTest` — opt-in, it needs the live PocketBase. It
+PASSED in wave 4's first half; the cover round-trip gap from wave 3 is closed.
+
+Commits `5455df2` (app work) + `0f47ee9` (orchestration). Pushed to `origin/main`
+(`ssh://git@git.jfmonty2.com:2022/jfmonty2/bookshelf.git`) — the repo now has a
+remote, so pushing after each commit is the norm.
+
+### How wave 4 actually ended — F3 never reported
+F3-release wrote all four deliverables between 20:34 and 20:46 on 09-08 and then
+could not finish. Two separate mechanisms:
+- `claude -p` terminates background tasks after 600s (`Background tasks still
+  running after 600s; terminating. Set CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0 to
+  wait indefinitely.`). F3 had launched `assembleRelease` in the background with a
+  Monitor and ended its turn saying it would report when done — the exact failure
+  its own prompt forbade.
+- It then hit the 5h quota and went into a 600s wait loop, so the service
+  supervisor would have kept re-running verification on finished work indefinitely.
+
+The orchestrator ran the verification itself, wrote `logs/WAVE4-DONE` by hand
+(noting it was NOT written by `service-worker.sh`), and stopped the service.
+**If you launch another worker, set `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` in
+`run-task.sh`, or tell the worker to run builds in the FOREGROUND.** A worker that
+backgrounds a 10-minute Gradle build cannot ever report on it.
+
+### The one thing wave 4 owed and did not deliver
+F3 was asked to say candidly what the rendered screens get WRONG against SPEC's
+design language, now that they can finally be seen. It never reported. **Fourteen
+new PNGs are on disk, unreviewed by anyone.** The user explicitly cares how this
+looks, so this is the top open item — not a build problem, a design-review one:
+`app/app/src/test/snapshots/images/` (setup, detail, scan ×2, locations, settings,
+library, scaffold — each light + dark).
+
+## STATE: what is NOT done (as of 2026-09-08)
+1. **Nobody has looked at the screenshots.** See above. Highest-value next step.
+2. **The app has still never run on a device or emulator** (no KVM on this box).
+   Everything is compile + unit-test + Paparazzi evidence only. Installing the
+   signed APK on a real phone is the only way past this, and it needs the user.
+3. **R8 is off.** Acceptable per F3's prompt, but the release APK is 41.8MB.
+   Turning it on requires proving Room/Retrofit/kotlinx-serialization/ML Kit
+   survive minification.
+4. Still-open user questions, unchanged: where the server will actually live, and
+   the two account emails for `create-user.sh`.
+
+## First on-device test — 2026-09-09
+The user installed the signed APK on a real phone. It runs. This closes the
+"never been run" gap that waves 1-4 all carried. Six issues came back; five were
+fixed directly by the orchestrator in commit `356f639` (they were small, and
+spinning up Sonnet workers for two-line Compose edits costs more than it saves).
+
+**The one worth remembering** — `BookCover` branched on `painter.state`, but in
+coil3 that is a `StateFlow<State>`, not a `State`. Every `is
+AsyncImagePainter.State.X` arm was therefore always false, and because a `when`
+used as a statement needs no `else`, it compiled clean and drew NOTHING — no
+cover, no placeholder, no error icon. Kotlin emitted "Check for instance is
+always 'false'" as a *warning* on four consecutive lines and the build stayed
+green. **Grep the build log for `always 'false'` before accepting a wave**; that
+warning class is a silent-dead-code detector and this build had it for months.
+
+Two more cover defects sat behind it, both verified against the live service:
+- `covers.openlibrary.org/b/isbn/{isbn}-L.jpg` answers **200 with a 43-byte 1x1
+  transparent GIF** for an edition with no art. Any image loader calls that a
+  successful load. Only `?default=false` turns a miss into a 404.
+- OL's DTO synthesized that URL unconditionally, so `MetadataMerger`'s
+  fill-blanks rule could never reach Google Books' thumbnail. The SPEC'd cover
+  fallback was dead code. Cover URLs now come from OL's own `cover` object.
+
+Also fixed: sync bar clipped by rounded display corners (now owns its
+navigation-bar inset, wider horizontal padding, moved into Scaffold's `bottomBar`
+slot); setup screen's Password field hidden behind the IME (`safeDrawingPadding`
+outside `verticalScroll`, plus Next/Next/Done IME actions and
+`windowSoftInputMode=adjustResize`); library card titles reflowed (20sp leading,
+author gets its own 4dp gap); scan sheet now names the ISBN and says
+"Searching…" instead of showing a bare spinner.
+
+| Check | Result |
+|---|---|
+| `./tasks/gw assembleDebug` | exit 0 |
+| `./tasks/gw testDebugUnitTest` | exit 0 — 106 tests, 1 skipped, 0 failures |
+| `./tasks/gw verifyPaparazziDebug` | exit 0 against re-recorded snapshots |
+| `./tasks/gw assembleRelease` | exit 0 — 41,777,376 bytes |
+| `apksigner verify` | V2 signer `CN=Bookshelf, O=Montanaro` — real release key |
+
+### Open, not started: metadata coverage
+The user reported 1 of 3 scans resolving, and asked for **research, not a
+change**. Findings are in `docs/METADATA-SOURCES.md`. Headline: Open Library
+answered 88% of a 60-ISBN sample, keyless Google Books returned **429 on 60 of
+60** requests, and both clients collapse every non-200 into `null` — so a
+rate-limited lookup reaches the user as "No match found." Recommended order is a
+free Google Books API key, then distinguishing "couldn't ask" from "not found",
+then retry/backoff, before adding any new source. **Awaiting the user's decision;
+do not implement unasked.**
+
+## Wave 5 — G-diagnostics: IN FLIGHT, launched 2026-09-09 10:42Z
+Prompt: `tasks/G-diagnostics.txt`. Session id in `logs/G-diagnostics.sid`.
+Lease `bookshelf-wave` held and VERIFIED by `tasks/wave-guard.sh`, sentinel
+`logs/WAVE5-DONE`. Launched from a console the user was about to disconnect, so
+the lease is the only thing keeping the sprite hot — check it first if anything
+looks stalled: `sprite-env curl /v1/tasks` and `tail logs/wave-guard.log`.
+
+**Scope:** make the app distinguish three outcomes it currently conflates —
+barcode-didn't-decode (silent today), lookup-request-failed (reported as "No
+match found"), and genuinely-not-found. SPEC's "Book metadata lookup" and
+"Barcode scanning" sections were rewritten to state the three-way contract
+(`Found` / `NotFound` / `Unavailable`) BEFORE launch, so the worker implements a
+spec rather than inventing one. This is the only wave-5 task; there is no
+parallel worker, so the disjoint-ownership device isn't needed, but the prompt
+still forbids build files and every package outside data.metadata + ui.scan.
+
+**Why this and not more sources:** the two books that failed on the phone
+(9781883937386, 9781883937676) are BOTH fully present in Open Library, with
+cover art, and the app's own parser handles their real responses — there are
+regression fixtures and a test proving it. The coverage hypothesis is dead.
+See `docs/METADATA-SOURCES.md` § "What actually failed". Do not let a future
+worker "fix" this by bolting on a third data source.
+
+**Verify before accepting** (workers self-report optimistically; two of five
+waves over-claimed):
+    cd ~/bookshelf && ./tasks/gw assembleDebug && ./tasks/gw testDebugUnitTest \
+      && ./tasks/gw recordPaparazziDebug && git status --porcelain
+107 tests pass today; the count must go UP and nothing may regress. Also grep the
+build log for `always 'false'` — that warning class silently blanked every book
+cover in this app for months and is now an explicit item in the worker's prompt.
+Then eyeball the two new Paparazzi PNGs (LookupFailed sheet, rejected-barcode
+overlay) — the user cares how this looks and no worker has ever been trusted on
+that.
+
+**Still open, unchanged:** the free Google Books API key (keyless returns 429;
+worth doing on its own merits but no longer the leading theory), R8 still off so
+the release APK is 41.8MB and too large to send over the file channel (30MB cap),
+where the server will live, and the two account emails for `create-user.sh`.
+
+## Wave 5 — G-diagnostics: COMPLETE, verified by the orchestrator 2026-09-09
+Commit `93f972b`. The app now distinguishes barcode-didn't-decode from
+lookup-request-failed from genuinely-not-found; see the commit message and
+`docs/METADATA-SOURCES.md`.
+
+| Check | Result |
+|---|---|
+| `assembleDebug` | exit 0 |
+| `testDebugUnitTest` | exit 0 — **138 tests**, 1 skipped, 0 failures (was 107) |
+| `verifyPaparazziDebug` | exit 0 |
+| `assembleRelease` | exit 0 — 41,793,760 bytes, V2 signer `CN=Bookshelf` |
+| boundary check | clean — no build files, no forbidden packages |
+| `grep "always 'false'"` | 0 hits on touched files |
+
+The worker was honest this time: everything it claimed checked out. Cost $0.28,
+6 turns, one quota wait that `run-task.sh` resumed correctly.
+
+**The orchestrator added one thing the worker's brief didn't cover:** the
+manual-ISBN dialog silently discarded an unparseable entry — the same silent
+failure this wave existed to eliminate, sitting just outside the prompt's scope.
+It now marks the field in error and disables "Look up" until the checksum passes.
+Lesson for future prompts: scope a wave by *failure class*, not by file list, or
+the instances of the class that live outside the listed files survive.
+
+### HAZARD #8 — the wave-guard can die without writing its sentinel
+`logs/WAVE5-DONE` was written BY HAND. The guard renewed at 11:13, the worker
+succeeded at 11:21, and the guard neither wrote the sentinel nor logged its
+"guard exiting" trap line — it was killed outright. The lease expired on its own
+an hour later.
+
+**This breaks the first-command heuristic at the top of this file.** "no sentinel
++ pgrep count 0 -> workers were KILLED" was WRONG here: the worker had finished
+successfully. Use these instead, in this order:
+  1. `ls -l logs/<name>.json` — 0 bytes means killed; non-zero means it finished.
+  2. `tail logs/<name>.state` — says SUCCESS / GIVING UP / WALL CLOCK explicitly.
+  3. `git status --porcelain` — is there actually work in the tree?
+The sentinel is a convenience, not the record of truth. `logs/<name>.state` is.
+
+## Wave 6 — second on-device feedback round: COMPLETE, verified 2026-09-09
+The user tested the phone build again and sent eight items. All eight are done.
+Two Sonnet workers (`tasks/H1-screens.txt`, `tasks/H2-picker.txt`) took the UI
+work; the ORCHESTRATOR did the retry/backoff work itself in `data/metadata` and
+`AppContainer`, because it needed the live measurement below to design it.
+
+| Check | Result |
+|---|---|
+| `./tasks/gw assembleDebug` | exit 0 |
+| `./tasks/gw testDebugUnitTest` | exit 0 — **172 tests**, 1 skipped, 0 failures (was 138) |
+| `./tasks/gw verifyPaparazziDebug` | exit 0 |
+| `grep "always 'false'"` on a `--rerun-tasks` rebuild | **0 hits** |
+| `./tasks/gw assembleRelease` | exit 0 — 41,810,740 bytes, V2 signer `CN=Bookshelf, O=Montanaro` |
+| boundary check | clean — neither worker touched a build file or the other's packages |
+
+### The ghost bookcase was an inset bug, not a data bug
+`LocationsScreen`'s list branch dropped the Scaffold's `innerPadding` while its
+empty-state branch applied it, so the FIRST bookcase row rendered underneath the
+top app bar and was invisible. Every symptom the user described follows from that:
+invisible first bookcase, no empty state on re-entry (the list was genuinely
+non-empty), a second bookcase created, both showing in the filter menu. **Both
+records were always real and healthy** — the user should delete the spare.
+Every other screen was checked for the same class of bug; Locations was the only
+one. Fix: fold `innerPadding` into the LazyColumn's `contentPadding` (NOT
+`Modifier.padding`, which would clip the scroll area instead of insetting it).
+
+### Metadata: measured, not guessed
+See `docs/METADATA-SOURCES.md` § "Measured again 2026-09-09" for the full data.
+Two things that change how you should think about this app:
+
+1. **Google Books keyless is dead for everyone, permanently.** The user's
+   residential-IP test returned a quota error naming `project_number:624717413613`
+   — a shared anonymous *project*, not an IP. The old note in METADATA-SOURCES.md
+   guessing that a residential IP "may well get answers" is now marked CORRECTED
+   in place. Because `combine()` turns any Failed-with-no-Found into `Unavailable`,
+   this standing failure meant **every** Open Library hiccup surfaced as
+   "one or more sources couldn't be reached". The app has been single-sourced all
+   along. **The user has deliberately deferred the API key — do not add it unasked.**
+2. **Our own timeouts were manufacturing failures.** 30 live requests: 13% failed,
+   all fast TLS resets (<2.5s); successes had a median of 4.3s but a max of 22.0s,
+   and **2 of 26 successes exceeded the old 12s `callTimeout`**. Timeouts are now
+   25s/20s/20s. Failures are fast and successes are slow, so a short timeout buys
+   nothing on the failure path and costs real successes on the slow path.
+
+`RetryPolicy` + `withRetry` (new, `data/metadata/`) retry TRANSPORT and
+SERVER_ERROR only. It deliberately does NOT retry:
+- **TIMEOUT** — the budget is already spent; retrying could triple the wait.
+- **RATE_LIMITED** — hammering a quota is how an intermittent block becomes a
+  permanent one, and METADATA-SOURCES.md records that happening to this project's
+  IP. Revisit when the Google Books key lands: a *keyed* 429 is a per-second limit
+  and does deserve one Retry-After-respecting retry.
+`SourceResult.Failed` now carries a `FailureKind` alongside its human `reason`, and
+`reason` names the specific exception ("tls connection reset, 3 attempts") instead
+of a generic "network error". **That string is now rendered on the scan sheet and
+is our ONLY diagnostic channel from a real phone.** Nothing may parse it.
+
+### Known-soft spots in wave 6 — do not mistake these for verified
+1. **The Paparazzi "regression" snapshot for the ghost bookcase is a lookalike,
+   not the real screen.** `LocationsScreenPaparazziTest` hand-rolls its own
+   Scaffold+LazyColumn copy because the real `LocationsScreen` needs an
+   `AppContainer` (Room + DataStore). The orchestrator verified the REAL fix by
+   reading the diff; the PNG only proves the test's copy is right, and the two can
+   drift — the copy already omits the bottom inset the real screen adds. Splitting
+   a stateless `LocationsContent(state, callbacks)` out of the screen would make
+   this snapshot genuine. Worth doing before anyone trusts it as regression cover.
+2. **The auto-focus calls are unverified.** Three dialogs now do
+   `LaunchedEffect(Unit) { runCatching { focusRequester.requestFocus() } }`. That
+   is the idiomatic form, but there is no emulator here and `runCatching` means a
+   too-early call fails SILENTLY rather than crashing. If a dialog opens unfocused
+   on the phone, that is why; the fix is to await a frame before requesting.
+3. **The shelf picker opens as a bottom sheet stacked on top of the save sheet**
+   (H2's own flagged judgement call). It renders correctly in Paparazzi but
+   sheet-over-sheet is awkward on real Android. Watch it on the device.
+
+### Worker lessons (both are repeats — the prompts already forbade them)
+- **H1 backgrounded a Gradle build and ended its turn**, exactly the wave-4
+  failure, despite an explicit foreground-only instruction AND
+  `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0` being set in `run-task.sh`. Its final
+  message was "I'll wait for this background build to complete." `run-task.sh`
+  still recorded SUCCESS because the process exited 0. **`.state` saying SUCCESS
+  means the process exited cleanly, NOT that the worker finished its task** — read
+  `logs/<name>.summary` and check that the result is an actual report. H1's work
+  was fine, but nobody verified it except the orchestrator.
+- H2 (108 turns, $4.00) followed the brief closely, ran builds in the foreground,
+  and reported honestly, including flagging its own stacked-sheet judgement call.
+  Cost ratio to H1 ($0.66, 5 turns) is roughly the ratio of work actually done.

docs/METADATA-SOURCES.md

@@ -0,0 +1,294 @@
+# Book metadata lookup — why scans miss, and what else we could ask
+
+Research note, 2026-09-09. Written in response to "out of the 3 barcodes I've
+scanned, only 1 has been discovered properly."
+
+**Nothing in here has been implemented.** SPEC's two-source design (Open Library
+primary, Google Books fallback) is unchanged. This is the evidence for deciding
+whether to change it.
+
+> **Update, same day — the coverage hypothesis is dead.** The user supplied the
+> two ISBNs that failed: 9781883937386 (*The Hittite Warrior*) and 9781883937676
+> (*Shadow Hawk*), both Bethlehem Books. **Both are fully present in Open
+> Library** — title, author, publisher, page count and cover art — and the app's
+> own parser handles both real responses correctly (regression test:
+> `OpenLibraryClientTest.parses the real responses for the two books the app
+> failed to identify`). Whatever went wrong on the phone was upstream of the
+> metadata sources. Everything below still holds as background, but do not act
+> on "add a third source" until we know why a book Open Library *has* did not
+> reach the lookup. See [What actually failed](#what-actually-failed).
+
+---
+
+## Short version
+
+Three separate defects were making lookups *look* far worse than the underlying
+data actually is, and all three are now fixed (commit `356f639`). They are not
+the same problem as "this book isn't in the database":
+
+1. A cover that loaded fine still rendered as nothing, so a **successful** lookup
+   looked like a failed one. That alone could account for the book you did find
+   appearing broken.
+2. Open Library's cover URL was synthesized for every book whether or not art
+   existed, and a missing cover comes back as a **200 with a 43-byte 1×1
+   transparent GIF** — a "successful" load that paints nothing.
+3. Because that synthesized URL was never blank, the merge rule could never fall
+   through to Google Books' thumbnail. The documented fallback was dead code for
+   covers.
+
+What is left is a real coverage question, and there the measurements point at one
+thing above all others: **the Google Books fallback is probably not answering at
+all.** Every keyless request from this machine returned HTTP 429, and the app
+turns any non-200 into `null`, which the UI presents as "No match found — enter
+the details by hand." A rate-limited lookup and a book that genuinely exists
+nowhere are, right now, indistinguishable to both you and me.
+
+My recommendation is to fix the diagnosis before buying more data. Details in
+[Recommendation](#recommendation).
+
+---
+
+## What I measured
+
+**Sample.** 60 ISBNs drawn from the Harvard Library catalog — deliberately a
+third party, so the sample doesn't presuppose the answer by coming from one of
+the two sources under test. Ten publishers, weighted toward the small Catholic
+and homeschool presses that a MODG family's shelf actually carries (Ignatius,
+TAN, Sophia Institute, Bethlehem Books, Baronius) alongside mainstream trade
+(Penguin, Random House, Scholastic, Crossway, Loyola).
+
+**Method.** Direct HTTP against each API, one ISBN at a time, 1.2 s apart. A
+source "hits" only if it returns a usable title.
+
+### Results
+
+| Source | Hit | Miss | Error | Hit rate |
+|---|---|---|---|---|
+| Open Library Books API (what the app calls today) | 53 | 4 | 3 | **88%** |
+| Google Books, keyless (the app's fallback) | 0 | 0 | **60 × HTTP 429** | **0%** |
+| Harvard LibraryCloud | 56 | 4 | 0 | 93% * |
+| Open Library cover art exists for the ISBN | 47 | 13 | 0 | 78% |
+
+\* Harvard is where the sample came from, so its number is inflated by
+construction. It's here to show the API works and answers by ISBN-13, not as a
+fair comparison.
+
+Two further observations from the same runs:
+
+- **Concurrency is punished.** The same 60 ISBNs run six-at-a-time dropped Open
+  Library from 88% to 70%, entirely through transport errors. The app makes one
+  request per scan, so this doesn't bite in normal use — but it does mean
+  "Open Library missed" in a log is not proof the book is absent. By the end of
+  this research my own IP was refused outright for a while.
+- **17% of successful Open Library lookups have no cover art at all** (9 of 53).
+  Even with everything working, roughly one book in six will legitimately show
+  the placeholder. That is a data fact, not a bug, and it's worth knowing before
+  you read a placeholder as a failure.
+
+### What this does not tell us
+
+Worth saying plainly, because it bounds how much weight the numbers carry:
+
+- n = 60, and the sample comes from a research library. It under-represents
+  recent mass-market paperbacks, reprints and print-on-demand editions — which
+  is exactly where Open Library is thinnest. Real shelf coverage is probably
+  *below* 88%.
+- Every request came from a datacenter IP. The Google Books 429 may partly be
+  this host sharing a quota pool with other tenants; **your phone, on a
+  residential or mobile IP, may well get answers.** That's precisely why the
+  app needs to be able to tell us which it got.
+  > **CORRECTED 2026-09-09 — this guess was WRONG.** The user tested from a
+  > residential IP and got the same refusal, naming a shared *project* quota
+  > rather than an IP one. See "Measured again 2026-09-09" at the end of this
+  > file. Do not act on the sentence above.
+- I don't know which three ISBNs you scanned. If you still have the books to
+  hand, those three numbers are worth more than another 60 sampled ones.
+
+---
+
+## The options
+
+### A. Give Google Books an API key
+Free, 1,000 requests/day, no billing account required. Turns the fallback from
+"silently 429" into a working source. Roughly a dozen lines: a key in
+`local.properties` → `BuildConfig` → `&key=` on the query.
+
+The key ships inside the APK and can be extracted, so restrict it to the Books
+API in the Google Cloud console. At our volume, someone stealing it costs us
+nothing but the quota.
+
+**Effort: hours. Cost: free. Likely the single biggest win.**
+
+### B. Tell the difference between "not found" and "couldn't ask"
+Both clients collapse every non-200, timeout and parse failure into `null`, and
+`MetadataRepository` collapses that into "no match", and the UI writes "No match
+found." A book that's offline, rate-limited, or hit a 500 is reported to you as
+a book that does not exist.
+
+Distinguishing these gets you a retry button instead of a manual-entry form, and
+gets me a real answer next time you say "it missed."
+
+**Effort: half a day. Cost: free. Do this regardless of what else we choose.**
+
+### C. Retry with backoff
+One retry on 429/5xx, a couple of seconds apart. Standing at a bookshelf, a
+two-second retry is invisible; a manual-entry form is not.
+
+**Effort: an hour. Cost: free.**
+
+### D. Add a third free source
+Only worth doing after A–C, when we can see what's actually still missing.
+Ranked by what I'd try first:
+
+| Source | Key? | Notes |
+|---|---|---|
+| **Open Library `search.json`** | No | Searches the whole OL index rather than the edition table the Books API reads. Cheapest possible fallback — same service, one more request, no new failure modes. |
+| ~~**Harvard LibraryCloud**~~ | No | **Demoted.** Free, no registration, answers by ISBN-13 (`?identifier=<isbn>`), verified working — but it returned `numFound: 0` for *both* of the user's real failing books. It is a research library: strong on scholarly and older material, and it simply does not hold small-press children's historical fiction. The 93% in the table above is inflated by construction (the sample came from Harvard) and is misleading in exactly the direction that matters. Not a fit for this shelf. |
+| **Library of Congress** | No | The SRU endpoint (port 210) is blocked from here; the `loc.gov` JSON API responds. Excellent for US imprints. Needs more probing before I'd commit. |
+| **K10plus SRU** | No | Free German-led union catalogue, large and international. Cataloguing conventions differ enough that merging would need care. |
+
+Dead ends, so nobody re-investigates them: **OCLC Classify** (retired 2021),
+**Goodreads API** (retired 2020), **Amazon Product Advertising API** (requires an
+affiliate account with qualifying sales), **WorldCat Search** (requires OCLC
+membership — institutional pricing).
+
+### E. Pay for ISBNdb
+~$15–50/month depending on tier. Genuinely better coverage than anything free,
+including cover art, and a single clean API. It is also a subscription for a
+two-person home library, and I'd want proof that A–D leave a real gap before
+recommending it.
+
+**Effort: hours. Cost: $180–600/year.**
+
+---
+
+## What actually failed
+
+Both failing ISBNs resolve cleanly against the source the app already uses:
+
+| Check | 9781883937386 | 9781883937676 |
+|---|---|---|
+| Open Library Books API | *Hittite warrior*, Joanne S. Williamson | *Shadow hawk*, Andre Norton |
+| Cover art | yes | yes |
+| App's own parser (unit test) | parses | parses |
+| ISBN-13 checksum | valid | valid |
+| Harvard | not held | not held |
+
+So the request either never went out, or went out and failed in a way the app
+reported as "not found". Candidates, in the order I'd chase them:
+
+1. **The barcode never decoded into a valid ISBN-13.** `ScanCodeFilter` drops
+   anything that fails the checksum, silently and with no UI feedback at all —
+   no sheet, no message, nothing. A book whose barcode carries a price add-on,
+   or is worn, or is a UPC-A rather than a Bookland EAN, looks to the user
+   exactly like a camera that isn't working. This is my leading theory, and it
+   fits "wasn't able to scan" better than "wasn't found".
+2. **The HTTP request failed.** Both clients turn every non-200, timeout and
+   parse error into `null`, which reaches the user as "No match found". The
+   metadata `OkHttpClient` is constructed with no call timeout, so a stalled
+   connection hangs on default socket timeouts.
+3. **The lookup ran and the sheet was dismissed before it landed.** While
+   Loading, the sheet passes an empty `onDismissRequest`, so it can't be
+   swiped away — but `onScanned` early-returns whenever a sheet is already
+   showing, so a stuck sheet blocks every subsequent scan.
+
+Nothing here is a data-source problem. Note the sting in (1) and (2): both
+failure modes are invisible or actively misleading, which is why three scans
+produced no usable diagnosis.
+
+## Recommendation
+
+**Revised after the two real ISBNs came in.** Adding sources is now the *wrong*
+next move: the books that failed are already in the source we query.
+
+Do **B** first and on its own — make the app say what happened. A scan that
+decodes nothing should say so on the camera screen; a lookup that fails should
+offer retry, not a manual-entry form captioned "No match found". Add a call
+timeout while in there.
+
+Then rescan those two books. The app will tell us which of the three candidates
+above it is, and that determines everything after it. **A** (the free Google
+Books key) and **C** (retry/backoff) are still worth doing — cheap, and the 429
+result is real — but they are no longer the leading theory.
+
+**D** and **E** are on hold. Harvard specifically is off the list for this
+shelf. Paying ISBNdb for coverage we demonstrably already have would be the
+wrong order.
+
+One thing worth deciding separately: 17% of books legitimately have no cover art
+anywhere. The placeholder now looks deliberate rather than broken, but if you
+want covers on everything, that's a different feature — photograph the book,
+store it as the cover — and not a metadata-source problem at all.
+
+## Measured again 2026-09-09, after the user tested from a residential IP
+
+Two things were settled that the first round could only guess at.
+
+### Google Books keyless is dead everywhere, not just from this box
+
+The user ran the app's exact Google Books call from their home connection and got:
+
+    Quota exceeded for quota metric 'Queries' and limit 'Queries per day'
+    of service 'books.googleapis.com' for consumer 'project_number:624717413613'
+
+That names a **Google Cloud project, not an IP**. Every keyless caller on the
+internet is billed to that one shared anonymous project and its daily quota is
+exhausted. So:
+
+- The earlier caveat — "your phone, on a residential or mobile IP, may well get
+  answers" — is **WRONG**. Delete it from your mental model. It was tested and it
+  is not true.
+- Backoff cannot help. This is a daily quota, not a per-second rate limit.
+- A free API key is the only fix, and it is a complete one: it moves the app into
+  its own project with its own quota (free tier 1,000 req/day).
+
+The knock-on is the part that actually hurt the user. `MetadataRepository.combine`
+turns "any source Failed, none Found" into `Unavailable`. Google Books is a
+PERMANENT standing failure, so **every** Open Library hiccup became `Unavailable`.
+The app has effectively been single-sourced this whole time while reporting
+failures as though two sources had been consulted.
+
+**The user has deliberately deferred the API key.** Do not implement it unasked.
+
+### Open Library: 13% failure, and our own timeout was manufacturing more
+
+30 requests, the exact call `OpenLibraryClient` makes, 1.5s apart, from the sprite:
+
+| | |
+|---|---|
+| failure rate | **13%** (4 of 30) |
+| every failure | curl exit 35 — TLS-stage `Connection reset by peer` |
+| failure latency | 0.23s, 0.31s, 0.59s, 2.46s — **all fast** |
+| success latency | median **4.3s**, p75 6.0s, p90 **9.2s**, max **22.0s** |
+| successes over the old 12s callTimeout | **2 of 26 (8%)** |
+
+Two conclusions, and they point in opposite directions:
+
+1. **Failures are cheap and transient**, so retrying is nearly free. 13% → ~1.7%
+   at two attempts → ~0.2% at three. This is why `RetryPolicy` exists and why its
+   backoff is milliseconds rather than the conventional seconds.
+2. **Successes are slow and long-tailed**, and the app's own
+   `callTimeout(12s)`/`connectTimeout(10s)` were cutting off roughly 8% of
+   lookups that were about to succeed — then reporting them to the user as
+   "couldn't be reached". The app was generating a meaningful share of its own
+   failures. Timeouts are now 25s/20s/20s, above the 22.0s worst observed success.
+
+The asymmetry is the whole design: a short timeout buys nothing on the failure
+path (failures return in under 2.5s regardless) and costs real successes on the
+slow path. That is also why `RetryPolicy.isRetryable` refuses to repeat a
+TIMEOUT — a timeout means the budget was already spent, and the evidence says
+slow requests mostly succeed if you let them finish.
+
+Connection reuse is visible in the data and matters in real use: cold connects
+ran 2-19s while warm ones ran 0.07s. OkHttp pools connections for 5 minutes, so
+scanning a box of books in sequence stays on the fast path after the first book.
+
+### What still is not known
+
+- All 30 requests came from this datacenter IP. The user's phone may see a
+  different failure rate. The reason string now shown on the scan sheet
+  (`SourceResult.Failed.reason`, e.g. "tls connection reset, 3 attempts") is how
+  we find out — it is the only diagnostic channel we have from a real device.
+- The user's own 3-request sample showed 2 failures. That is consistent with 13%
+  (p ~ 5%) but does not confirm it. If their phone reports "3 attempts" often,
+  their network is worse than this one and the retry count deserves revisiting.

docs/SPEC.md

@@ -91,12 +91,28 @@ Never let sync failure surface as a crash or a blocking dialog — a quiet statu
 Primary Open Library: https://openlibrary.org/api/books?bibkeys=ISBN:{isbn}&format=json&jscmd=data
 Fallback Google Books: https://www.googleapis.com/books/v1/volumes?q=isbn:{isbn}  (no key)
 Cover: https://covers.openlibrary.org/b/isbn/{isbn}-L.jpg  else GB imageLinks (force https, zoom=2)
-Merge: prefer whichever has a title; fill blanks from the other. Return null if both miss,
+Merge: prefer whichever has a title; fill blanks from the other.
-and the UI must then offer manual entry pre-filled with the scanned ISBN.
+Cover URL comes from a source that REPORTS one. Never synthesize the by-ISBN cover
+URL as if it were evidence: for an edition with no art that endpoint returns 200 +
+a 43-byte 1x1 transparent GIF, which loads "successfully" and paints nothing. As a
+last resort it may be used only with `?default=false`, which makes a miss a 404.
+
+Lookup outcome is THREE-WAY, never a bare null. A source that could not be reached
+must never be reported to the user as a book that does not exist:
+  Found(metadata)   - at least one source returned a record
+  NotFound          - EVERY source answered authoritatively and none had it
+  Unavailable       - no source could be reached (non-2xx, timeout, transport error)
+                      and none of the reachable ones had it
+UI: Found -> the save sheet. NotFound -> manual entry pre-filled with the scanned
+ISBN. Unavailable -> a retry affordance, with manual entry as the escape hatch;
+it must NOT claim the book is unknown.
 
 ## Barcode scanning
 CameraX Preview + ImageAnalysis -> ML Kit BarcodeScanning (EAN_13, EAN_8, UPC_A).
 Validate ISBN-13 checksum before lookup; ignore non-book barcodes. Debounce repeats.
+A rejected barcode is NOT silent: the camera screen must say a code was read and
+was not a book ISBN, or the user cannot tell a non-book barcode from a dead camera.
+Throttle that message — a non-book barcode sits in frame emitting continuously.
 Continuous mode: after a save, stay on camera for the next book (shelving a box of
 books is the real use case). Show a running "added this session" count.
 Handle: camera permission denial, torch toggle, and a manual-ISBN-entry escape hatch.

logs/F3-release.sid

@@ -0,0 +1 @@
+0bdf98e8-c28a-4069-ad84-87e674234136

logs/G-diagnostics.sid

@@ -0,0 +1 @@
+9b656dc8-a225-47ec-b6ce-549241854de6

logs/G-diagnostics.summary

@@ -0,0 +1,19 @@
+=== G-diagnostics  attempts=2 quota_waits=1 hard_fails=0 ===
+cost=$0.28007899999999997 turns=6 err=?
+--- result (tail) ---
+` case. `byIsbnCoverUrl` untouched.
+
+**AppContainer.kt** — `metadataHttpClient` now has `callTimeout(12s)/connectTimeout(10s)/readTimeout(10s)`. PocketBase `okHttpClient` untouched.
+
+**ui.scan:**
+- `ScanCodeFilter.kt` — `accept()` returns `ScanOutcome { Isbn, NotAnIsbn, Ignored }`; one shared debounce mechanism throttles repeats of valid *and* rejected codes alike.
+- `ScannerController.kt` — new `rejectedCodes: SharedFlow<String>` routed alongside `scanResults`.
+- `ScanModels.kt` — `ScanSheetState.NotFound` gained `viaLookupFailure: Boolean = false`; added `ScanSheetState.LookupFailed(isbn13, reason)`; `ScanMetadataOutcome.from` maps all three `LookupResult` cases.
+- `ScanViewModel.kt` — `retryLookup`/`enterByHand` added; lookup logic factored so Retry bypasses the "sheet already showing" guard; `rejectedMessage: StateFlow<String?>` with a 3s auto-clear timer.
+- `ScanScreen.kt` — new `LookupFailedSheet` (Retry/Enter by hand/Skip, dismissible, never claims the book unknown); `ManualEntrySheet` reworded via `authoritative: Boolean`; new `RejectedBarcodeBanner` shown over the camera.
+
+**Tests:** classify() cases for both clients, the full 3×3 `combine` matrix, `ScanCodeFilter` throttle tests with an injected clock, `ScannerController` rejected-code routing, updated `ScanModelsTest`, and two new Paparazzi snapshots (`LookupFailedSheet`, rejected-barcode banner) recorded in both light and dark — all visually verified.
+
+No warnings (Kotlin or otherwise) were introduced in any file I touched; a clean `--rerun` compile shows only pre-existing, unrelated deprecation warnings elsewhere in the codebase.
+
+Nothing was left undone relative to the original instructions, and no constraints (forbidden files, no commits, foreground builds, no MockWebServer) were violated.

logs/H1-screens.sid

@@ -0,0 +1 @@
+430e1016-0c8c-47a5-905b-ad106cbb6b19

logs/H1-screens.summary

@@ -0,0 +1,4 @@
+=== H1-screens  attempts=1 quota_waits=0 hard_fails=0 ===
+cost=$0.6623552 turns=5 err=?
+--- result (tail) ---
+I'll wait for this background build to complete before continuing.

logs/H2-picker.sid

@@ -0,0 +1 @@
+67bf128a-9c53-4fd2-b9ce-10b99f4a385d

logs/H2-picker.summary

@@ -0,0 +1,10 @@
+=== H2-picker  attempts=1 quota_waits=0 hard_fails=0 ===
+cost=$3.9990499999999995 turns=108 err=?
+--- result (tail) ---
+ succeeded. New `shelf-picker-grouped-{light,dark}` snapshot shows two bookcases (Living Room with two shelves, one selected/bold/checked; Study empty with "No shelves yet"), plus the "Recent" section and "Not shelved" — verified visually. Existing `scan-searching-sheet` and `scan-lookup-failed-sheet` snapshots regenerated and confirmed correct (no stray "lower the book" line; reason string now visible).
+- Grepped all Kotlin compiler warnings from a forced rebuild: zero `always 'false'` hits anywhere, including my files.
+- `git status --porcelain`: only my owned files changed by me (`data/prefs/SettingsStore.kt`, `ui/scan/ScanScreen.kt`, `ui/scan/ScanViewModel.kt`, `ui/detail/DetailScreen.kt`, `ui/detail/DetailViewModel.kt`, new `ui/components/ShelfPickerSheet.kt`, and new/edited files under `app/app/src/test/**`). Everything else showing modified/untracked (`AppContainer.kt`, `data/metadata/**`, `ui/locations/**`, `ui/library/**`, `res/drawable/**`, `docs/METADATA-SOURCES.md`, locations snapshots) is the orchestrator's/other worker's concurrent work — untouched by me, left as-is.
+
+**Didn't do / judgment calls worth flagging**
+- Nothing skipped from the spec. One design decision: `ShelfPickerSheet` owns its own `ModalBottomSheet`, so tapping "Choose a shelf"/"Change" opens it as a second, stacked sheet over the already-open save/detail sheet — this matches "presented as a Material 3 ModalBottomSheet" literally rather than inlining the list in the existing sheet.
+- Added tests beyond the stated minimum: `SettingsStoreTest` (round-trip, overwrite, clear, clearAuth), `ShelfPickerSheetTest` (`resolveRecentShelf` — null/missing-shelf/missing-bookcase/found cases), `ScanViewModelTest` and `DetailViewModelTest` (remember-on-save/move, "Not shelved" doesn't overwrite).

logs/WAVE4-DONE

@@ -0,0 +1,19 @@
+=== WAVE4-DONE written 2026-09-08T21:34Z by the Opus orchestrator ===
+NOT written by service-worker.sh. F3-release's FILES were all complete and
+untouched for ~50 min; it was stuck re-running verification it could not finish
+(600s background-wait ceiling, then a quota wait). The orchestrator ran the
+verification itself, accepted the work, and stopped the service.
+
+Independently verified by the orchestrator (not self-reported):
+  ./tasks/gw assembleDebug     exit 0
+  ./tasks/gw testDebugUnitTest exit 0 -- 102 tests, 1 skipped, 0 failures, 0 errors
+  ./tasks/gw assembleRelease   exit 0
+  app-release.apk 41,777,344 bytes, V2-signed CN=Bookshelf,O=Montanaro (real
+    release key, not the debug cert)
+  keystore + keystore.properties confirmed gitignored, NOT in the commit
+  skipped test = LiveSyncTest (opt-in, needs the live server)
+
+All four F3 tasks DONE: settings-email fix, 5 remaining screens' Paparazzi
+shots (light+dark), release signing + signed APK, top-level README.
+NOT delivered: F3's own written report, incl. its candid design critique of
+the rendered screens. The orchestrator must eyeball the PNGs instead.

logs/WAVE5-DONE

@@ -0,0 +1,22 @@
+=== WAVE5-DONE written BY HAND by the orchestrator, 2026-09-09 ===
+NOT written by tasks/wave-guard.sh. The guard renewed its lease at 11:13, the
+worker reported SUCCESS at 11:21, and the guard should have noticed within 30s
+and written this file. It never did, and it left no "guard exiting" line either,
+so it was killed outright rather than exiting through its TERM/INT trap. The
+lease then expired on its own at ~12:13.
+
+READ THIS BEFORE TRUSTING THE FIRST-COMMAND HEURISTIC AT THE TOP OF HANDOFF.md:
+"no sentinel + pgrep 0 -> workers were KILLED" would have been WRONG here. The
+worker finished successfully; only the guard died. The reliable signal is the
+size of logs/<name>.json (5695 bytes here — a killed worker leaves 0) plus the
+tail of logs/<name>.state (which says SUCCESS).
+
+G-diagnostics: SUCCESS after 2 attempts, 1 quota wait. cost=$0.28, turns=6.
+Independently re-verified by the orchestrator:
+  ./tasks/gw assembleDebug          exit 0
+  ./tasks/gw testDebugUnitTest      exit 0 - 138 tests, 1 skipped, 0 failures (was 107)
+  ./tasks/gw verifyPaparazziDebug   exit 0
+  ./tasks/gw assembleRelease        exit 0 - 41,793,760 bytes, V2 signer CN=Bookshelf
+  boundary check                    clean - no build files, no forbidden packages
+  grep "always 'false'"             0 hits on touched files
+Accepted and committed as 93f972b.

logs/WAVE6-DONE

@@ -0,0 +1,14 @@
+=== WAVE6-DONE written 2026-09-09T15:31:35+00:00 ===
+Workers finished. The orchestrator was NOT necessarily alive for this.
+
+--- H1-screens ---
+[2026-09-09T15:05:30+00:00] H1-screens: SUCCESS after 1 attempt(s), 0 quota wait(s)
+cost=$0.6623552 turns=5
+
+--- H2-picker ---
+[2026-09-09T15:31:29+00:00] H2-picker: SUCCESS after 1 attempt(s), 0 quota wait(s)
+cost=$3.9990499999999995 turns=108
+
+NEXT: orchestrator must independently verify before accepting:
+  cd ~/bookshelf && ./tasks/gw assembleDebug && ./tasks/gw testDebugUnitTest
+  git status --porcelain   # boundary check: who touched what

tasks/G-diagnostics.txt

@@ -0,0 +1,186 @@
+You are implementing ONE feature in the Bookshelf Android app at ~/bookshelf.
+
+READ FIRST, in this order:
+  1. ~/bookshelf/docs/SPEC.md — the authoritative contract. Sections "Book metadata
+     lookup" and "Barcode scanning" were just rewritten for this task. They are the
+     spec you are implementing. Do not contradict them and do not edit SPEC.md.
+  2. ~/bookshelf/docs/METADATA-SOURCES.md — why this work exists, section
+     "What actually failed".
+
+## The problem
+
+The app cannot tell three different things apart, and reports all of them
+identically or not at all:
+
+  (1) A barcode was decoded but is not a valid ISBN-13.
+      ScanCodeFilter.accept() returns null. NOTHING happens. No sheet, no message.
+      To the user this is indistinguishable from a camera that isn't working.
+
+  (2) A lookup request FAILED — non-2xx (Google Books returns HTTP 429 to keyless
+      callers), timeout, or transport error.
+      Both OpenLibraryClient.fetchBody and GoogleBooksClient.fetchBody collapse
+      this to null, MetadataRepository collapses that to null, and the UI writes
+      "No match found — enter the details by hand." The app tells the user a book
+      does not exist when in truth it never managed to ask.
+
+  (3) The lookup genuinely succeeded and neither source has the book.
+      This is the ONLY case where "No match found" is honest.
+
+This is not hypothetical. Two real books off the user's shelf (9781883937386
+"The Hittite Warrior", 9781883937676 "Shadow Hawk") failed on the phone, and both
+are fully present in Open Library — there are regression tests proving the app's
+own parser handles their real API responses. The bug is in how failure is
+classified and shown, NOT in coverage. Do not "fix" this by adding a data source.
+
+## What to build
+
+### 1. Per-source classification (data.metadata)
+
+Give each client a three-way outcome instead of `BookMetadata?`:
+
+    sealed interface SourceResult {
+        data class Found(val metadata: BookMetadata) : SourceResult
+        data object NotFound : SourceResult              // answered 2xx, no record
+        data class Failed(val reason: String) : SourceResult  // non-2xx/timeout/IO/parse
+    }
+
+`reason` is a short diagnostic string ("http 429", "timeout", "malformed json") —
+it is for the log and for us, NOT prose to show the user verbatim.
+
+CRITICAL for testability: there is no MockWebServer in this project and you must
+not add one. Put the classification in a PURE function that takes what an HTTP
+response gives you and returns a SourceResult, e.g.
+
+    internal fun classify(httpCode: Int, body: String?, isbn13: String): SourceResult
+
+and have fetch/lookup call it. Then it can be unit-tested exhaustively offline,
+the way parseResponse already is. Keep the existing internal parseResponse
+functions and their tests working.
+
+### 2. Combination (MetadataRepository)
+
+    sealed interface LookupResult {
+        data class Found(val metadata: BookMetadata) : LookupResult
+        data object NotFound : LookupResult
+        data class Unavailable(val reason: String) : LookupResult
+    }
+
+Rules, exactly as SPEC states them:
+  - any source Found            -> Found (merge as today via MetadataMerger)
+  - all sources NotFound        -> NotFound
+  - otherwise (>=1 Failed, none Found) -> Unavailable
+
+That last rule is the whole point: a single reachable source saying "no" is NOT
+authoritative while the other source could not be reached. Unit-test the full
+matrix — 3x3 of (OL outcome, GB outcome) — with real assertions.
+
+Keep MetadataRepository.byIsbnCoverUrl and the existing last-resort cover
+behaviour intact. An invalid ISBN (IsbnUtils.toIsbn13 returns null) is a
+programming error at this layer, not a lookup outcome — keep it out of
+LookupResult; the scan layer must never send one.
+
+### 3. Give the metadata HTTP client a call timeout (AppContainer)
+
+`metadataHttpClient` is a bare `OkHttpClient()` with no call timeout, so a stalled
+connection hangs on default socket timeouts. Give it an explicit callTimeout
+(10-15s is right — the user is standing at a bookshelf) plus connect/read
+timeouts. Leave the PocketBase okHttpClient alone; it is a different client for a
+reason (it carries the auth token) and sync is not in scope.
+
+### 4. Scanner feedback for a rejected barcode (ui.scan)
+
+ScanCodeFilter.accept() currently returns String?. Make the rejection visible:
+
+    sealed interface ScanOutcome {
+        data class Isbn(val isbn13: String) : ScanOutcome
+        data class NotAnIsbn(val rawValue: String) : ScanOutcome
+        data object Ignored : ScanOutcome   // debounced repeat: emit NO ui at all
+    }
+
+Route NotAnIsbn through ScannerController to the ScanScreen, which shows a
+transient message near the reticle, e.g. "Read 012345678905 — not a book barcode".
+
+THROTTLING IS MANDATORY AND IS THE EASY THING TO GET WRONG. A non-book barcode
+sitting in frame decodes on almost every analyzed frame. The message must not
+flicker or re-trigger per frame: debounce the same rejected code the way repeats
+of a valid code are already debounced, and let the message auto-clear after a
+few seconds. Unit-test the throttle with an injected clock — ScanCodeFilter
+already takes `nowMillis: () -> Long` for exactly this; use it, do not use real
+time in tests.
+
+### 5. UI states (ui.scan)
+
+ScanSheetState gains a failure case alongside the existing ones:
+
+    data class LookupFailed(val isbn13: String, val reason: String) : ScanSheetState
+
+  - Found      -> existing FoundBookSheet, unchanged
+  - NotFound   -> existing ManualEntrySheet. Reword its copy so it reads as an
+                  authoritative negative ("Not in Open Library or Google Books"),
+                  not as a generic failure.
+  - LookupFailed -> a NEW sheet that says the lookup could not be completed and
+                  offers: Retry (re-runs the lookup for that same ISBN), Enter by
+                  hand (falls through to the manual-entry form, ISBN pre-filled),
+                  and Skip. It must NOT say or imply the book is unknown.
+
+Wire Retry properly: it re-enters the loading state and re-runs the lookup. Do not
+leave a sheet that can strand the user — note that ScanViewModel.onScanned
+early-returns while any sheet is showing, so a sheet that cannot be dismissed
+blocks every subsequent scan.
+
+## Constraints — these are hard
+
+- Kotlin, Jetpack Compose, Material 3. Match the surrounding code's style, naming
+  and comment density. Read neighbouring files before writing.
+- Design language is in SPEC.md "Design language". Reuse existing components
+  (PrimaryButton, SecondaryButton, EmptyState, BookCover...). Do not invent new
+  colours or typography.
+- DO NOT touch: app/build.gradle.kts, gradle/libs.versions.toml, any file under
+  data/local, data/remote, data/repo, or ui/settings, ui/locations, ui/detail.
+  Every dependency you need is already declared. If you believe you need a new
+  one, STOP and say so in your report instead.
+- DO NOT edit docs/SPEC.md, docs/HANDOFF.md or docs/METADATA-SOURCES.md.
+- DO NOT git commit, git add, or git push. The orchestrator commits. Leave your
+  work in the working tree.
+- Build with `./tasks/gw <task>` — NEVER `./gradlew` directly (tasks/gw is a
+  flock-serialized wrapper).
+- RUN BUILDS IN THE FOREGROUND. Do not background a Gradle build and end your turn
+  saying you will report later — a previous worker did exactly that and could
+  never report. A full build here takes 1-3 minutes; just wait for it.
+- There is no emulator on this box (no KVM). You cannot run the app. Verify with
+  assembleDebug, unit tests, and Paparazzi.
+
+## Definition of done
+
+All of these must pass, and you must run them yourself and paste the real output:
+
+  ./tasks/gw assembleDebug          -> exit 0
+  ./tasks/gw testDebugUnitTest      -> exit 0, and the pre-existing 107 tests still
+                                       pass (only LiveSyncTest may be skipped)
+  ./tasks/gw recordPaparazziDebug   -> exit 0
+
+Also required:
+- New unit tests with REAL assertions for: the classify() function per source
+  (2xx-with-record, 2xx-without-record, 404, 429, 500, malformed body), the 3x3
+  LookupResult combination matrix, and the ScanOutcome throttle with an injected
+  clock. Assertion-free tests are a spec violation.
+- A Paparazzi snapshot for the new LookupFailed sheet, and one for the camera
+  overlay showing a rejected-barcode message, in BOTH light and dark. Follow the
+  existing pattern in src/test/java/org/modg/bookshelf/ui/screens/ScanScreenPaparazziTest.kt.
+- Check the build log for Kotlin warnings on files you touched. A warning reading
+  "Check for instance is always 'false'" is NOT cosmetic — that exact warning hid
+  a bug that blanked every book cover in this app for months. If you see it, you
+  have written dead code; fix it.
+
+## Report
+
+End with a plain report covering:
+  - what you changed, file by file
+  - the verbatim tail of each of the three gradle commands
+  - the test count before and after
+  - anything you could NOT do, or did differently from these instructions, and why
+  - anything you noticed that looks wrong but was out of scope
+
+Be honest. A worker on this project has over-claimed success before, and the
+orchestrator independently re-verifies everything, so an inflated report only
+wastes a round trip.

tasks/H1-screens.txt

@@ -0,0 +1,137 @@
+You are a Sonnet worker on the Bookshelf Android app (~/bookshelf). Read
+`docs/SPEC.md` first — it is the authoritative product contract and it wins over
+anything you infer from the code. Do not restate it, do not let it drift.
+
+## Ground rules (violating these fails the wave)
+- Build ONLY with `./tasks/gw <task>` — never `./gradlew`. A second worker shares
+  this Gradle project dir and concurrent invocations clobber each other. `tasks/gw`
+  is a flock-serialized wrapper.
+- Run builds in the FOREGROUND. Never background a Gradle build and end your turn
+  saying you'll report later — `claude -p` kills background tasks and you will
+  never report at all. Builds take up to 10 minutes; just wait.
+- You own EXACTLY these files:
+      app/app/src/main/java/org/modg/bookshelf/ui/locations/LocationsScreen.kt
+      app/app/src/main/java/org/modg/bookshelf/ui/library/LibraryScreen.kt
+      app/app/src/main/res/drawable/ic_shelves.xml          (new file, create it)
+      app/app/src/test/**                                    (tests you add)
+  Touch NOTHING else. Specifically forbidden: any build file
+  (`app/build.gradle.kts`, `gradle/libs.versions.toml`, `settings.gradle.kts`),
+  `data/**`, `ui/scan/**`, `ui/detail/**`, `ui/components/**`, `ui/nav/**`,
+  `ui/settings/**`, `ui/setup/**`, `AppContainer.kt`. Another worker and the
+  orchestrator own those RIGHT NOW and are editing them concurrently.
+- Do not change any public composable signature. `ui/nav/BookshelfNavHost.kt`
+  calls these screens and you may not edit it.
+
+## Task 1 — the ghost-bookcase bug (highest priority, a real user-facing defect)
+`LocationsScreen.kt` line ~97. The Scaffold hands `content` an `innerPadding` that
+accounts for the top app bar. The empty-state branch applies it; the list branch
+does NOT:
+
+    ) { innerPadding ->
+        PaperSurface(...) {
+            if (state.bookcases.isEmpty()) {
+                EmptyState(modifier = Modifier.padding(innerPadding), ...)   // correct
+            } else {
+                LazyColumn(contentPadding = PaddingValues(bottom = 96.dp)) { // BUG
+
+So the first bookcase row renders UNDERNEATH the app bar and is invisible. A user
+created a bookcase, could not see it, created a second one, and ended up with two
+real bookcases and no idea why. Fix it by folding `innerPadding` into the
+LazyColumn's `contentPadding` so the existing 96.dp bottom inset is PRESERVED and
+added to, not replaced — the bottom inset is what keeps the last row clear of the
+FAB. Something equivalent to:
+
+    contentPadding = PaddingValues(
+        top = innerPadding.calculateTopPadding(),
+        bottom = innerPadding.calculateBottomPadding() + 96.dp,
+    )
+
+Using `contentPadding` rather than `Modifier.padding` is deliberate: it keeps the
+list scrolling under the bar instead of clipping the scroll area.
+
+VERIFY THIS SPECIFICALLY: add a Paparazzi snapshot of `LocationsScreen` in a state
+with exactly ONE bookcase, and confirm in the rendered PNG that the bookcase row is
+fully visible below the app bar. A one-bookcase list is the exact case that was
+broken and it must be the case you prove fixed. If the existing Paparazzi harness
+makes rendering this screen with seeded state impractical, say so plainly in your
+report rather than skipping it silently.
+
+## Task 2 — auto-focus the first field in the location dialogs
+In `LocationsScreen.kt`, `BookcaseEditDialog` (~line 276) and `ShelfEditDialog`
+(~line 299) each open with an unfocused `OutlinedTextField`. The first field
+should take focus and raise the keyboard when the dialog appears. Use a
+`FocusRequester` + `LaunchedEffect(Unit) { focusRequester.requestFocus() }`.
+Bookcase dialog: focus "Name" (not "Note"). Shelf dialog: focus "Label".
+Guard the requestFocus call so it cannot throw if the node isn't attached yet.
+
+## Task 3 — library filter empty state
+`LibraryScreen.kt` ~line 204. The filter DropdownMenu always offers "All books"
+first, then a flat list of bookcases and shelves. When there are NO bookcases and
+NO shelves, the menu contains only "All books" — which is already the active state
+and cannot be changed, so it is a menu with nothing in it.
+
+When `bookcases` and `shelves` are both empty, replace the menu contents with a
+single DISABLED item reading "Add a bookcase to enable filtering". Keep the
+toolbar filter icon visible and enabled (it is how the feature is discovered) —
+only the menu's contents change. When locations DO exist, behaviour is unchanged.
+
+## Task 4 — replace the Warehouse icon with a real bookcase
+`LibraryScreen.kt` line ~100 uses `Icons.Outlined.Warehouse` for the button that
+opens Locations. It renders as a barn and reads wrong. `material-icons-extended`
+1.7.8 has no bookcase glyph (I checked all 1932 outlined icons), so use Material
+Symbols' `shelves`, which is a bookcase frame with shelves and books on them.
+
+Create `app/app/src/main/res/drawable/ic_shelves.xml` with EXACTLY this content.
+This is the SVG path verbatim from Google's CDN. Do not re-derive it, do not
+    "simplify" it, and do not convert its relative (lowercase) commands to absolute
+    ones — Android's pathData parser accepts SVG syntax as-is. Material Symbols ship with
+`viewBox="0 -960 960 960"` — a negative Y origin that Android `<vector>` has no
+equivalent for — and the `<group android:translateY="960">` is what compensates.
+Removing it renders an empty icon.
+
+    <?xml version="1.0" encoding="utf-8"?>
+    <!-- Material Symbols "shelves" (Apache 2.0). Source viewBox is
+         "0 -960 960 960"; Android has no viewport origin, so the group
+         translate is load-bearing. Do not flatten it. -->
+    <vector xmlns:android="http://schemas.android.com/apk/res/android"
+        android:width="24dp"
+        android:height="24dp"
+        android:viewportWidth="960"
+        android:viewportHeight="960">
+        <group android:translateY="960">
+            <path
+                android:fillColor="#FF000000"
+                android:pathData="M120-40v-880h80v80h560v-80h80v880h-80v-80H200v80h-80Zm80-480h80v-160h240v160h240v-240H200v240Zm0 320h240v-160h240v160h80v-240H200v240Zm160-320h80v-80h-80v80Zm160 320h80v-80h-80v80Z" />
+        </group>
+    </vector>
+
+Then swap the icon at the call site:
+
+    Icon(painterResource(R.drawable.ic_shelves), contentDescription = "Bookcases & shelves")
+
+Keep the existing contentDescription text. `Icon` applies its own tint over a
+Painter exactly as it does over an ImageVector, so the icon still picks up the
+theme colour — do NOT hardcode a colour at the call site. You will need imports
+for `androidx.compose.ui.res.painterResource` and `org.modg.bookshelf.R`, and the
+`Icons.Outlined.Warehouse` import becomes unused — remove it.
+
+## Verify before you report (all in the FOREGROUND)
+    ./tasks/gw assembleDebug
+    ./tasks/gw testDebugUnitTest
+    ./tasks/gw recordPaparazziDebug
+    git status --porcelain
+
+- assembleDebug and testDebugUnitTest must exit 0. The test count is 138 today and
+  must not go DOWN.
+- Grep your build output for the string `always 'false'`. That Kotlin warning class
+  silently blanked every book cover in this app for months by making a `when`
+  branch dead code that still compiled. Zero hits on files you touched.
+- `git status --porcelain` must show ONLY the files you own. If it shows others,
+  you have broken the boundary — report it, do not revert someone else's work.
+- Do not commit. The orchestrator commits after verifying.
+
+## Report
+Finish with a plain report: what you changed per task, the exact exit codes and
+test counts, whether the one-bookcase Paparazzi render actually proves task 1, and
+anything you could NOT do. Do not claim success you did not verify — several
+previous workers on this project over-claimed and were caught.

tasks/H2-picker.txt

@@ -0,0 +1,143 @@
+You are a Sonnet worker on the Bookshelf Android app (~/bookshelf). Read
+`docs/SPEC.md` first — it is the authoritative product contract and it wins over
+anything you infer from the code. Do not restate it, do not let it drift.
+
+## Ground rules (violating these fails the wave)
+- Build ONLY with `./tasks/gw <task>` — never `./gradlew`. Another worker shares
+  this Gradle project dir and concurrent invocations clobber each other.
+  `tasks/gw` is a flock-serialized wrapper.
+- Run builds in the FOREGROUND. Never background a Gradle build and end your turn
+  saying you'll report later — `claude -p` kills background tasks and you will
+  never report at all. Builds take up to 10 minutes; just wait.
+- You own EXACTLY these files:
+      ui/components/ShelfPickerSheet.kt          (new file, create it)
+      ui/scan/ScanScreen.kt
+      ui/scan/ScanViewModel.kt
+      ui/detail/DetailScreen.kt
+      ui/detail/DetailViewModel.kt
+      data/prefs/SettingsStore.kt
+      app/app/src/test/**                         (tests you add)
+  (paths relative to app/app/src/main/java/org/modg/bookshelf/)
+  Touch NOTHING else. Specifically forbidden: any build file
+  (`app/build.gradle.kts`, `gradle/libs.versions.toml`), `data/metadata/**`
+  (the ORCHESTRATOR is editing that right now, in this same working tree),
+  `ui/locations/**`, `ui/library/**`, `ui/nav/**`, `ui/settings/**`,
+  `ui/setup/**`, `AppContainer.kt`, and every file in `ui/components/` EXCEPT the
+  new `ShelfPickerSheet.kt` you create.
+- Do not change any public composable signature. `ui/nav/BookshelfNavHost.kt`
+  calls these screens and you may not edit it.
+- `AppContainer.settingsStore` is already a public val — you do NOT need to change
+  AppContainer to reach it.
+
+## Background: what the user actually reported
+They are shelving books a box at a time, scanning a run of books that all belong
+on the SAME shelf. Two complaints:
+1. The shelf dropdown lists every bookcase×shelf pair in one flat menu. With more
+   than a couple of bookcases that is unusable.
+2. Re-picking the same shelf for every book in the box is tedious.
+
+## Task 1 — a grouped shelf picker, replacing the flat dropdown
+There are currently TWO near-duplicate flat pickers:
+  - `ShelfPicker` in `ScanScreen.kt` (~line 477)
+  - the location picker inside `DetailScreen.kt` (~line 273-310)
+Both build a `DropdownMenu` containing "Not shelved" followed by one flat item per
+(bookcase, shelf) pair, labelled "Bookcase • Shelf".
+
+Replace BOTH with ONE new shared composable in `ui/components/ShelfPickerSheet.kt`,
+presented as a Material 3 `ModalBottomSheet` rather than a dropdown. Contents, top
+to bottom:
+  a. A "Recent" section — see task 2. Omit the whole section when there is no
+     remembered shelf, or when the remembered shelf no longer exists.
+  b. "Not shelved" as an always-available choice.
+  c. One section per bookcase, in `position` order. The bookcase name is a section
+     header (non-selectable — a bookcase is not a location a book can sit in;
+     only shelves are). Its shelves are listed under it in `position` order,
+     labelled with just the shelf label, since the header already gives the
+     bookcase. Make the currently-selected shelf visually distinct.
+  d. A bookcase with no shelves shows its header and an inline "No shelves yet"
+     hint, so an empty bookcase does not look like a rendering bug.
+The sheet must scroll. Do NOT add a search field — the user explicitly deferred
+that; we will add it later if the grouping alone proves insufficient.
+
+Design language is in SPEC.md ("feels like books") and the existing components in
+`ui/components/` are your reference for type, spacing and the gold hairline rules.
+Reuse `GoldDivider` for section separation rather than inventing a new rule.
+
+## Task 2 — remember the most recently used shelf
+Add a `LAST_SHELF_ID` key to `SettingsStore` (a nullable String preference, with a
+`Flow<String?>` reader, a setter, and a way to clear it), following the exact
+shape of the keys already there. Clear it in `clearAuth()` alongside the rest —
+signing out of a shared library should not leak the other account's shelf.
+
+Write it whenever a book's shelf is set to a non-null value:
+  - `ScanViewModel` — on save, both from a metadata hit and from manual entry.
+  - `DetailViewModel` — when the user changes a book's location.
+Setting a book to "Not shelved" must NOT overwrite the remembered shelf; it isn't
+a shelf, and clobbering the memory with it would defeat the whole feature.
+
+Surface it as the "Recent" section at the top of the picker, labelled with the
+full "Bookcase • Shelf" text (the section has no bookcase header to lean on).
+
+**Do NOT pre-select it.** The user considered and explicitly rejected
+pre-selection: the risk of silently mis-shelving a book, when the user forgets to
+change it, outweighs saving one tap. A new scan still starts with no shelf chosen;
+the remembered shelf is one tap away at the top of the sheet, and that is all.
+
+Note `ScanViewModel._selectedShelfId` already survives across saves within a single
+scanning session (it is deliberately not reset in `recordSave`). Keep that. What
+you are adding is persistence ACROSS sessions and screens.
+
+## Task 3 — three small fixes in ScanScreen.kt
+3a. In `SearchingSheet` (~line 268), delete the third Text, the one reading
+    "Barcode read — you can lower the book." The user says "Searching…" plus the
+    ISBN already carries it. Update the composable's KDoc, which currently
+    justifies that line — do not leave a comment explaining code that is gone.
+
+3b. `LookupFailedSheet` (~line 435) takes a `reason` parameter and never renders
+    it. `ScanSheetState.LookupFailed(isbn13, reason)` already carries a diagnostic
+    string, and `MetadataRepository` already builds it as e.g.
+    "open library: network error; google books: http 429". It is currently dead —
+    it reaches the UI and is dropped on the floor.
+    Render it, below the existing explanatory paragraph, in
+    `MaterialTheme.typography.bodySmall` and `onSurfaceVariant`. This is the only
+    diagnostic channel we have from a real phone, so it must actually appear.
+    Keep the existing headline and paragraph as they are — the reason is
+    supplementary detail, not a replacement for plain-language copy.
+    NOTE: the orchestrator is concurrently making those reason strings more
+    specific. Do not depend on their exact wording — render whatever you are
+    given, and do not parse, match on, or reformat the string.
+
+3c. `ManualIsbnDialog` (~line 512) opens with an unfocused text field. Auto-focus
+    it and raise the keyboard, via `FocusRequester` +
+    `LaunchedEffect(Unit) { focusRequester.requestFocus() }`. Guard the call so it
+    cannot throw if the node is not attached yet.
+
+## Verify before you report (all in the FOREGROUND)
+    ./tasks/gw assembleDebug
+    ./tasks/gw testDebugUnitTest
+    ./tasks/gw recordPaparazziDebug
+    git status --porcelain
+
+- assembleDebug and testDebugUnitTest must exit 0. The test count is 138 today and
+  must not go DOWN. Add real tests for the logic you introduce — at minimum the
+  SettingsStore round-trip, that "Not shelved" does not overwrite the memory, and
+  that a remembered shelf which no longer exists is not offered. Assertion-free
+  tests are explicitly forbidden by SPEC's quality bar.
+- Add a Paparazzi snapshot of the new picker sheet with at least two bookcases,
+  one of them empty, and a recent shelf present — that is the state the whole
+  change exists for, and no one has ever trusted a worker's word on how this app
+  looks.
+- Grep your build output for the string `always 'false'`. That Kotlin warning class
+  silently blanked every book cover in this app for months by making a `when`
+  branch dead code that still compiled. Zero hits on files you touched.
+- `git status --porcelain` will show files the orchestrator and the other worker
+  are editing (`data/metadata/**`, `ui/locations/**`, `ui/library/**`,
+  `res/drawable/**`). That is EXPECTED. Confirm only that no file outside your
+  own list was changed BY YOU. Never revert or "fix" someone else's work.
+- Do not commit. The orchestrator commits after verifying.
+
+## Report
+Finish with a plain report: what you changed per task, exact exit codes and test
+counts, what the new Paparazzi PNG shows, and anything you could NOT do. Do not
+claim success you did not verify — several previous workers on this project
+over-claimed and were caught.

tasks/run-task.sh

@@ -16,6 +16,10 @@ export ANDROID_HOME="$HOME/toolchain/android-sdk"
 export ANDROID_SDK_ROOT="$ANDROID_HOME"
 export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$PATH"
 export GRADLE_USER_HOME="$HOME/.gradle"
+# Wave-4 post-mortem: `claude -p` terminates background tasks after 600s and ends
+# the turn, so a worker that backgrounds a 10-minute Gradle build can never report
+# on it. 0 = wait indefinitely. Worker prompts ALSO require foreground builds.
+export CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0
 cd "$CWD" || exit 1
 
 # Stable session id so a killed run can be resumed rather than restarted.