bookshelf/docs/HANDOFF.md

Bookshelf — session handoff

Written 2026-09-06 by the Opus orchestrator, after a sprite restart forced a fresh session.

Read these first, in order

1. docs/SPEC.md — the authoritative product/technical contract. Unchanged and still correct. Every worker prompt must point at it. Do not restate it; do not let it drift.
2. This file — operational state, what's done, what bit us, what's next.

Operating model (the user explicitly asked for this — keep it)

The user is on the $20/mo Pro plan and wants Opus used sparingly.

• Opus = orchestrator only. Write specs, launch workers, verify results, decide. Do NOT write app code yourself. Do NOT read large files into Opus context.
• Sonnet = all implementation, via claude -p (NOT the Agent tool — the user asked for claude -p specifically, and it keeps worker output out of the orchestrator's context).
• Read worker output via logs/<name>.summary / jq -r '.result', never by cat-ing source.
• Quota status: user reported 62% of the 5h window consumed at ~19:45 on 09-05. Worker A alone cost $2.40 / 85 turns. Budget accordingly; prefer resuming a session over restarting one.

How to launch a worker

cd ~/bookshelf && nohup ./tasks/run-task.sh <NAME> ./tasks/<NAME>.txt >/dev/null 2>&1 &

tasks/run-task.sh is quota-aware: on a usage-limit error it sleeps POLL (600s) and resumes the SAME session rather than restarting, up to MAX_WALL (24h), and does not count quota waits against its 3-strike hard-failure budget. It writes: logs/<name>.json (final result), .err, .sid (session id), .state (progress), .summary.

HAZARD — do not repeat: never edit run-task.sh while workers are running. Bash reads scripts by byte offset; swapping the file mid-run makes live workers resume inside unrelated code and can spawn duplicate claude processes that burn quota on finished work. If you must change it, write a NEW file and use that for the next wave.

Environment

• JDK 21: ~/toolchain/jdk21 (system java is 25 — too new for AGP, do not use it)
• Android SDK: ~/toolchain/android-sdk (platforms;android-37.0, build-tools;37.0.0, platform-tools)
• No KVM, no emulator. Verify only via ./gradlew assembleDebug, JVM unit tests, and Paparazzi PNG rendering. Never claim the app was "run".
• PocketBase v0.40.2 service, 127.0.0.1:8090, deliberately NOT internet-exposed (no --http-port, so the sprite proxy can't reach it). Restart: sprite-env services restart pocketbase. Logs: /.sprite/logs/services/pocketbase.log.
• Superuser creds: server/.dev-credentials (gitignored).

STATE: what is DONE

Wave 1A — server: COMPLETE and verified by the orchestrator (not just self-reported)

server/ contains setup-schema.sh (idempotent), create-user.sh, pb_hooks/main.pb.js, pb_migrations/, deploy/ (systemd unit, Dockerfile, compose, backup.sh, README covering Tailscale vs port-forward+Caddy), README.md, .gitignore.

Independently re-verified on 09-06 after fixing the service:

Check	Result
anonymous LIST books/shelves/bookcases	403 / 403 / 403
anonymous self-registration	403
/api/health	200

pb_hooks/main.pb.js is INTENTIONAL, not scope drift. PocketBase's listRule is a row filter, so anonymous LIST would otherwise return 200 [] instead of an error. The hook forces 403. Keep it; it is why the table above passes. It is auto-loaded by the stock binary.

STATE: what is NOT done

Wave 1B — Android scaffold + design system: INCOMPLETE (killed mid-run by the restart)

Present: gradle wrapper, gradle/libs.versions.toml, app/build.gradle.kts, AndroidManifest.xml, proguard-rules.pro, Literata OFL license. Missing/unverified: ui/theme (Color/Type/Theme), the shared component set, MainActivity, Paparazzi setup, and any evidence the build compiles.

Its session SURVIVED and is resumable — prefer this over a restart (saves quota): claude -p --model sonnet --permission-mode bypassPermissions --output-format json \ --add-dir ~/bookshelf --resume 6823e72a-69c1-486e-ae5a-18abab84529b with a "continue where you left off, don't restart" prompt. (Worker A's session, for reference, is 5e3bd183-252c-4224-99b5-91779761ccbc.) First thing the resumed worker must do: get ./gradlew assembleDebug GREEN. Everything downstream is blocked on it.

Waves 2-4 — not started. Prompts not yet written.

• Wave 2 (parallel, after 1B is green):
  • C — data layer: Room entities/DAOs/DB, PocketBase Retrofit client + auth interceptor, SyncEngine (push-then-pull, LWW, tombstones, client-generated 15-char ids), SettingsStore.
  • D — metadata + scanning: Open Library + Google Books merge, ISBN-13 checksum validation, CameraX + ML Kit continuous scanning.
• Wave 3 (after C+D): E — the six screens (setup, library, detail, scan, locations, settings).
• Wave 4: F — Paparazzi screenshots for the user to judge the look, release keystore + signed APK, top-level README, end-to-end sync test against the live PocketBase.

Gotchas already paid for — do not rediscover

1. Migration filename ↔ _migrations desync. Worker A renamed 1788636563_created_books.js to ...564... to fix an alphabetical-replay ordering bug (books sorted before shelves, breaking the relation). Correct for fresh instances, but the dev DB still had the old name recorded applied, so PocketBase tried to re-create books and crash-looped 9 times. Fixed via UPDATE _migrations SET file=.... If you ever rename a migration, update that table too. DB backup: scratchpad data.db.bak.
2. Rule semantics: in PocketBase "" means PUBLIC, null means superuser-only. Confusing these is exactly how the library would end up world-readable.
3. claude -p --output-format json writes its log only at exit; a 0-byte .json means the worker is still running or was killed, not that it failed.
4. System JDK is 25 and will break AGP. Workers must export JAVA_HOME=~/toolchain/jdk21 (run-task.sh already does).

Verification standard (hold workers to this)

Workers self-report optimistically. Before accepting any wave:

• Re-run the security curls above yourself. The user's stated requirement is that this not be "accessible to everyone in the world"; that check is non-negotiable and cheap.
• Require assembleDebug + test exit 0, and confirm artifacts exist on disk.
• Treat "I couldn't get Paparazzi working so I skipped screenshots" as a finding to report to the user, not something to paper over — the user explicitly cares how this looks.

Open questions for the user (not yet asked — deferred, not forgotten)

• Where the server will actually live (home box vs a sprite) — only affects the deploy README.
• Their two account emails, for create-user.sh. Not needed until the app can log in.