@@ -4,9 +4,26 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-DebateLab is an AI-powered debate preparation suite. It uses **Supabase Edge Functions** as the backend for all AI calls (keys are never exposed to the browser). Authentication is via Supabase Auth with Google OAuth.
+DebateLab is an AI-powered debate preparation suite for competitive debaters. It combines multiple AI providers (OpenAI, Google Gemini, Anthropic) with real-time web research via Jina AI. Uses **Supabase Edge Functions** as the backend so API keys are never exposed to the browser. Authentication is via Supabase Auth with Google OAuth.
 
 **Live URL:** https://debate.pi-stack.org
+**Hosting:** Raspberry Pi + Docker + Cloudflare Tunnel
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Frontend | React 18, TypeScript, Vite 5 |
+| Styling | TailwindCSS + shadcn/ui (51+ components) |
+| State | Zustand with localStorage persistence |
+| Forms | React Hook Form + Zod validation |
+| Routing | React Router v6 |
+| Backend | Supabase Edge Functions (Deno runtime) |
+| Auth | Supabase Auth (Google OAuth) |
+| Database | Supabase PostgreSQL (15 tables, RLS enabled) |
+| AI Providers | OpenAI, Google Gemini, Anthropic Claude |
+| Web Search | Jina AI (Search + Reader) |
+| CI/CD | GitHub Actions + Docker Hub + Watchtower |
 
 ## Common Commands
 
@@ -15,79 +32,203 @@ DebateLab is an AI-powered debate preparation suite. It uses **Supabase Edge Fun
 npm install              # Install dependencies
 npm run dev             # Start dev server on port 8080
 npm run build           # Production build to dist/
+npm run build:dev       # Dev build with source maps
+npm run preview         # Preview production build
 
 # Quality
 npm run lint            # Run ESLint
-npm test                # Run tests with Vitest
+npm test                # Run tests with Vitest (39 tests)
+npm run test:watch      # Run tests in watch mode
 
 # Docker
 docker build -t debate-trainer .
 docker run -d -p 3001:80 --name debate-app debate-trainer
