# Tarot App — Vision & Phased Roadmap

**Branch:** `claude/tarot-app-paywall-dfWZ6`
**Status:** scoping — VI #001 gathers the visual foundation first.

## Vision (Ivy's words, distilled)

A tarot app that holds **all of Ivy's decks**. First 3 decks ship free; the
rest live behind a **per-deck unlock paywall**. Every deck supports **upright
and reversed** readings.

**Core experience:**

1. Browse decks, scroll cards with a satisfying **flip**.
2. Tap **Shuffle** — animated hands come out and shuffle the deck. The
   shuffle style is randomized across real-world styles: poker, overhand,
   riffle, Hindu, and several mystic / tarot shuffle styles. User **taps to
   stop**; hands cut the deck.
3. Pull **1 card** or a **5-card spread**, lay them out, read them.
4. **Cross-deck readings:** a drawer on the left edge lets Ivy pull a
   secondary deck (tarot or oracle, any unlocked deck), shuffle it into the
   same reading, and draw additional cards.
5. **AI reading:** an AI trained by Ivy on Ivy's reading voice synthesizes
   the pulled cards into a thorough reading.
6. **Ask Ivy (live):** pay-per-minute voice call with Ivy, or request a
   recorded **video reading back** (à la Purple Ocean / Purple Garden).
7. **Reviews:** Ivy's existing reviews from Purple Garden / Purple Ocean
   surface here, consolidated in one profile.

## Phased roadmap

### Phase 0 — Foundations (in flight)

- [x] Repo scaffold + locked visual foundation
- [x] VI #001 baseline (collects palette, font, a11y, motion preferences)
- [ ] VI #002 — tarot app layout (collects shuffle animation preferences, card flip direction, spread layouts)
- [ ] Tech stack decision locked in VI #003 (React Native + Expo strongly recommended)

### Phase 1 — Deck experience (MVP)

- Deck browser (3 free decks)
- Card list per deck with flip animation
- Upright / reversed toggle
- Single-card draw + 5-card spread
- Shuffle (single style, no animated hands yet)
- Dyslexia controls surfaced in settings

### Phase 2 — Paywall & library

- RevenueCat (or StoreKit / Play Billing direct) per-deck IAP
- Locked deck cards in browser with "Unlock" CTA
- Restore purchases
- Full deck library (Ivy's owned decks added progressively)

### Phase 3 — Animated shuffle & multi-deck

- Animated hands; 5+ shuffle styles, randomized
- Tap-to-stop, animated cut
- Left-edge drawer for secondary deck
- Cross-deck reading: shuffle and draw from multiple decks

### Phase 4 — AI reading + Ask Ivy

- AI reading endpoint (Claude Sonnet / Opus) fine-tuned with Ivy's reading
  samples (needs 50–200 samples from Ivy)
- Pay-per-minute voice calls (Agora or Twilio)
- Recorded video reading request + delivery

### Phase 5 — Reviews & polish

- Purple Garden / Purple Ocean review sync (API access TBD)
- Unified reviews surface in Ivy's profile
- Launch polish, onboarding, app store assets

## Open questions (for future VIs, not this one)

- First 3 "free" decks — which specific decks, and do we own art rights?
- AI reading training data — how many of Ivy's readings can she contribute?
- Purple Garden / Purple Ocean — is there an existing API, or do we start
  with screenshots?
- Pricing — per-deck price point? Trial for AI readings?

These all come AFTER VI #001 establishes the visual foundation.