bookshelf/tasks/K-manual.txt

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, especially "Non-negotiables",
     "Design language" and "Screens". Do not contradict it and do not edit it.
  2. The files named below, and their neighbours, before you write anything.

## The gap

There is currently NO way to add a book that has no barcode. Every path into
"save a book" starts from an ISBN:
  - The scan screen's keyboard button (`ui/scan/ScanScreen.kt`, `showManualEntry`)
    only accepts an ISBN and then runs a metadata lookup on it.
  - `ManualEntrySheet` (ScanScreen.kt) only appears after a lookup comes back
    NotFound / LookupFailed, and `ScanViewModel.saveManualEntry(isbn13: String, ...)`
    REQUIRES an ISBN.
Older books, pamphlets, self-published and foreign books often have no ISBN at all.
The data layer already supports this: `BookRepository.createBook(isbn13: String? = null, ...)`
takes every field as optional except title. This wave is UI + navigation work.

A follow-up wave (online search, runs right after you) will navigate into what you
build here with a pre-filled title, and possibly other pre-filled fields. Design for
that; do not build the search.

## What to build

### 1. An "Add a book by hand" screen

New package `org.modg.bookshelf.ui.add` — `AddBookScreen` + `AddBookViewModel`.
A full screen (not a sheet: the library has no camera context, and this form is
longer than the scan sheet's two fields). Fields, all optional except Title:
  Title (required), Subtitle, Authors (comma-separated, same convention as
  ManualEntrySheet), Publisher, Published (free text — SPEC's `publishedDate` is a
  text field; "1960" and "1999-04" are both legitimate), Pages (digits only),
  ISBN, Description, and a shelf picker.

- **Pre-fill.** Model the form as a plain data class (e.g. `BookDraft`) and let the
  ViewModel take an initial draft. Add a route in `ui/nav/Routes.kt` with OPTIONAL
  query arguments for at least `title` and `isbn`, e.g. `add?title={title}&isbn={isbn}`
  plus a helper `Routes.addBook(title: String? = null, isbn: String? = null)` that
  URL-encodes its arguments. (Titles contain `&`, `?`, `/`, `#` — test that the
  helper round-trips them.) The next wave may extend the draft; keep the draft →
  form mapping in one place so that is a small change.
- **ISBN is optional but never silently discarded.** Blank = no ISBN. Non-blank must
  parse via `IsbnUtils.toIsbn13` (accepts ISBN-10 or -13, with or without hyphens);
  if it does not, mark the field in error with a message and disable Save. Wave 5
  fixed exactly this silent-discard bug in the manual-ISBN dialog — do not
  reintroduce it. Store the normalized ISBN-13; also store the ISBN-10 when the user
  typed a valid ISBN-10.
- **Duplicate warning.** If the parsed ISBN-13 is already owned
  (`BookRepository.findByIsbn13`), show the same kind of warning the scan sheet
  shows (`DuplicateCheck` / `DuplicateStatus` in `ui/scan/ScanModels.kt` — reuse,
  do not duplicate). It is a warning, not a block: two copies of a book is legal.
- **Shelf picker.** Reuse the existing shelf picker exactly as the scan sheet uses it
  (`ui/components/ShelfPickerSheet.kt` and the `ShelfPicker` call in ScanScreen.kt),
  including pre-selecting the remembered last shelf from `SettingsStore`, and
  remembering the chosen shelf on save the same way `ScanViewModel.rememberShelf` does.
- **Two save actions**, because SPEC's real use case is shelving a box of books:
  "Save" — saves, then navigates to the new book's detail screen, removing the add
  screen from the back stack (so Back from detail returns to the library).
  "Save & add another" — saves, clears the form but KEEPS the shelf, shows a short
  confirmation naming the saved title, and a running count, and puts focus back in
  Title.
- **Saving must not crash or lose the form.** Wave 8 made the lookup path
  exception-safe but flagged that SAVE paths still make unguarded Room calls. Guard
  yours: catch `Throwable` around the save, RETHROW `CancellationException` first
  (`kotlinx.coroutines.CancellationException`), and on failure keep the typed form
  and show an error naming the exception class (not its message). Disable the save
  buttons while a save is in flight so a double-tap cannot create two books.
- Offline-first (SPEC): Room only. Nothing on this screen touches the network.
- IME: Next between fields, sensible keyboard types (Number for pages, capitalize
  words for title/authors), and make sure the focused field is not hidden behind
  the keyboard — the setup screen hit this; see how it was fixed there
  (`safeDrawingPadding` outside `verticalScroll`, `adjustResize` is already set).
- **Split a stateless `AddBookContent(state, callbacks)` out of the screen** so the
  Paparazzi snapshot renders the REAL composable. Wave 6 shipped a hand-rolled
  lookalike snapshot for Locations and it is recorded in HANDOFF.md as a known
  soft spot; do not repeat that.

### 2. Entry points

- **Library screen** (`ui/library/LibraryScreen.kt`): add an entry point next to the
  scan FAB. Use a Material 3 pattern that keeps Scan as the primary action — e.g. a
  `SmallFloatingActionButton` ("Add by hand", edit/pencil-style icon) stacked above
  the main FAB. Pick what looks right against SPEC's design language; justify it in
  your report. Also give the empty state a secondary "Add by hand" action next to
  "Scan a book". New `LibraryScreen` parameter, wired in `BookshelfNavHost`.
- **Scan screen**: the manual-ISBN dialog (the keyboard button) gets a clear
  secondary action like "No ISBN? Enter the details by hand" that navigates to the
  add screen. New `ScanScreen` callback parameter, wired in `BookshelfNavHost`.
- Leave the in-scan `ManualEntrySheet` (post-lookup NotFound/LookupFailed) as it is —
  it keeps the scanned ISBN and continuous-scan flow. You may give it a
  "More fields…" action that opens the add screen pre-filled with that ISBN and the
  title/authors typed so far, if it is small; otherwise leave it and say so.

## Constraints — these are hard

- Kotlin, Compose, Material 3. Match surrounding code's style, naming and comment
  density (this codebase comments the evidence for a decision, not a restatement of
  the code). Read neighbouring files first.
- You MAY touch: new `ui/add/`, `ui/nav/`, `ui/library/`, `ui/scan/` (entry point
  and optional "More fields…" only), `ui/components/` (only if a shared piece must
  move there to be reused), and tests. Nothing else.
- DO NOT touch: any build file (`app/app/build.gradle.kts`, `gradle/libs.versions.toml`,
  etc.), `data/**`, `server/`, `docs/`. If you believe you need a dependency or a
  data-layer change, STOP and say so in your report. Everything above is doable with
  what exists (`createBook` already takes all these fields).
- DO NOT read, print or grep `app/local.properties`.
- DO NOT git commit, add or push. Leave the work in the working tree.
- Build with `./tasks/gw <task>` — NEVER `./gradlew` directly (flock-serialized wrapper).
- RUN BUILDS IN THE FOREGROUND. Never background a Gradle build and end your turn
  saying you will report later — you will never get to. Several previous workers on
  this project did exactly that. A build takes 1-5 minutes; wait for it.
- No emulator on this box. You cannot run the app. Do not claim you did.

## Definition of done

Run these yourself, in the foreground, and paste the real output tails:

  ./tasks/gw assembleDebug          -> exit 0
  ./tasks/gw testDebugUnitTest      -> exit 0. **205 tests today, 2 skipped** (both
                                       opt-in live tests). Count must go UP; nothing
                                       may regress. Sum the TEST-*.xml files
                                       (app/app/build/test-results/testDebugUnitTest/)
                                       — do not read the console.
  ./tasks/gw recordPaparazziDebug   -> exit 0
  ./tasks/gw verifyPaparazziDebug   -> exit 0 against the re-recorded snapshots

Required tests with REAL assertions (assertion-free tests violate SPEC):
  - `Routes.addBook` round-trips titles containing `&`, `?`, `/`, `#`, spaces and
    non-ASCII (e.g. "Hänsel & Gretel / Part 1?"), and omits absent args.
  - Draft validation: blank title disables save; blank ISBN is valid (saves null);
    ISBN-10 is normalized to ISBN-13 and the ISBN-10 kept; a bad checksum is an
    error, not a silent drop; non-digit pages rejected.
  - ViewModel: save calls `createBook` with every field mapped (authors split and
    trimmed, empty entries dropped); duplicate ISBN produces the AlreadyOwned
    warning; "save & add another" clears fields but keeps the shelf and increments
    the count; a repository that throws leaves the form intact with an error and
    does not throw; a `CancellationException` is NOT swallowed; a second save while
    one is in flight does not create a second book.
  - Paparazzi (light + dark, in `ui/screens/` alongside the others): the empty form,
    a filled form with a duplicate-ISBN warning, and the ISBN-error state. Plus the
    library screen with the new FAB, re-recorded.

Also grep the build output for Kotlin warnings on files you touched. "Check for
instance is always 'false'" is NOT cosmetic — it hid a bug that blanked every book
cover in this app for months.

## Report

End with a plain report:
  - what you changed, file by file
  - verbatim tails of each gradle command above
  - test count before and after, summed from the XML
  - the exact route string and `Routes.addBook` signature, and how `BookDraft` is
    passed in — the next wave's worker will read this report to build on it
  - judgement calls you made (FAB pattern, "More fields…" yes/no) and why
  - anything you could NOT do or did differently, and why
  - anything you noticed that looks wrong but was out of scope

Be honest. Workers here have over-claimed before, and everything is re-verified, so
an inflated report only wastes a round trip.