Update

.claude/agents.md

@@ -0,0 +1,73 @@
+# Agents Documentation
+
+This file contains important project-specific context for Claude Code agents working on this repository.
+
+## Redemption Code System
+
+**IMPORTANT: Codes can only be redeemed on the website, NOT in the mobile app.**
+
+Apple's App Store guidelines require that any premium features purchased within an iOS app must go through In-App Purchase. Adding a redemption code feature to the mobile app would violate these guidelines and risk app rejection.
+
+### Overview
+Promotional codes that grant users premium access without going through RevenueCat/App Store subscription flow.
+
+### Database Schema
+
+**`redemption_codes` table:**
+- `id` (UUID) - Primary key
+- `code` (TEXT, UNIQUE) - The redemption code
+- `description` (TEXT) - Optional description
+- `max_uses` (INTEGER) - Maximum number of redemptions allowed
+- `current_uses` (INTEGER) - Current number of redemptions
+- `expires_at` (TIMESTAMPTZ) - Optional expiration date
+- `is_active` (BOOLEAN) - Whether the code can be redeemed
+- `created_by` (UUID) - Admin who created the code
+- `created_at` (TIMESTAMPTZ)
+- `updated_at` (TIMESTAMPTZ)
+
+**`code_redemptions` table:**
+- `id` (UUID) - Primary key
+- `code_id` (UUID) - Reference to redemption_codes
+- `user_id` (UUID) - User who redeemed the code
+- `redeemed_at` (TIMESTAMPTZ)
+- UNIQUE constraint on (code_id, user_id) - Each user can only redeem a code once
+
+### Components
+
+1. **Admin UI** (`apps/admin/src/pages/RedemptionCodesPage.tsx`)
+   - Super admins can generate codes
+   - View all codes with usage stats
+   - Toggle active/inactive
+   - View who redeemed each code
+   - Delete codes
+
+2. **Edge Function** (`apps/supabase/functions/redeem-code/index.ts`)
+   - **Unauthenticated** - accepts email + code in request body
+   - Calls the `redeem_code_by_email()` database function
+   - Returns success/error response
+
+3. **Database Function** (`redeem_code_by_email(p_email TEXT, p_code TEXT)`)
+   - Atomic operation with row locking
+   - Looks up user by email (must have signed up in app first)
+   - Validates: code exists, is active, not expired, has uses remaining
+   - Checks user hasn't already redeemed
+   - Records redemption in `code_redemptions`
+   - Increments `current_uses`
+   - Sets `profiles.is_premium = true`
+
+4. **Web UI** (`apps/web/app/redeem/page.tsx`)
+   - Public page at `/redeem`
+   - User enters email + redemption code
+   - Calls edge function via fetch
+   - Shows success or error message
+
+### Environment Variables
+
+The web app requires:
+- `NEXT_PUBLIC_SUPABASE_URL` - Supabase project URL for API calls
+
+### DO NOT
+
+- **DO NOT** add redemption code UI to the mobile app
+- **DO NOT** create any in-app mechanism to bypass App Store purchases
+- **DO NOT** expose the redeem endpoint in mobile app Supabase calls