+
+# Supabase
+npx supabase functions deploy ai       # Deploy AI function
+npx supabase functions deploy admin    # Deploy admin function
+npx supabase functions deploy share    # Deploy share function
 ```
 
 ## Architecture
 
-### Backend: Supabase Edge Functions
+### Backend: 3 Supabase Edge Functions
+
+1. **`supabase/functions/ai/index.ts`** (~888 lines) - Main AI proxy
+   - JWT authentication required
+   - API keys stored as Supabase secrets (OPENAI_API_KEY, GOOGLE_API_KEY, ANTHROPIC_API_KEY, JINA_API_KEY)
+   - Input sanitization with prompt injection pattern detection
+   - Deep research with Jina AI (multi-round search, content reading, URL verification)
+   - Rate limiting per authenticated user
+   - Multi-provider routing (OpenAI, Google, Anthropic)
 
-All AI calls go through `supabase/functions/ai/index.ts`:
-- JWT authentication required
-- API keys stored as Supabase secrets
-- Input sanitization for prompt injection
-- Deep research with Jina AI (multi-search, URL verification)
+2. **`supabase/functions/admin/index.ts`** (~329 lines) - Admin API
+   - Admin role verification
+   - User management, usage stats
+
+3. **`supabase/functions/share/index.ts`** (~131 lines) - Share link creation
+   - Unique share code generation with collision detection
 
 ### Frontend: React + Zustand
 
+**AI Client** (`src/lib/ai/client.ts`):
+- Calls Edge Function via `fetch` with JWT Bearer token
+- Custom error hierarchy: `AIError`, `AIAuthError`, `AIRateLimitError`, `AIProviderError`, `AIResponseError`, `TimeoutError`
+- Type guards for error handling
+
 **Session Store** (`src/lib/stores/session-store.ts`):
-- Active results for each feature
-- History arrays (savedCases, savedAttacks, etc.)
+- Active results for each feature (generateResult, attackResult, etc.)
+- History arrays (savedCases, savedAttacks, savedBrainstorms, savedFactoids, savedChats)
 - Source Library for knowledge base grounding
+- Persistence key: `debate-trainer-storage`
 
 **Settings Store** (`src/lib/stores/settings-store.ts`):
-- Per-feature AI provider configuration
-- Theme, language, admin mode
+- Per-feature AI provider configuration (provider, model, temperature)
+- Theme (light/dark/system), language (en/es)
+- Admin mode, custom system prompt
+- Persistence key: `debate-settings`
 
 ### State Persistence
 - All data stored in browser localStorage via Zustand persist
 - Auth state in Supabase session
 
+## Project Structure
+
+```
+src/
+├── components/
+│   ├── auth/          # Auth-related components
+│   ├── features/      # Feature-specific components (9 folders)
+│   ├── landing/       # Landing page components (11 files)
+│   ├── layout/        # AppLayout, Sidebar, MobileNav
+│   └── ui/            # shadcn/ui components (51 files)
+├── hooks/             # use-mobile, use-speech-to-text, use-toast
+├── lib/
+│   ├── ai/
+│   │   ├── client.ts  # AI integration (Edge Function calls)
+│   │   └── schemas/   # Zod validation (ask, attack, brainstorm, factoids, generate)
+│   ├── stores/        # Zustand stores
+│   ├── supabase/      # Client + AuthProvider
+│   └── validation/    # URL validation
+├── pages/             # 14 route pages
+└── test/              # Tests (39 passing across 8 files)
+
+supabase/functions/    # Edge Functions (ai, admin, share)
+```
+
 ## Feature Organization
 
-Five main features under `src/components/features/`:
-- **generate/**: Case generation
-- **attack/**: Critical analysis  
-- **brainstorm/**: Idea generation
-- **factoids/**: Evidence research with web search
-- **ask/**: Coach chat
+Main features under `src/components/features/`:
+- **generate/**: Case generation (4-6-6-3 tournament format, contentions with CWI structure)
+- **attack/**: Critical analysis with fallacy detection and severity ratings
+- **brainstorm/**: Multi-mode ideation (mindmap, buckets, top-5)
+- **factoids/**: Deep research with multi-round Jina search, URL verification, content reading
+- **ask/**: Coach chat with conversation memory, source grounding, voice input
+
+Each follows: `FeatureForm.tsx` -> `FeatureResults.tsx` pattern.
+
+Additional features:
+- **Source Library** (`/library`): Persistent knowledge base (URL reading, manual text, response saving)
+- **Debate Timer** (`/timer`): Presets for constructive (4m), rebuttal (6m), cross-ex (6m), summary (3m)
+- **Word/PDF Export**: Download cases as .docx or formatted PDF
+- **Google Docs Export**: Direct export via Google Docs API
+- **Argument Flowcharts**: Visual debate flow with React Flow
+
+## Routes
+
+| Path | Page | Description |
+|------|------|-------------|
+| `/` | GeneratePage | Case generation |
+| `/attack` | AttackPage | Case critique |
+| `/brainstorm` | BrainstormPage | Idea generation |
+| `/factoids` | FactoidsPage | Research |
+| `/ask` | AskPage | Chat coaching |
+| `/library` | LibraryPage | Source library |
+| `/history` | HistoryPage | Saved items |
+| `/timer` | TimerPage | Debate stopwatch |
+| `/settings` | SettingsPage | Configuration |
+| `/login` | LoginPage | Authentication |
+
+## Database Schema (15 tables)
 
-Each follows: `FeatureForm.tsx` → `FeatureResults.tsx` pattern.
+Tables with RLS enabled: `user_settings`, `cases`, `attacks`, `brainstorms`, `factoids`, `chats`, `messages`, `sources`, `source_files`, `ai_requests`, `api_keys`, `shared_items`, `user_roles`, `rate_limits`, `global_prompts`
+
+All RLS policies use optimized `(SELECT auth.uid())` pattern.
 
 ## Security
 
 | Layer | Implementation |
 |-------|----------------|
-| API Keys | Supabase Edge Function secrets |
-| Auth | Supabase Auth + JWT |
-| Input Validation | Prompt injection sanitization |
-| Nginx | CSP headers, block sensitive files |
-
-## Critical Files
-
-- **Edge Function**: `supabase/functions/ai/index.ts` - All AI logic
-- **Supabase Client**: `src/lib/supabase/client.ts`
-- **State**: `src/lib/stores/session-store.ts`, `settings-store.ts`
-- **Schemas**: `src/lib/ai/schemas/` - Zod validation
-- **Deployment**: `Dockerfile`, `nginx.conf`
+| API Keys | Supabase Edge Function secrets (never in browser) |
+| Auth | Supabase Auth + JWT verification |
+| Input Validation | Prompt injection regex patterns, MAX_INPUT_LENGTH=50000 |
+| CORS | Strict allowlist (debate.pi-stack.org + localhost) |
+| Nginx | CSP headers, HSTS, X-Frame-Options, block sensitive files |
+| URL Validation | Block javascript:, data:, vbscript:, file: protocols |
+| File Validation | 10MB limit, allowed extensions only |
+| RLS | All 15 tables protected with row-level security |
+
+## Environment Variables
+
+| Variable | Location | Description |
+|----------|----------|-------------|
+| `VITE_SUPABASE_URL` | Frontend (.env) | Supabase project URL |
+| `VITE_SUPABASE_ANON_KEY` | Frontend (.env) | Supabase anonymous key |
+| `OPENAI_API_KEY` | Supabase secrets | OpenAI API key |
+| `GOOGLE_API_KEY` | Supabase secrets | Google AI API key |
+| `ANTHROPIC_API_KEY` | Supabase secrets | Anthropic API key |
+| `JINA_API_KEY` | Supabase secrets | Jina AI API key |
+| `AI_DEFAULT_PROVIDER` | Supabase secrets | Default provider (google) |
+| `AI_DEFAULT_MODEL` | Supabase secrets | Default model (gemini-2.0-flash) |
 
 ## Deployment
 
 Docker two-stage build:
-1. Node builder: `npm ci → npm run build`
-2. nginx runtime: serves static files
+1. Node builder (`node:20-alpine`): `npm ci` -> `npm run build`
+2. Nginx runtime (`nginx:alpine`): serves static files from `dist/`
+
+Production: Raspberry Pi + Watchtower for auto-updates from Docker Hub + Cloudflare Tunnel.
+
+CI/CD: GitHub Actions on push to main -> build + push multi-arch Docker image.
+
+## Adding a New Feature
 
-Production uses Watchtower for auto-updates from Docker Hub.
+1. Create Zod schema: `src/lib/ai/schemas/newfeature.ts`
+2. Update Edge Function: `supabase/functions/ai/index.ts` (add feature case)
+3. Create form component: `src/components/features/newfeature/NewFeatureForm.tsx`
+4. Create results component: `src/components/features/newfeature/NewFeatureResults.tsx`
+5. Create page: `src/pages/NewFeaturePage.tsx`
+6. Add route: `src/App.tsx`
+7. Update stores: `src/lib/stores/session-store.ts`
+
+## Coding Conventions
+
+- 2-space indentation
+- Named exports preferred
+- `@/` alias for `src/` imports
+- PascalCase.tsx for components, kebab-case.ts for utilities
+- Functional components with hooks
+- React Hook Form for forms, Zod for runtime validation
+- shadcn/ui for UI components, TailwindCSS for styling
 
 ## Admin Mode
 
 Code `debate2026` in Settings unlocks:
 - Global custom system prompt
-- Database reset
+- Database reset functionality
+- Advanced configuration options
+
+## Known Technical Debt
+
+- TypeScript strict mode disabled in `tsconfig.app.json` (TD-01, high priority)
+- Bundle size warnings: GeneratePage (360KB), vendor-charts/Recharts (400KB)
+- Test coverage measurement blocked by peer dep conflict (@vitest/coverage-v8)
+- Deep research may approach Edge Function timeout limits
+
+## Upcoming Features (Roadmap)
+
+**Next up:**
+- Practice Mode / Sparring Partner (AI plays opponent, turn-based with timer)
+- Debate Wiki integration (WikiDebate, NDCA caselist)
+- Stripe payments (free trial -> $5/mo Pro tier, promo code system)
+- Native mobile apps (Capacitor or React Native)
@@ -0,0 +1,95 @@
+# Stripe Implementation Progress
+
+**Last Updated:** 2026-02-10
+**Status:** Code complete, not deployed
+
+## What's Done (All code written, lint/test passing)
+
+### Database
+- `supabase/migrations/20260208000000_stripe_schema.sql` — Creates `subscriptions`, `promo_codes`, `user_promos` tables, adds `subscription_tier`/`daily_limit_override`/`trial_ends_at`/`grace_period_ends_at` columns to `user_settings`, sets up RLS policies, and migrates existing users to `legacy_free` with 30-day grace period.
+
+### Backend (Supabase Edge Functions)
+| Function | Path | Status |
+|---|---|---|
+| `stripe-webhook` | `supabase/functions/stripe-webhook/index.ts` | New — handles checkout.session.completed, invoice.payment_succeeded/failed, subscription deleted/updated |
+| `create-checkout` | `supabase/functions/create-checkout/index.ts` | New — creates Stripe Checkout Sessions with promo code support |
+| `create-portal` | `supabase/functions/create-portal/index.ts` | New — creates Stripe Customer Portal sessions |
+| `redeem-promo` | `supabase/functions/redeem-promo/index.ts` | New — validates and applies promo codes (extended_trial, extra_limit, free_month, discount) |
+| `ai` | `supabase/functions/ai/index.ts` | Updated — added `getSubscriptionInfo()`, `PRO_MODELS` set, subscription-aware `checkRateLimit()` that returns 402/403 |
+| `admin` | `supabase/functions/admin/index.ts` | Updated — added `promo-codes`, `create-promo`, `toggle-promo`, `subscribers` endpoints |
+
+### Frontend
+| File | Status | Description |
+|---|---|---|
+| `src/hooks/use-subscription.ts` | New | Hook providing tier, isPro, dailyLimit, dailyUsed, trialEndsAt, refresh() |
+| `src/hooks/use-subscription-error.ts` | New | Hook that detects 402/403 errors and opens correct modal |
+| `src/lib/stripe.ts` | New | `redirectToCheckout()`, `redirectToPortal()`, `redeemPromoCode()` helpers |
+| `src/lib/ai/client.ts` | Updated | Added `AISubscriptionError`, `AIModelRestrictionError`, type guards, error parsing |
+| `src/lib/ai/providers/types.ts` | Updated | Added `isProOnly` flag to `AIModel`, marked pro models |
+| `src/components/features/subscription/PricingModal.tsx` | New | Free vs Pro comparison, Stripe checkout redirect, promo code input |
+| `src/components/features/subscription/LimitReachedModal.tsx` | New | Daily limit / trial expired modal with upgrade CTA |
+| `src/components/features/subscription/ModelRestrictedModal.tsx` | New | Pro model restriction modal |
+| `src/pages/SettingsPage.tsx` | Updated | Added subscription status card, usage bar, manage/upgrade buttons, model gating |
+| `src/pages/GeneratePage.tsx` | Updated | Integrated subscription error modals |
+| `src/pages/AttackPage.tsx` | Updated | Integrated subscription error modals |
+| `src/pages/BrainstormPage.tsx` | Updated | Integrated subscription error modals |
+| `src/pages/FactoidsPage.tsx` | Updated | Integrated subscription error modals |
+| `src/pages/AskPage.tsx` | Updated | Integrated subscription error modals |
+| `src/pages/AdminPage.tsx` | Updated | Added Promo Codes tab (create/toggle) + Subscribers tab |
+| `package.json` | Updated | Added `@stripe/stripe-js` dependency |
+
+## What's NOT Done (Requires Manual Steps / Deploy)
+
+### 1. Stripe Dashboard Setup (Manual — see stripe_implementation.md Section 2)
+- Create DebateLab Pro product ($5/mo) in Stripe Dashboard
+- Copy the Price ID (starts with `price_...`)
+- Enable Customer Portal
+- Add webhook endpoint pointing to `https://<project-ref>.supabase.co/functions/v1/stripe-webhook`
+- Copy webhook signing secret
+
+### 2. Environment Variables
+- Add to Supabase secrets:
+  - `STRIPE_SECRET_KEY` — from Stripe Dashboard
+  - `STRIPE_WEBHOOK_SECRET` — from webhook endpoint
+- Add to frontend `.env`:
+  - `VITE_STRIPE_PRICE_ID` — the Price ID from step 1
+
+### 3. Deploy
+- Run the migration SQL against Supabase DB
+- Deploy all 6 edge functions: `ai`, `admin`, `stripe-webhook`, `create-checkout`, `create-portal`, `redeem-promo`
+- Deploy frontend (build already succeeds)
+
+### 4. Landing Page Pricing Section
+- `LandingPage.tsx` doesn't have a pricing section yet (low priority, users can see pricing in the PricingModal from Settings)
+
+### 5. Stripe Tax Configuration
+- Enable Stripe Tax in Dashboard settings if desired
+- `create-checkout` already has `automatic_tax: { enabled: true }` set
+
+## Architecture Notes
+
+### Subscription Tiers
+| Tier | Daily Limit | Pro Models | When |
+|---|---|---|---|
+| `trial` | 5 | No | New users, first 3 days |
+| `pro` | 50 | Yes | Active Stripe subscription |
+| `legacy_free` | 50 | Yes | Existing users during 30-day grace |
+| `expired` | 0 | No | Trial/grace expired, no subscription |
+
+### Error Codes from AI Function
+| HTTP | Code | Meaning | Frontend Action |
+|---|---|---|---|
+| 402 | `trial_expired` | Trial ended, no sub | Shows LimitReachedModal (trial_expired) |
+| 402 | `limit_reached` | Daily requests used up | Shows LimitReachedModal (limit_reached) |
+| 403 | `upgrade_required` | Pro model selected by free user | Shows ModelRestrictedModal |
+
+### Pro Models (Gated on Backend)
+`gpt-4o`, `claude-3-5-sonnet-latest`, `claude-3-opus-20240229`, `gemini-1.5-pro`, `gemini-2.0-pro-exp`, `gemini-3-pro-preview`
+
+### Promo Code Types
+| Type | Effect |
+|---|---|
+| `extended_trial` | Sets `trial_ends_at` to now + X days |
+| `extra_limit` | Sets `daily_limit_override` to X |
+| `free_month` | Sets tier to `pro` + grace period 30 days |
+| `discount` | Applied at Stripe checkout (not redeemed server-side) |
@@ -0,0 +1,18 @@
+
+ ▐▛███▜▌   Claude Code v2.1.38
+▝▜█████▛▘  Opus 4.6 · Claude Pro
+  ▘▘ ▝▝    ~/Code/innovation_fair_2026/MVP-Stripe-Prototype
+
+✻ Conversation compacted (ctrl+o for history)
+
+  ⎿  Read STRIPE_PROGRESS.md (96 lines)
+  ⎿  Referenced file stripe_implementation.md
+  ⎿  Read src/pages/GeneratePage.tsx (240 lines)
+  ⎿  Read src/pages/AskPage.tsx (129 lines)
+  ⎿  Read src/pages/FactoidsPage.tsx (138 lines)
+  ⎿  You're out of extra usage · resets 4pm (Europe/Madrid)
+     /upgrade or /extra-usage to finish what you’re working on.
+
+✻ Churned for 18m 40s
+
+❯ Unknown skill: rate-limit-options