Session Handoff — Bookify billing spine BUILT + deployed (slots, image metering, paywall) + research/feed spec

Where it started

Continuing BookifAI (AI KDP book SaaS on Sondra's own stack). This session (1) designed and LOCKED the entitlement model, book-size cap, and the research/demand-feed features into the PRD, then (2) built the billing spine on top of the already-deployed money-spine backend. Everything is TEST mode; app has 0 real users. Prior context: c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\handoffs\billing-money-spine-2026-07-05.md.

Decisions locked + what shipped

• Entitlement = slot-based (Option A, locked). 1 free book/account; then starting each book spends a slot ($29 single = 1 slot, tied to that book; $79 Author Pack = 5 book_credits). Slot spent at book creation so text-only books can't run up (rejected Option B / charge-at-first-action for the text leak). Inside a slotted book the user is uncapped except the 15/40 image cap. Free first book = try-before-buy. No separate research-credit currency (YAGNI). Spec in PRD.md §7.8.
• Book-size runaway guardrail (locked): UI already caps 3-25 chapters; add ~50 hard ceiling as a script backstop, shown on-screen with an upsell line. In PRD.md §7.8.
• Research features (locked, spec only — NOT built): Feature A "Research My Idea" (user types niche → live research; one run included per book). Feature B demand feed (free generic across evergreen categories + tailored $79 perk via Settings). Framed "what readers are asking for," not "selling."
• Feed cost-safety (locked): weekly, lazy + cached, never on a timer — dormant $79 buyer = $0. Engine = Firecrawl search (Amazon direct scrape is BLOCKED — proven live) + cheap Sonnet 5 structuring. Cost measured: Firecrawl flat plan (1,000 credits/cycle), scrape=1 credit, search=~2; weekly generic feed ~30-40 credits/mo = effectively $0. In PRD.md §7.8.
• Model confirmed: anthropic/claude-sonnet-5 (OpenRouter) for writing + structuring; not Opus.
• Sell-page scroll bar = replicate P2P Landing.jsx two-row marquee (lb-marquee), each chip links to signup ?idea=... → prefills Feature A. Spec in §7.8.
• DB RPCs (applied to live DB umnlokuehteqwrheoyai): claim_book_slot(uuid) (free→credit→unpaid, ownership-checked, EXECUTE authenticated), meter_image(user,project,kind) + refund_image(...) (service_role only). Local file: ...\app\supabase\migrations\20260706000000_billing_slot_metering.sql.
• generate-illustration (rewritten + deployed): requires JWT, metering via meter_image before generation, auto-refund on failure. Closes the prior unauth/unmetered security hole. ...\app\supabase\functions\generate-illustration\index.ts.
• generate-chapter (edited + deployed): new-book writing (bookTitle/bookTopic flow) now requires a claimed slot (entitlement != 'unpaid', checked by projectId via service role); returns 402 no_slot otherwise. Legacy editor path (taskType, no bookTitle) stays free/unmetered. ...\app\supabase\functions\generate-chapter\index.ts.
• Client (typecheck clean): slot claimed after project insert (CreateBook.tsx); projectId+kind:"page" passed to illustration + 402 lock messaging (BookPreview.tsx readLockReason); projectId added to chapter body (ChapterGenerator.tsx); download page locked behind paid with "Unlock this book — $29" button (ExportOptions.tsx); Account "Plan & Credits" card with book/image credit counts + Buy Author Pack $79 / Buy Image Credits $9 buttons + purchase-return handling (Account.tsx). Regenerated src/integrations/supabase/types.ts.

Key files for next session

• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\PRD.md — read §7.7 then §7.8 (locked billing + research/feed spec).
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\supabase\migrations\20260706000000_billing_slot_metering.sql
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\supabase\functions\generate-illustration\index.ts
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\supabase\functions\generate-chapter\index.ts
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\src\components\create-book\ExportOptions.tsx (paywall + $29 unlock)
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\app\src\pages\Account.tsx (buy buttons)
• c:\Users\srver\AIOS-Workspace\aios-starter-kit\PROJECTS\Bookify AI Studio\stripe-test-products.json (price IDs)
• Plan file: none (PRD is the spec).
• Memory files touched: none.

Running state

• Background processes: none.
• Dev servers / ports: none started this session. To run: cd "PROJECTS/Bookify AI Studio/app" && npm run dev -> localhost:8080.
• Open worktrees / branches: none (main, local only, nothing committed this session).

Verification — how to confirm things still work

• Metering logic (all 8 transitions verified this session in a rolled-back block; nothing persisted): unpaid->blocked, free->page-locked, free cover cap at 3, paid->15 included -> need_credits -> credit -> hard_cap at 40.
• Auth boundaries verified: generate-illustration no-auth -> 401, anon -> 401; generate-chapter unslotted book -> 402 no_slot. Re-run: curl -s -o /dev/null -w "%{http_code}" -X POST https://umnlokuehteqwrheoyai.supabase.co/functions/v1/generate-illustration -H "Content-Type: application/json" -d '{"scenePrompt":"x","projectId":"0"}' -> 401.
• Typecheck: cd "PROJECTS/Bookify AI Studio/app" && npx tsc --noEmit -> exit 0.
• Redeploy fn: TOKEN=$(python -c "import re,pathlib;print(re.findall(r'sbp_[A-Za-z0-9]+',pathlib.Path.home().joinpath('.claude.json').read_text(encoding='utf-8'))[0])"); CLI ~/AppData/Local/Programs/cli-bin/supabase.exe; SUPABASE_ACCESS_TOKEN=$TOKEN supabase.exe functions deploy <name> --project-ref umnlokuehteqwrheoyai.
• Regenerate types: same CLI, gen types typescript --project-id umnlokuehteqwrheoyai > src/integrations/supabase/types.ts.

Deferred + open questions — THE THINGS SONDRA NEEDS TO LOOK AT

• [HER STEP] Live test-card round-trip (the money proof — not doable without her browser): (1) npm run dev -> localhost:8080; (2) sign up/log in, make a book, reach the download page -> Unlock $29; (3) Stripe TEST card 4242 4242 4242 4242, any future date, any CVC; (4) confirm it returns to Account and downloads unlock. Author Pack ($79) / Image Credits ($9) buttons test the same way from Account.
• Deferred — cover-generation metering NOT wired: per-page images are fully metered (BookPreview -> generate-illustration kind:"page"). The free-tier 3-cover cap exists in meter_image but the cover screen (CoverGenerator.tsx) was NOT confirmed to route through generate-illustration with kind:"cover" — wire + verify that next.
• Deferred — Stripe TEST -> LIVE + /app-safety-check before any real launch. Live key STRIPE_API_KEY_MAIN in master .env; create live products + live webhook + reset secrets.
• Deferred — Research/feed (Feature A/B) spec'd in §7.8, NOT built. Build order: Feature A first, then generic feed, then tailored+Settings; all after billing.
• Open: book #2+ friction — a single-buyer (no pack) pays $29 before writing book #2 (accepted; free first book softens it). Confirm this feels right when she tests.
• Note (low harm): generate-chapter checks entitlement by projectId via service role; it does not re-verify per-user ownership on the text call (ownership is enforced at claim_book_slot, which is auth'd). A user passing a stranger's paid projectId could generate text billed to us — text is cheap, no data written. Tighten later if desired.
• Nothing committed to git this session (app is its own local repo).

Pick up here

Sondra runs the live 4242 test-card round-trip; if it grants access cleanly, next agent wires cover-generation metering (CoverGenerator.tsx -> generate-illustration kind:"cover"), then starts Feature A (Research My Idea) per PRD §7.8.