# CLAUDE.md -- QuitSure Discovery

> Global coding rules (Karpathy's 4 Principles) are in `~/.claude/CLAUDE.md`. Always follow them.

## What This Is

A free 3-5 chapter web chatbot that teaches smokers why they procrastinate quitting.
Gamified with "Excuse Monsters" (9 total, caught across 3 chapters: 4 → 6 → 9).
Completers earn 50 credits ($50 off QuitSure's $99 program).

**Source content:** Ram's `QS Procrastination program V1.docx` (72 pages, tracked changes)
**PRD:** `quitsure-analytics/outputs/QuitSure_Discovery_PRD.docx`
**Original PDF:** `quitsure-analytics/raw_files/QS Procrastination program V1.pdf`

## Current State (as of May 2026)

**Status:** MVP built, flow testing in progress. Not yet approved by Ram. Not deployed.

### What's Built
- Landing page (QuitSure branded, card stack visual, Quira coach card)
- Chat UI (Quira avatar, teal/orange brand, chips, animations)
- 60 screens across 5 days (Ram's content with HTML bold formatting)
- Animated monster grid (9 monsters pop in one by one)
- CSS animations (Quit/Tomorrow buttons, Monday Graveyard calendar, Excuse Funeral coffins, Neural Pathway, Split Screen)
- Hybrid chapters (Continue Now / Remind Me Tomorrow between Ch 1-3)
- Willpower Challenge (2 rounds with 5-second countdown)
- CAUGHT YOU overlay (dark screen, red text, 3.5s display)
- Future A/B voicemail cards (text only, no audio yet)
- Procrastination Report Card (Day 5)
- Early Bird conversion option (Day 4)
- Exit Forever 60-second countdown (Day 5)
- Session persistence (SQLite, resume from any screen)
- QA Debug panel (/debug with jump-to-any-screen)
- All notification copy (5 days, state-based triggers)

### What's NOT Built
- Email system (Postmark day-unlock + nudge emails)
- Day-gating cron (currently all chapters unlock immediately in dev)
- MySQL for prod (using SQLite for dev)
- Audio for Future A/B voicemails
- Pricing localization (hardcoded USD, needs INR for India)
- Push notification integration with QuitSure app
- Free trial / 50-credit coupon integration with QuitSure backend
- In-app banner ("Try Discovery") in QuitSure app

### Known Issues / Feedback from QA
- "Let's start QuitSure" button on method comparison (D3M2S1) currently jumps to conversion_success, skipping Excuse Funeral + 9/9. Needs fix: should skip only willpower challenge, not the funeral/completion.
- Text density too high -- many chat bubbles have 4-6 sentences, should be 1-2
- Key insight moments (LOOP reveal, Monday Graveyard punchline) need full-screen visual treatment, not just chat bubbles
- No audio for voicemails (major emotional impact loss)
- Pricing is US-only ($99, $49) -- needs India localization
- Chat format may not be ideal for all content types

### Rating: 55/100
Core content is strong (Ram's psychology). Technical foundation works. But delivery (chat bubble format, text density, lack of audio, limited interaction depth) significantly weakens the emotional impact. Key improvements needed: full-screen moments for insights, 40% text reduction, audio voicemails, pricing localization, more micro-interactions.

## Architecture

- **Backend:** FastAPI (app.py)
- **Frontend:** Jinja2 templates + vanilla JS (single chat.html file ~1700 lines)
- **State:** SQLite for dev, MySQL for prod
- **Emails:** Postmark (not built yet)
- **Content:** All in `static/content.json` (60 screens, 5 days, notifications)

## Key Endpoints

- `GET /` -- Landing page (register or resume)
- `GET /u/{session_id}` -- Chat experience (resumes from last position)
- `GET /u/{session_id}?screen=D3M2S1` -- Jump to specific screen (QA)
- `GET /debug` -- QA debug panel (lists all screens, clickable jump links)
- `GET /debug/reset` -- Reset test user
- `POST /api/register` -- Create session (name + email)
- `POST /api/progress` -- Save screen completion + answer
- `GET /api/state/{session_id}` -- Load full session state
- `POST /api/convert` -- User clicked "Start QuitSure"
- `POST /api/unlock-bonus` -- Unlock Days 4-5 after CAUGHT YOU

## Monster Progression

- Monsters are NOT personally selected (we tried tinder swipe, removed it -- created math conflicts)
- Ram's design: animated grid shows all 9, poll asks "how many have YOU used?"
- Progression is content-based: complete Chapter 1 content = 4 caught, Chapter 2 = 6, Chapter 3 = 9
- Progress bar in header tracks defeated count (0 → 4 → 6 → 9)

## Content Structure

All program content lives in `static/content.json`:
```json
{
  "meta": { "monsters": [...], "pricing": {...} },
  "notifications": { "day_1": {...}, ... },
  "days": {
    "1": {
      "title": "...",
      "modules": [
        {
          "id": "D1M1",
          "title": "...",
          "screens": [
            {
              "id": "D1M1S1",
              "type": "text|poll|video|monster_catch|...",
              "messages": [...],
              "button": "..."
            }
          ]
        }
      ]
    }
  }
}
```

### Screen Types
- `text` -- messages + button (or buttons array for branching)
- `poll` -- messages + chip options (single select)
- `multi_poll` -- messages + checkboxes + continue button
- `video` -- messages + animation (animation_type triggers CSS/JS animation)
- `monster_catch` -- level complete banner (monsters_earned triggers progress bar update)
- `day_complete` -- end of day message + button
- `chapter_gate` -- "Continue Now" / "Remind Me Tomorrow" fork
- `willpower_challenge` -- countdown timer + button
- `future_messages` -- two voicemail cards (Future A / Future B)
- `conversion` -- offer card or split-screen visual + branch buttons
- `conversion_success` -- celebration + redirect
- `caught_you` -- dark screen overlay + follow-up messages + unlock bonus
- `exit_forever` -- 60-second countdown + escape button
- `report` -- procrastination report card

## Running Locally

```bash
cd /Users/neelraut/quitsure-discovery
pip3 install -r requirements.txt
python3 -m uvicorn app:app --host 0.0.0.0 --port 8081 --reload
# Open http://localhost:8081
# Debug: http://localhost:8081/debug
```

## Deployment Plan (Not Yet Executed)

- Will be hosted at `program.quitsure.app/discovery/` (same pattern as chatbot-onboarding)
- Dev team needs: hosting, in-app banner, deep link with userId, free trial activation
- Debug panel should be disabled in production (ENV=production check)

## Key Decisions Made

| Decision | Choice | Why |
|----------|--------|-----|
| Monster mechanic | Animated grid + poll (Ram's original) | Tinder swipe created math conflicts with 4→6→9 progression |
| Session structure | Hybrid chapters (can do all in one sitting or across days) | Pure multi-day has high drop-off; pure single-session is too long |
| Pricing | 50 credits / $99 (Ram's original) | Not free trial -- matches Ram's doc |
| Program routing | P9 (6-week) for Discovery graduates | Procrastinators need relaxed pace |
| Chat persona | Quira (same as chatbot onboarding) | Brand consistency |
| Animations | CSS/JS in-app (no video production needed) | Faster to build, personalizable, no hosting needed |