BookSwapKMP · plan

Where we are going

Long-term goal
Unlock the world's idle bookshelves by turning every reader's home collection into a connected, walking-distance neighborhood library.
Product spec (PRD) — BookSwap — Product Requirements (Phase 1) · docs/PRD.md · 170 lines · collapsed — expand to read

BookSwap — Product Requirements (Phase 1)

Vision. Eliminate dead shelf capital by turning every reader's home collection into a tradable library that can be exchanged within walking distance.

The whole surface is four pillars. A tradable library, two exchange modes (temporary or permanent), structured offer cards, and a visible trust score. Anything else is out of scope.

Sources of truth. This document is written from .pipeline/design-intake-2026-11-09.md, the live backend contract in docs/backend-contract.md, the design law in docs/design.md (Stitch project 6316778772167622129, Kinfolk & Folio) and the code on main.


1. Who it is for

Success means a first-time reader can install the app, sign in with Google, set a coarse area, find a nearby copy, agree a temporary or permanent exchange with structured cards, meet safely, and confirm it by QR — without a single dead end or fabricated success.


2. Product principles

  1. Neighbourly high trust. Every actor has a trust passport built from real completed handshakes, on-time returns and condition accuracy.
  2. Physical, not commercial. Borrow, hand off, swap, curate. No carts, no "Buy Now", no countdown pressure.
  3. Live data or nothing. A screen never invents a number, a venue, a token or a book. Missing facts are shown as missing, with the next action.
  4. Privacy by default. Only approximate location is requested; the database fuzzes coordinates; addresses are never exchanged; handshakes happen in verified public places.

3. Phase 1 scope and acceptance

3.1 Identity — Google sign-in end to end

3.2 Location — coarse and changeable

3.3 Discovery, search and radar

3.4 Book detail, borrow or swap, safe meetup

3.5 QR handoff, borrow timer and return

3.6 Shelf and one-photo AI onboarding

3.7 Neighbour trust passport

3.8 Exchange modes and offer cards


4. Phase 2 (deferred, not designed away)

CapabilityWhy it waits
Overdue freeze and disputesNeeds a scheduled overdue scan and persisted arbitration; Phase 1 already has the verified return scan.
Push notificationsPhase 1 delivers in-app state; push is a delivery channel, not the feature.
WhatsApp/SMS remindersSame: the due date and grace period exist; the reminder channel comes later.
Apple / GitHub sign-inProviders are off in the current Supabase project; the menu hides them until they are enabled.

5. Backend contract (live)

SurfaceEndpointNotes
Feed / search / radarPOST /functions/v1/ui-composer, rpc_search_local_booksSDUI blocks, SSE, zero-result radar
Book detailGET /api/v1/books/{listing_id}listing facts, condition, owner trust tier
Shelf + wishlistGET /api/v1/users/{user_id}/shelflibrary, wishes, stats
Borrow / swapPOST /api/v1/trades/requestauthenticated as the caller; DB row lock
Handoff QRGET /api/v1/handoff/{transaction_id}/qrcaller's own signed token
Verify handoffPOST /api/v1/handoff/verifyHANDOFF_SCHEDULED → ACTIVE_BORROW, due date
MeetupGET/POST /api/v1/trades/{id}/meetupmidpoint, venue, accepted time, alternate
Returnrpc_get_return_qr, rpc_verify_returncompletes the loan, relists the book
Vision scannerPOST /functions/v1/vision-shelf-scannerbooks[] with title, author, confidence
Shelf publishPOST /api/v1/shelf/publishwrites user_books as the caller
PassportGET /api/v1/users/{user_id}/passportsingle trust aggregate
Vibe railrpc_search_by_vibe_and_geo768-d embedding similarity

Authenticated writes carry the caller's JWT; auth.uid() is never null on a user-scoped path. RLS and security-definer checks are not bypassed.


6. Non-goals for Phase 1


7. Success measures


8. Release policy

Phase 1 builds land on internal testing. Promotion beyond internal testing is an owner decision made in this conversation; the agent never raises it. A build that carries a fix must be a new version — the rejected 1.0.1-rc.2 is never resubmitted.

Design: 13 UI features ask the designer at build time · 7 answered · 2 backend-only

Sub-goals the ends · order is priority

A great experienceIn progress
Users get a product that does the thing it promises, without friction, confusion or a crash.
95 of 95 tasks built · 20 features
Design law aligned with the Stitc… P1Google sign-in and precise, profi… P1Neighborhood discovery, search an… P1Book detail and one structured of… P1Optional in-person confirmation P1Shelf and one-photo AI vision onb… P1Neighbor trust passport P1Store listing and installed app p… P1Scope lock P1My Tradable Library is the whole… P1Screen set is redesigned from the… P1Wishes are ads; one offer composer P1Offer page P1Search says one calm sentence, no… P1Agent work goes through A2A, one… P1One product name on screen and in… P1The Play listing follows the prod… P1The feed answers, or says plainly… P1The codebase carries only what sh… P1The product runs in a desktop bro… P2
Users stayPlanned
People who install keep using it — the product earns a place in their day.
0 of 0 tasks built · 2 features
Optional in-person confirmation P1Neighbor trust passport P1
Users payPlanned
The product earns subscription revenue from the users it keeps.
0 of 0 tasks built · 0 features
No feature yet.

Phase 1 95 of 95 built

Optional in-person confirmation
Phase 1Planned
Serves: A great experienceUsers stay
Two readers who meet in person can confirm the swap with one optional scan, which closes the deal and records the trust event. Where and when they meet is never part of the app.
No task queued for this feature.
how we will know it is done
  • A scan is offered from the accepted Offer page as an optional confirmation; it is never required to keep or see the agreement.
  • One scan by the counterpart closes the swap and writes exactly one trust event. There is no timer, due date, return code, extension or overdue state anywhere.
  • A swap the readers never scan can still be closed by both tapping Done on the Offer page.
technical detail
  • id: f_qr_handoff
  • status: pending
  • phase: 1
  • serves: goal-experience, goal-retention
My Tradable Library is the whole inventory
Phase 1In progress14 of 14 built — all of them
Serves: A great experience
Design · new screen required
Every book a reader owns is tradable inventory in exactly two states, available or locked, under one of two exchange modes.
✓
Tradable library inventory v?
in My Tradable Library is the whole inventory
technical detail
  • id: tradable-library-inventory
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
✓
Bugfix the bookswap app library 2026 11 12 v1.0.38
in My Tradable Library is the whole inventory
technical detail
  • id: bugfix-the-bookswap-app-library-2026-11-12
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
✓
A copy says when it comes back v1.0.44
in My Tradable Library is the whole inventory
technical detail
  • id: a-copy-says-when-it-comes-back
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/androidUnitTest/kotlin/agrawal/bhanu/bookswap/sdui/ContentEnvelopeTest.kt
✓
Bugfix thhe bookswap app make 2026 11 13 v1.0.48-rc.1
in My Tradable Library is the whole inventory
technical detail
  • id: bugfix-thhe-bookswap-app-make-2026-11-13
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
✓
Bugfix shelf review publishes what it says 2026 11 15 v1.0.72
in My Tradable Library is the whole inventory
technical detail
  • id: bugfix-shelf-review-publishes-what-it-says-2026-11-15
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/library/**
✓
Feature scan and add books flow 2026 11 16 v1.0.73
in My Tradable Library is the whole inventory
technical detail
  • id: feature-scan-and-add-books-flow-2026-11-16
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/library/**
✓
Bugfix build room one library 2026 11 17 v1.0.77
in My Tradable Library is the whole inventory
technical detail
  • id: bugfix-build-room-one-library-2026-11-17
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
✓
Bugfix let adding book when 2026 11 17 v1.0.78-rc.3
in My Tradable Library is the whole inventory
technical detail
  • id: bugfix-let-adding-book-when-2026-11-17
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
✓
Revamp remove local lookup thata 2026 11 17 v?
in My Tradable Library is the whole inventory
technical detail
  • id: revamp-remove-local-lookup-thata-2026-11-17
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
✓
Bugfix system design interview book 2026 11 17 v1.0.78
in My Tradable Library is the whole inventory
technical detail
  • id: bugfix-system-design-interview-book-2026-11-17
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
✓
Bugfix another issue library data 2026 11 17 v1.0.79
in My Tradable Library is the whole inventory
technical detail
  • id: bugfix-another-issue-library-data-2026-11-17
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
✓
Bugfix a borrowed book needs its own section 2026 11 18 v1.0.81
in My Tradable Library is the whole inventory
technical detail
  • id: bugfix-a-borrowed-book-needs-its-own-section-2026-11-18
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/library/MyLibraryScreen.kt
✓
Feature instrument app with analytics 2026 11 18 v1.0.82-rc.1
in My Tradable Library is the whole inventory
technical detail
  • id: feature-instrument-app-with-analytics-2026-11-18
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
✓
Bugfix loggin accound bhanuagrawal001 the 2026 11 18 v1.0.82
in My Tradable Library is the whole inventory
technical detail
  • id: bugfix-loggin-accound-bhanuagrawal001-the-2026-11-18
  • type: —
  • advances: my-tradable-library-is-the-whole-inventory
  • target: composeApp/src/commonMain/**
how we will know it is done
  • My Library holds only books the reader will trade, each Available or Locked in an active trade, with its condition tier, the smoke-free, pet-free and highlights facts, and its mode: temporary, permanent or both.
  • Books the reader is currently borrowing appear in a separate Borrowed (Must Return) section and cannot enter the tradable library, enforced by the backend.
  • A duplicate scan is skipped with 'Already in your Library' and a second-copy escape, and a temporary return flips the copy back to Available while a permanent handover removes it.
  • Every listing can be edited, paused or removed, and a locked listing says which trade holds it.
technical detail
  • id: my-tradable-library-is-the-whole-inventory
  • status: active
  • phase: 1
  • serves: goal-experience
Screen set is redesigned from the block contract
Phase 1Planned22 of 22 built — all of them
Serves: A great experience
Design · tweak Discovery - Instant Swap (Bengaluru)
The app is designed top-down from seven block templates in four slots, on the existing Kinfolk and Folio palette and typography, so every screen is a composition of the same system rather than a screen that grew alongside the code.
✓
Stitch redesign from block contract v?
in Screen set is redesigned from the block contract
technical detail
  • id: stitch-redesign-from-block-contract
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: docs/stitch/**
✓
Design copy and state fixes v?
in Screen set is redesigned from the block contract
technical detail
  • id: design-copy-and-state-fixes
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: docs/stitch/**
✓
Revamp plan this for phase 2026 11 11 v1.0.22-rc.3
in Screen set is redesigned from the block contract
technical detail
  • id: revamp-plan-this-for-phase-2026-11-11
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Visual borrow button still there 2026 11 11 v1.0.22-rc.5
in Screen set is redesigned from the block contract
technical detail
  • id: visual-borrow-button-still-there-2026-11-11
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Fix this mess have 2026 11 11 v1.0.24
in Screen set is redesigned from the block contract
technical detail
  • id: fix-this-mess-have-2026-11-11
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: docs/stitch/**
✓
Visual fix this mess have 2026 11 11 v1.0.33
in Screen set is redesigned from the block contract
technical detail
  • id: visual-fix-this-mess-have-2026-11-11
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: docs/stitch/**
✓
Feature timeout should increased app 2026 11 12 v1.0.40-rc.2
in Screen set is redesigned from the block contract
technical detail
  • id: feature-timeout-should-increased-app-2026-11-12
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Revamp donot need the bookmark 2026 11 12 v1.0.40
in Screen set is redesigned from the block contract
technical detail
  • id: revamp-donot-need-the-bookmark-2026-11-12
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Feature our app must expose 2026 11 12 v1.0.41-rc.2
in Screen set is redesigned from the block contract
technical detail
  • id: feature-our-app-must-expose-2026-11-12
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Visual just remove the your 2026 11 12 v1.0.41-rc.4
in Screen set is redesigned from the block contract
technical detail
  • id: visual-just-remove-the-your-2026-11-12
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/wishes/**
✓
Bugfix home streams instead of waiting for the end v1.0.41-rc.6
in Screen set is redesigned from the block contract
technical detail
  • id: bugfix-home-streams-instead-of-waiting-for-the-end
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/data/BookSwapRepository.kt
✓
Storefront regenerate assets 2026 11 12 v1.0.41-rc.8
in Screen set is redesigned from the block contract
technical detail
  • id: storefront-regenerate-assets-2026-11-12
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Feature tools are also dynamic 2026 11 13 v1.0.43-rc.1
in Screen set is redesigned from the block contract
technical detail
  • id: feature-tools-are-also-dynamic-2026-11-13
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Feature redesign login screen its 2026 11 13 v1.0.48-rc.2
in Screen set is redesigned from the block contract
technical detail
  • id: feature-redesign-login-screen-its-2026-11-13
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Visual offers and passport page 2026 11 14 v1.0.49-rc.1
in Screen set is redesigned from the block contract
technical detail
  • id: visual-offers-and-passport-page-2026-11-14
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Feature our SDUI completely dynamic 2026 11 14 v1.0.49
in Screen set is redesigned from the block contract
technical detail
  • id: feature-our-sdui-completely-dynamic-2026-11-14
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Feature app home should completely 2026 11 14 v1.0.50-rc.1
in Screen set is redesigned from the block contract
technical detail
  • id: feature-app-home-should-completely-2026-11-14
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Feature home is a renderer 2026 11 14 v1.0.50
in Screen set is redesigned from the block contract
technical detail
  • id: feature-home-is-a-renderer-2026-11-14
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/DiscoveryScreen.kt
✓
Bugfix also theri limit cards 2026 11 14 v1.0.51
in Screen set is redesigned from the block contract
technical detail
  • id: bugfix-also-theri-limit-cards-2026-11-14
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/sdui/Tools.kt
✓
Feature ship the single navigate 2026 11 14 v1.0.53
in Screen set is redesigned from the block contract
technical detail
  • id: feature-ship-the-single-navigate-2026-11-14
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/**
✓
Feature home cache login public preview 2026 11 14 v1.0.57
in Screen set is redesigned from the block contract
technical detail
  • id: feature-home-cache-login-public-preview-2026-11-14
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/DiscoveryViewModel.kt
✓
Bugfix no control pretends 2026 11 14 v1.0.59
in Screen set is redesigned from the block contract
technical detail
  • id: bugfix-no-control-pretends-2026-11-14
  • type: —
  • advances: screen-set-matches-the-v2-product-updated-in-place
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/auth/AuthScreen.kt
how we will know it is done
  • The redesign starts from the block contract, not from the current screens: every template is drawn in every slot it can occupy, and no layout is inherited just because it exists today.
  • The dock carries four destinations - Discover, Scan Shelf, Offers, Library - and Passport is reached from the header. The borrow-era Trade and Handoff tabs and every screen behind them are gone.
  • The palette, type scale and shared components stay Kinfolk and Folio; no second visual language appears, and no retired block or action is drawn anywhere.
  • Every exported screen lives under docs/stitch/screens/<id>/ as index.html plus screen.png, is listed in the manifest, and docs/design.md names the block system instead of a screen list.
technical detail
  • id: screen-set-matches-the-v2-product-updated-in-place
  • status: pending
  • phase: 1
  • serves: goal-experience
Wishes are ads; one offer composer
Phase 1Planned17 of 17 built — all of them
Serves: A great experience
Design · tweak My Library
A reader posts what they want and what they will give, and the app finds the neighbour who wants their copy in return.
✓
Wishes and two way match v?
in Wishes are ads; one offer composer
technical detail
  • id: wishes-and-two-way-match
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Visual new wish shit the 2026 11 11 v1.0.22-rc.4
in Wishes are ads; one offer composer
technical detail
  • id: visual-new-wish-shit-the-2026-11-11
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Bugfix while searching for book 2026 11 12 v1.0.32
in Wishes are ads; one offer composer
technical detail
  • id: bugfix-while-searching-for-book-2026-11-12
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Feature reader nearby are looking 2026 11 13 v1.0.41
in Wishes are ads; one offer composer
technical detail
  • id: feature-reader-nearby-are-looking-2026-11-13
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/DiscoveryScreen.kt
✓
Wishes leave home v1.0.44
in Wishes are ads; one offer composer
technical detail
  • id: wishes-leave-home
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/wishes/**
✓
Bugfix home requests card showed 2026 11 14 v1.0.52
in Wishes are ads; one offer composer
technical detail
  • id: bugfix-home-requests-card-showed-2026-11-14
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Bugfix the swap destination opened 2026 11 14 v1.0.54
in Wishes are ads; one offer composer
technical detail
  • id: bugfix-the-swap-destination-opened-2026-11-14
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Feature readers nearby are looking 2026 11 14 v1.0.55
in Wishes are ads; one offer composer
technical detail
  • id: feature-readers-nearby-are-looking-2026-11-14
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Feature encode the full offer 2026 11 14 v1.0.56
in Wishes are ads; one offer composer
technical detail
  • id: feature-encode-the-full-offer-2026-11-14
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Feature user should aware offering 2026 11 14 v1.0.60-rc.1
in Wishes are ads; one offer composer
technical detail
  • id: feature-user-should-aware-offering-2026-11-14
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Feature offer composer and page 2026 11 15 v1.0.61
in Wishes are ads; one offer composer
technical detail
  • id: feature-offer-composer-and-page-2026-11-15
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Feature offer screen one composer 2026 11 15 v1.0.68
in Wishes are ads; one offer composer
technical detail
  • id: feature-offer-screen-one-composer-2026-11-15
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Bugfix make offer book the 2026 11 15 v1.0.69
in Wishes are ads; one offer composer
technical detail
  • id: bugfix-make-offer-book-the-2026-11-15
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Bugfix when offer created other 2026 11 15 v1.0.70
in Wishes are ads; one offer composer
technical detail
  • id: bugfix-when-offer-created-other-2026-11-15
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Bugfix bhanuagrawal001 answered the wish 2026 11 17 v1.0.77-rc.1
in Wishes are ads; one offer composer
technical detail
  • id: bugfix-bhanuagrawal001-answered-the-wish-2026-11-17
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Bugfix don need legacy support 2026 11 17 v1.0.78-rc.2
in Wishes are ads; one offer composer
technical detail
  • id: bugfix-don-need-legacy-support-2026-11-17
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/**
✓
Bugfix offer composer send and prefill 2026 11 17 v1.0.80
in Wishes are ads; one offer composer
technical detail
  • id: bugfix-offer-composer-send-and-prefill-2026-11-17
  • type: —
  • advances: wishes-and-the-two-way-matchmaker
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/offers/**
how we will know it is done
  • Replying to an ad and offering on a copy open ONE composer, with the reader's own copy and one of the ad's copies already suggested and every side changeable before sending; prefill never writes the note and never sends.
  • The composer keeps one book each way from two cited copy ids, and the handshake no longer advertises an argument nothing reads (reply_wish drops wantedWorkId/wantedTitle), so the catalog fingerprint moves with it.
  • Home carries at least one list the reader can open, named by their shelf or by themes the rows share — never 'Available nearby' — and while the planner thinks the stream says what the server is doing, never a forecast.
technical detail
  • id: wishes-and-the-two-way-matchmaker
  • status: pending
  • phase: 1
  • serves: goal-experience
Offer page: propose, revise, accept, close
Phase 1Planned9 of 9 built — all of them
Serves: A great experience
Design · tweak Deal from arjun
Each swap is one page both readers see: the book wanted, the copies offered, a short note, and a version history of who proposed what. Only the reader whose turn it is can accept; either side can revise or withdraw.
✓
Bugfix app show borrow still 2026 11 11 v1.0.25
in Offer page
technical detail
  • id: bugfix-app-show-borrow-still-2026-11-11
  • type: —
  • advances: structured-offer-cards-never-chat
  • target: composeApp/src/commonMain/**
✓
Bugfix get rid this direct 2026 11 11 v1.0.26
in Offer page
technical detail
  • id: bugfix-get-rid-this-direct-2026-11-11
  • type: —
  • advances: structured-offer-cards-never-chat
  • target: composeApp/src/commonMain/**
✓
Bugfix user does not see 2026 11 11 v1.0.31
in Offer page
technical detail
  • id: bugfix-user-does-not-see-2026-11-11
  • type: —
  • advances: structured-offer-cards-never-chat
  • target: composeApp/src/commonMain/**
✓
Bugfix these options are not 2026 11 12 v1.0.34
in Offer page
technical detail
  • id: bugfix-these-options-are-not-2026-11-12
  • type: —
  • advances: structured-offer-cards-never-chat
  • target: composeApp/src/commonMain/**
✓
Feature after accepting the offer 2026 11 12 v1.0.35
in Offer page
technical detail
  • id: feature-after-accepting-the-offer-2026-11-12
  • type: —
  • advances: structured-offer-cards-never-chat
  • target: composeApp/src/commonMain/**
✓
Bugfix the app crashes when 2026 11 12 v1.0.36
in Offer page
technical detail
  • id: bugfix-the-app-crashes-when-2026-11-12
  • type: —
  • advances: structured-offer-cards-never-chat
  • target: composeApp/src/commonMain/**
✓
Bugfix clicked revised offer cta 2026 11 14 v1.0.58-rc.1
in Offer page
technical detail
  • id: bugfix-clicked-revised-offer-cta-2026-11-14
  • type: —
  • advances: structured-offer-cards-never-chat
  • target: composeApp/src/commonMain/**
✓
Bugfix check phone connect book 2026 11 15 v1.0.72-rc.1
in Offer page
technical detail
  • id: bugfix-check-phone-connect-book-2026-11-15
  • type: —
  • advances: structured-offer-cards-never-chat
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/offers/**
✓
Bugfix for the book swap 2026 11 16 v1.0.72-rc.2
in Offer page
technical detail
  • id: bugfix-for-the-book-swap-2026-11-16
  • type: —
  • advances: structured-offer-cards-never-chat
  • target: composeApp/src/commonMain/**
how we will know it is done
  • Make Offer from a book detail opens the one offer composer: the copy the reader gives and the copy they take (or a note), sent as offer version 1.
  • The Offer page shows both copies, the note, and every prior version as a card. No chat bubble, typing indicator or read receipt appears anywhere.
  • Only the counterpart of the latest offer can accept; either side can revise or withdraw, and each action bumps offer_version and records who did it.
  • An accepted offer becomes the swap pass: both books, both first names and areas, one editable note per side, and a Share button. The app never asks where or when to meet.
  • An offer with neither a book nor a note is refused, and two concurrent accepts on one copy leave exactly one accepted deal.
technical detail
  • id: structured-offer-cards-never-chat
  • status: pending
  • phase: 1
  • serves: goal-experience
Search says one calm sentence, not a backend log
Phase 1Planned7 of 7 built — all of them
Serves: A great experience
Design · new screen required
A reader opens the app or searches a messy query and the screen stays quiet: one plain sentence while it looks, one when it answers, and a retry when something fails. Results still stream in as typed blocks; nobody sees the pipeline.
✓
Home is agent composed no radius v1.0.44
in Search says one calm sentence, not a backend log
technical detail
  • id: home-is-agent-composed-no-radius
  • type: —
  • advances: search-is-a-live-agent-not-a-spinner
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/App.kt
✓
Radius is the backends decision v1.0.44
in Search says one calm sentence, not a backend log
technical detail
  • id: radius-is-the-backends-decision
  • type: —
  • advances: search-is-a-live-agent-not-a-spinner
  • target: docs/backend-contract.md
✓
Bugfix login domain config v1.0.45
in Search says one calm sentence, not a backend log
technical detail
  • id: bugfix-login-domain-config
  • type: —
  • advances: search-is-a-live-agent-not-a-spinner
  • target: composeApp/src/debug/AndroidManifest.xml
✓
Search is a fast deterministic list v1.0.46
in Search says one calm sentence, not a backend log
technical detail
  • id: search-is-a-fast-deterministic-list
  • type: —
  • advances: search-is-a-live-agent-not-a-spinner
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/search/**
✓
Feature dont want search every 2026 11 13 v1.0.47
in Search says one calm sentence, not a backend log
technical detail
  • id: feature-dont-want-search-every-2026-11-13
  • type: —
  • advances: search-is-a-live-agent-not-a-spinner
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/ui/search/**
✓
Bugfix check bookswap app noticed 2026 11 14 v1.0.58
in Search says one calm sentence, not a backend log
technical detail
  • id: bugfix-check-bookswap-app-noticed-2026-11-14
  • type: —
  • advances: search-is-a-live-agent-not-a-spinner
  • target: composeApp/src/commonMain/**
✓
Bugfix bookswap swap user seeing 2026 11 15 v1.0.71-rc.1
in Search says one calm sentence, not a backend log
technical detail
  • id: bugfix-bookswap-swap-user-seeing-2026-11-15
  • type: —
  • advances: search-is-a-live-agent-not-a-spinner
  • target: composeApp/src/commonMain/**
how we will know it is done
  • The stream still carries one status event per real stage (resolve, scan, expand, similar, wish-match), but the reader sees one plain sentence and a progress indicator, never stage names or a step counter.
  • Home and search render the same seven block templates into their slots, and a block whose condition does not apply is omitted rather than sent empty.
  • A block re-sent under the same artifactId replaces in place without moving scroll, asserted by a test that enriches a card with an instant-swap reason.
  • A failed part of a search is said in the reader terms with a retry, and transport detail stays in logs and telemetry. The string 'Agent paused after 0 of 3 steps' appears on no screen, asserted by a test.
  • INSTANT_SWAP appears only from a real wish intersection, and a non-streaming client renders the same blocks through the same templates.
technical detail
  • id: search-is-a-live-agent-not-a-spinner
  • status: pending
  • phase: 1
  • serves: goal-experience
Agent work goes through A2A, one door
Phase 1Planned5 of 5 built — all of them
Serves: A great experience
Design · ask again (design changed)
Every turn where the agent decides or composes something travels over /a2a/v1, and the agent card advertises only capabilities the product actually has.
✓
A2A single door v?
in Agent work goes through A2A, one door
technical detail
  • id: a2a-single-door
  • type: —
  • advances: agent-work-goes-through-a2a-one-door
  • target: composeApp/src/commonMain/**
✓
Bugfix cmp was rejected requires 2026 11 13 v1.0.42
in Agent work goes through A2A, one door
technical detail
  • id: bugfix-cmp-was-rejected-requires-2026-11-13
  • type: —
  • advances: agent-work-goes-through-a2a-one-door
  • target: composeApp/src/commonMain/**
✓
Bugfix get rid koog first 2026 11 13 v1.0.43-rc.2
in Agent work goes through A2A, one door
technical detail
  • id: bugfix-get-rid-koog-first-2026-11-13
  • type: —
  • advances: agent-work-goes-through-a2a-one-door
  • target: composeApp/src/commonMain/**
✓
Revamp use navigation library the 2026 11 13 v1.0.43
in Agent work goes through A2A, one door
technical detail
  • id: revamp-use-navigation-library-the-2026-11-13
  • type: —
  • advances: agent-work-goes-through-a2a-one-door
  • target: composeApp/src/commonMain/**
✓
Agent can send a search v1.0.44
in Agent work goes through A2A, one door
technical detail
  • id: agent-can-send-a-search
  • type: —
  • advances: agent-work-goes-through-a2a-one-door
  • target: composeApp/src/commonMain/kotlin/agrawal/bhanu/bookswap/agent/AgentNavigation.kt
how we will know it is done
  • The agent card lists live skills only and no retired one, and a test fails if a retired skill or streaming=false reappears.
  • The legacy agent routes (ui-composer, trade-negotiator, bounty-radar, dispute-arbiter, workflow/resume, a2a-gateway) answer 404, and the client carries no call to them.
  • A home turn and a search turn both show stage frames over SendStreamingMessage, and the unary path returns the same blocks.
technical detail
  • id: agent-work-goes-through-a2a-one-door
  • status: pending
  • phase: 1
  • serves: goal-experience
One product name on screen and in the store
Phase 1Planned
Serves: A great experience
A reader sees the same product name in the app, on the launcher and in Play, and the design system name never leaks into the UI.
No task queued for this feature.
how we will know it is done
  • No user-facing screen shows 'Folio & Shelf'; the header, onboarding and store copy all say BookSwap.
  • The design-system name stays in the design tooling and docs, never in the interface.
technical detail
  • id: one-product-name-on-screen-and-in-the-store
  • status: pending
  • phase: 1
  • serves: goal-experience
The Play listing follows the product
Phase 1Planned2 of 2 built — all of them
Serves: A great experience
Design · ask again (design changed)
What Play shows — icon, banner, screenshots, listing copy — is drawn from the build a user installs, so a reader who taps the listing recognises the app they open.
✓
Store regerate playstore assets and 2026 11 15 v1.0.65
in The Play listing follows the product
technical detail
  • id: store-regerate-playstore-assets-and-2026-11-15
  • type: —
  • advances: the-play-listing-follows-the-product
  • target: composeApp/src/commonMain/**
✓
Store regenerate play store assets 2026 11 17 v1.0.80
in The Play listing follows the product
technical detail
  • id: store-regenerate-play-store-assets-2026-11-17
  • type: —
  • advances: the-play-listing-follows-the-product
  • target: distribution/listing/en-US/images/phoneScreenshots/01_hero.png
how we will know it is done
  • Every phone screenshot in the listing comes from the current shipped build: no listing asset predates the last release, and storefront-build's freshness check reports CURRENT.
  • The listing carries at least four phone screenshots plus the Stitch icon and the painted feature graphic, each with recorded provenance, and store-publish uploads and reads them back.
technical detail
  • id: the-play-listing-follows-the-product
  • status: pending
  • phase: 1
  • serves: goal-experience
The feed answers, or says plainly why not
Phase 1Planned1 of 1 built — all of them
Serves: A great experience
Design · tweak Sign In With Email And Password (Debug)
A reader on Home always gets either the neighbourhood feed or one plain sentence with a working way out: the transport renews an expiring token before a turn, the header never claims an identity the session lacks, and no door leads onto a screen that needs a session.
✓
Bugfix feed refresh failed you 2026 11 17 v1.0.75
in The feed answers, or says plainly why not
technical detail
  • id: bugfix-feed-refresh-failed-you-2026-11-17
  • type: —
  • advances: the-feed-answers-or-says-plainly-why-not
  • target: composeApp/src/commonMain/**
how we will know it is done
  • An access token that expires mid-session still opens Home after one renewal, with no sign-in prompt.
  • No screen offers a way into the feed without a session; signing out lands on the sign-in screen and stays there.
technical detail
  • id: the-feed-answers-or-says-plainly-why-not
  • status: pending
  • phase: 1
  • serves: goal-experience
The codebase carries only what ships
Phase 1Planned1 of 1 built — all of them
Serves: A great experience
Design · ask the designer
Every target, source set, dependency and CI step in the app belongs to the Android product: no browser build, no web-only platform seams, no dead code kept for a platform that no longer exists.
✓
Revamp remove wasm retire web 2026 11 17 v1.0.76
in The codebase carries only what ships
technical detail
  • id: revamp-remove-wasm-retire-web-2026-11-17
  • type: —
  • advances: the-codebase-carries-only-what-ships
  • target: composeApp/src/commonMain/**
how we will know it is done
  • composeApp declares one target; there is no wasmJs source set, no wasm-only dependency and no web entry point in the build.
technical detail
  • id: the-codebase-carries-only-what-ships
  • status: pending
  • phase: 1
  • serves: goal-experience
Design law aligned with the Stitch system
Phase 1Done1 of 1 built — all of them
Serves: A great experience
The design law and Compose tokens describe the Kinfolk & Folio system the app is built from, so no UI task follows a stale palette or typography.
✓
Design regenerate from stitch v1.0.20-rc.1
in Design law aligned with the Stitch system
technical detail
  • id: design-regenerate-from-stitch
  • type: —
  • advances: f_design_law
  • target: docs/**
how we will know it is done
  • docs/design.md and the theme tokens match Stitch project 6316778772167622129; the old project reference is gone.
  • Every UI task reads the current design law and the five canonical screens.
technical detail
  • id: f_design_law
  • status: done
  • phase: 1
  • serves: goal-experience
Google sign-in and precise, profile-bound location
Phase 1Done8 of 8 built — all of them
Serves: A great experience
Design · tweak Asha Profile & Trust
A reader signs in with Google once, grants precise location for their home shelf (or falls back manually), can update their profile location anytime via PATCH /api/v1/users/me with a clear notice that this is where their books are available, and can separately switch their Home explore location to their current location with persistence.
✓
Google sign in end to end v1.0.20-rc.1
in Google sign-in and precise, profile-bound location
technical detail
  • id: google-sign-in-end-to-end
  • type: —
  • advances: f_identity_location
  • target: composeApp/src/commonMain/**
✓
Feature scrap the layer and 2026 11 09 v1.0.20-rc.6
in Google sign-in and precise, profile-bound location
technical detail
  • id: feature-scrap-the-layer-and-2026-11-09
  • type: —
  • advances: f_identity_location
  • target: composeApp/src/commonMain/**
✓
Flow p0 session restore and request borrow v?
in Google sign-in and precise, profile-bound location
technical detail
  • id: flow-p0-session-restore-and-request-borrow
  • type: —
  • advances: f_identity_location
  • target: composeApp/src/commonMain/**
✓
Feature ask for precise location 2026 11 11 v1.0.22
in Google sign-in and precise, profile-bound location
technical detail
  • id: feature-ask-for-precise-location-2026-11-11
  • type: —
  • advances: f_identity_location
  • target: composeApp/src/commonMain/**
✓
Feature design profile book location 2026 11 11 v1.0.23
in Google sign-in and precise, profile-bound location
technical detail
  • id: feature-design-profile-book-location-2026-11-11
  • type: —
  • advances: f_identity_location
  • target: composeApp/src/commonMain/**
✓
Feature debug variant has login 2026 11 11 v1.0.27
in Google sign-in and precise, profile-bound location
technical detail
  • id: feature-debug-variant-has-login-2026-11-11
  • type: —
  • advances: f_identity_location
  • target: composeApp/src/commonMain/**
✓
Feature debug build support creation 2026 11 11 v1.0.29-rc.1
in Google sign-in and precise, profile-bound location
technical detail
  • id: feature-debug-build-support-creation-2026-11-11
  • type: —
  • advances: f_identity_location
  • target: composeApp/src/commonMain/**
✓
Bugfix bookswap app are not 2026 11 11 v1.0.29
in Google sign-in and precise, profile-bound location
technical detail
  • id: bugfix-bookswap-app-are-not-2026-11-11
  • type: —
  • advances: f_identity_location
  • target: composeApp/src/commonMain/**
how we will know it is done
  • The Google button completes the OAuth round trip and creates a real profiles row; providers that are not enabled are not offered.
  • The app requests precise location (ACCESS_FINE_LOCATION alongside ACCESS_COARSE_LOCATION) and falls back to coarse or manual selection when denied or unavailable.
  • Profile/Passport shows the saved profile location and lets the reader update it via PATCH /api/v1/users/me while clearly telling them this is the location where their books are available.
  • Home (Discovery) in Phase 1 shows the user's profile location by default, lets the reader switch Home to their current location for exploring without overwriting their profile location, and persists that explore location across restarts.
technical detail
  • id: f_identity_location
  • status: done
  • phase: 1
  • serves: goal-experience
Neighborhood discovery, search and radar
Phase 1Done1 of 1 built — all of them
Serves: A great experience
A signed-in reader opens on a live neighborhood feed with nearby books, working search and filters, and no dead end when nothing is close.
✓
Backend zero result radar 500 v1.0.20-rc.1
in Neighborhood discovery, search and radar
technical detail
  • id: backend-zero-result-radar-500
  • type: —
  • advances: f_discovery_radar
  • target: docs/backend-contract.md
how we will know it is done
  • The bar shows the neighbourhood pill and the search field; the area is one fixed distance and there is no radius control anywhere.
  • While searching, a collapsible card ticks off the live steps — matched the book, checked nearby libraries, checked other neighbourhoods — then collapses to one line.
  • Home always carries at least one list the reader can open, named by their shelf or by themes the rows share, and never claims a mutual match or an Instant Swap.
  • Every card shows a neighbourhood and a broad band, never an address or a metre distance.
technical detail
  • id: f_discovery_radar
  • status: done
  • phase: 1
  • serves: goal-experience
Book detail and one structured offer
Phase 1Done
Serves: A great experience
A reader can judge a book and its keeper on one screen, then make one structured offer: the copy they give, the copy they take from the ad (or a note), and the term. No chat, no meetup planning.
No task queued for this feature.
how we will know it is done
  • Detail shows cover, publisher, format, pages, description, the condition tier, the three transparency facts, and the keeper trust, completed swaps and reliability.
  • The only actions are Make Offer and Post a Wish. Make Offer opens one composer that names the copy the reader gives and the copy they take from the ad, pre-filled from the card they came from, and sends offer version 1.
  • No screen names a borrow, a due date, a loan window or a return.
  • Accepting an offer opens the Offer page, never a midpoint or a meetup picker.
technical detail
  • id: f_book_detail_meetup
  • status: done
  • phase: 1
  • serves: goal-experience
Shelf and one-photo AI vision onboarding
Phase 1Done1 of 1 built — all of them
Serves: A great experience
Design · ask the designer
A reader photographs their shelf once, confirms the detected books in a batch sheet, and those books land in their tradable library.
✓
Feature bookswap pick this feature 2026 11 12 v1.0.39
in Shelf and one-photo AI vision onboarding
technical detail
  • id: feature-bookswap-pick-this-feature-2026-11-12
  • type: —
  • advances: f_shelf_vision
  • target: composeApp/src/commonMain/**
how we will know it is done
  • A shelf photo returns detected title, author and confidence per spine and renders them in a batch review sheet.
  • Confirming the batch writes real listings to the library, skips works already there by work_id, and offers the explicit second-copy escape.
  • The branch ends at the books appearing in the reader library: there is no shareable shelf card anywhere in the product.
technical detail
  • id: f_shelf_vision
  • status: done
  • phase: 1
  • serves: goal-experience
Neighbor trust passport
Phase 1Done
Serves: A great experienceUsers stay
Every reader has a passport that shows why they can be trusted, computed from real completed transactions rather than local events.
No task queued for this feature.
how we will know it is done
  • Profile shows a trust score from 0 to 100, starting at 75 for a new reader, with total completed swaps, on-time return rate and condition accuracy rate.
  • Those numbers come from completed trades and change after a handoff or return, and the same score appears on every card.
  • No endorsement, star rating, written review or invented tier appears anywhere on the profile.
technical detail
  • id: f_trust_passport
  • status: done
  • phase: 1
  • serves: goal-experience, goal-retention
Store listing and installed app present one identity
Phase 1Done2 of 2 built — all of them
Serves: A great experience
Design · ask the designer
A reader who finds BookSwap in Play installs the same name and icon the listing showed, and Play's Misleading Claims rejection is cleared.
✓
Store identity installed name matches listing v1.0.20-rc.5
in Store listing and installed app present one identity
technical detail
  • id: store-identity-installed-name-matches-listing
  • type: —
  • advances: f_store_identity
  • target: composeApp/src/androidMain/res/values/strings.xml
✓
Store icon one art v?
in Store listing and installed app present one identity
technical detail
  • id: store-icon-one-art
  • type: —
  • advances: f_store_identity
  • target: composeApp/src/androidMain/res/**
how we will know it is done
  • The installed launcher label equals the Play listing title exactly, and a test fails when either changes alone.
  • One icon art exists (docs/storefront-icon-v3.svg) and every launcher density, the adaptive foreground and the 512 listing icon derive from it - store-readiness 'Installed Icon Matches Store Listing' passes.
  • No screen or listing shows a second product name: the app is BookSwap, and 'Folio & Shelf' survives only as the design-system name, not as a user-facing wordmark.
technical detail
  • id: f_store_identity
  • status: done
  • phase: 1
  • serves: goal-experience
Scope lock: only the four pillars exist in code
Phase 1Done4 of 4 built — all of them
Serves: A great experience
Design · ask again (design changed)
No bounty, dispute, three-way cycle, pass card, endorsement or free-text review survives in the app or the backend; structured cards are the only negotiation surface.
✓
Mvp integration internal build v1.0.22-rc.1
in Scope lock
technical detail
  • id: mvp-integration-internal-build
  • type: —
  • advances: scope-lock-only-the-four-pillars-exist-in-code
  • target: composeApp/src/**
✓
Phase 1 release v1.0.22-rc.2
in Scope lock
technical detail
  • id: phase-1-release
  • type: —
  • advances: scope-lock-only-the-four-pillars-exist-in-code
  • target: composeApp/src/**
✓
Mvp release consolidated 2026 11 14 v1.0.48
in Scope lock
technical detail
  • id: mvp-release-consolidated-2026-11-14
  • type: —
  • advances: scope-lock-only-the-four-pillars-exist-in-code
  • target: composeApp/src/commonMain/**
✓
Bugfix scope lock retire the endors 2026 11 15 v1.0.74
in Scope lock
technical detail
  • id: bugfix-scope-lock-retire-the-endors-2026-11-15
  • type: —
  • advances: scope-lock-only-the-four-pillars-exist-in-code
  • target: docs/backend-contract.md
how we will know it is done
  • A repo-wide symbol check for bounty, cycle, triangle, pass card, endorsement and review comment returns zero hits in the client and the backend.
  • No schema field reachable by two users accepts user-authored free text.
  • docs/backend-contract.md lists no retired RPC and the drop manifest carries a commit SHA for every object.
technical detail
  • id: scope-lock-only-the-four-pillars-exist-in-code
  • status: done
  • phase: 1
  • serves: goal-experience
Phase 2 — frozen until Phase 1 ships (1 feature · 0 tasks)
The product runs in a desktop browser
Phase 2Done
Serves: A great experience
A reader can use BookSwap from a URL on a laptop, with the same backend, the same product laws and a desktop-first layout that Stitch designed.
No task queued for this feature.
how we will know it is done
  • docs/stitch ships DESKTOP screens and the web client binds them to a headless StateStore.
  • Every web read and write goes through the Cloud Run API — no direct database access, no mock arrays.
  • npm run build in web/ passes with zero type errors.
technical detail
  • id: web-desktop-client
  • status: done
  • phase: 2
  • serves: goal-experience
Already shipped (126)
Plan changes (5)

Rebuilt automatically every run from the team's own records in this project. Disagree with anything? Tell the team — it changes, and you are told — or run devteam goal <project> revert. Everything on this page, including the technical detail behind each item, is generated by code: no LLM writes it and nothing here is tuned for looks.