base structure of the project formed

.claude/skills/debugging.md

@@ -0,0 +1,157 @@
+# Skill — Debugging Patterns by Error Type
+
+## Purpose
+Read this file when stuck on a specific error type.
+Contains reusable debug snippets organised by error category.
+Always check logs/errors.log first before opening this file.
+
+---
+
+## Null & Undefined Errors
+
+### Pattern
+```typescript
+// Guard at function entry — always first line
+function myFunction(input: string | null) {
+  if (!input) {
+    handleError(new Error('input is null'), 'file.ts', 'myFunction')
+    return null
+  }
+  // safe to use input below
+}
+```
+
+### Checklist
+- [ ] Is the value null before it enters the function?
+- [ ] Is the value undefined because an async call hasn't resolved?
+- [ ] Is optional chaining `?.` missing somewhere?
+- [ ] Is the DB returning null instead of empty array?
+
+---
+
+## Async & Promise Errors
+
+### Pattern
+```typescript
+// Always await, always catch
+async function fetchData() {
+  try {
+    const result = await someAsyncCall()
+    if (!result) throw new Error('result is empty')
+    return result
+  } catch (err) {
+    handleError(err, 'file.ts', 'fetchData')
+    return null
+  }
+}
+```
+
+### Checklist
+- [ ] Is `await` missing before an async call?
+- [ ] Is a `.then()` chain missing a `.catch()`?
+- [ ] Is a Promise being returned without awaiting it?
+- [ ] Are two async calls racing without proper sequencing?
+
+---
+
+## Type Errors
+
+### Pattern
+```typescript
+// Validate type at boundary before using
+function processUser(user: unknown) {
+  if (!user || typeof user !== 'object') {
+    handleError(new Error('invalid user type'), 'file.ts', 'processUser')
+    return null
+  }
+  const typedUser = user as User
+  // safe to use typedUser below
+}
+```
+
+### Checklist
+- [ ] Is an `any` type hiding a real type mismatch?
+- [ ] Is an API response being used without type validation?
+- [ ] Is a number being used where a string is expected?
+
+---
+
+## React Render Errors
+
+### Pattern
+```typescript
+// Guard before rendering
+function UserCard({ user }: { user: User | null }) {
+  if (!user) return null  // or return <Skeleton />
+  return <div>{user.name}</div>
+}
+```
+
+### Checklist
+- [ ] Is a component rendering before data is loaded?
+- [ ] Is `useEffect` missing a dependency causing stale state?
+- [ ] Is state being mutated directly instead of via setter?
+- [ ] Is `useEffect` running twice due to React strict mode?
+
+---
+
+## API Route Errors
+
+### Pattern
+```typescript
+// Always validate request body
+export async function POST(req: Request) {
+  try {
+    const body = await req.json()
+    if (!body?.userId) {
+      return Response.json(
+        { error: 'userId is required' },
+        { status: 400 }
+      )
+    }
+    // proceed
+  } catch (err) {
+    handleError(err, 'app/api/route.ts', 'POST')
+    return Response.json({ error: 'internal server error' }, { status: 500 })
+  }
+}
+```
+
+### Checklist
+- [ ] Is the request body being parsed correctly?
+- [ ] Is the auth session being checked before processing?
+- [ ] Is a 400 returned for bad input vs 500 for server error?
+- [ ] Is the API route method correct (GET vs POST)?
+
+---
+
+## Environment Variable Errors
+
+### Pattern
+```typescript
+// Validate env vars at startup
+const requiredEnvVars = [
+  'NEXT_PUBLIC_SUPABASE_URL',
+  'NEXT_PUBLIC_SUPABASE_ANON_KEY'
+]
+
+requiredEnvVars.forEach((key) => {
+  if (!process.env[key]) {
+    throw new Error(`Missing required env var: ${key}`)
+  }
+})
+```
+
+### Checklist
+- [ ] Is `.env.local` present and not committed?
+- [ ] Are `NEXT_PUBLIC_` prefixes correct for client side vars?
+- [ ] Are env vars available in the deployment environment?
+- [ ] Was the dev server restarted after adding new env vars?
+
+---
+
+## What NOT to Do
+- Do not add console.log and forget to remove it
+- Do not catch an error and return undefined silently
+- Do not assume the error is in a different file than the log says
+- Do not fix the symptom without understanding the root cause

.claude/skills/supabase.md

@@ -0,0 +1,277 @@
+# Skill — Supabase Patterns & Operations
+
+## Purpose
+Read this file when writing any Supabase code.
+Contains reusable patterns, query templates and common gotchas.
+Do not guess schema or policies — confirm first.
+
+---
+
+## Client Setup
+
+### Client initialisation (Next.js)
+```typescript
+// lib/supabase.ts
+import { createClient } from '@supabase/supabase-js'
+
+const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!
+const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+```
+
+### Server side client (API routes / server components)
+```typescript
+// lib/supabase-server.ts
+import { createClient } from '@supabase/supabase-js'
+
+export const supabaseAdmin = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.SUPABASE_SERVICE_ROLE_KEY!
+)
+```
+
+---
+
+## Auth Patterns
+
+### Get current session
+```typescript
+const { data: { session }, error } = await supabase.auth.getSession()
+if (!session) {
+  handleError(new Error('no active session'), 'file.ts', 'functionName')
+  return null
+}
+```
+
+### Listen to auth state changes
+```typescript
+supabase.auth.onAuthStateChange((event, session) => {
+  if (event === 'SIGNED_OUT') {
+    // clear local state
+  }
+  if (event === 'TOKEN_REFRESHED') {
+    // update session in state
+  }
+})
+```
+
+### Sign out
+```typescript
+const { error } = await supabase.auth.signOut()
+if (error) handleError(error, 'file.ts', 'signOut')
+```
+
+---
+
+## Query Patterns
+
+### Select with error handling
+```typescript
+async function getRows(table: string, userId: string) {
+  try {
+    const { data, error } = await supabase
+      .from(table)
+      .select('*')
+      .eq('user_id', userId)
+
+    if (error) throw error
+    return data ?? []
+  } catch (err) {
+    handleError(err, 'lib/supabase.ts', 'getRows')
+    return []
+  }
+}
+```
+
+### Insert with error handling
+```typescript
+async function insertRow(table: string, payload: object) {
+  try {
+    const { data, error } = await supabase
+      .from(table)
+      .insert(payload)
+      .select()
+      .single()
+
+    if (error) throw error
+    return data
+  } catch (err) {
+    handleError(err, 'lib/supabase.ts', 'insertRow')
+    return null
+  }
+}
+```
+
+### Update with error handling
+```typescript
+async function updateRow(table: string, id: string, payload: object) {
+  try {
+    const { data, error } = await supabase
+      .from(table)
+      .update(payload)
+      .eq('id', id)
+      .select()
+      .single()
+
+    if (error) throw error
+    return data
+  } catch (err) {
+    handleError(err, 'lib/supabase.ts', 'updateRow')
+    return null
+  }
+}
+```
+
+### Delete with error handling
+```typescript
+async function deleteRow(table: string, id: string) {
+  try {
+    const { error } = await supabase
+      .from(table)
+      .delete()
+      .eq('id', id)
+
+    if (error) throw error
+    return true
+  } catch (err) {
+    handleError(err, 'lib/supabase.ts', 'deleteRow')
+    return false
+  }
+}
+```
+
+---
+
+## Migration Patterns
+
+### Standard migration file structure
+```sql
+-- supabase/migrations/[timestamp]_create_users.sql
+
+-- Create table
+CREATE TABLE IF NOT EXISTS users (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email TEXT NOT NULL UNIQUE,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Enable RLS
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+
+-- Policies
+CREATE POLICY "Users can view own record"
+ON users FOR SELECT
+USING (auth.uid() = id);
+
+CREATE POLICY "Users can update own record"
+ON users FOR UPDATE
+USING (auth.uid() = id);
+```
+
+### Add column migration
+```sql
+ALTER TABLE users ADD COLUMN IF NOT EXISTS display_name TEXT;
+```
+
+### Add index migration
+```sql
+CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
+```
+
+---
+
+## RLS Policy Templates
+
+### Full CRUD for owner
+```sql
+CREATE POLICY "owner select" ON table_name FOR SELECT USING (auth.uid() = user_id);
+CREATE POLICY "owner insert" ON table_name FOR INSERT WITH CHECK (auth.uid() = user_id);
+CREATE POLICY "owner update" ON table_name FOR UPDATE USING (auth.uid() = user_id);
+CREATE POLICY "owner delete" ON table_name FOR DELETE USING (auth.uid() = user_id);
+```
+
+### Public read, owner write
+```sql
+CREATE POLICY "public read" ON table_name FOR SELECT USING (true);
+CREATE POLICY "owner insert" ON table_name FOR INSERT WITH CHECK (auth.uid() = user_id);
+CREATE POLICY "owner update" ON table_name FOR UPDATE USING (auth.uid() = user_id);
+```
+
+### Service role bypass (admin operations)
+```sql
+-- Use supabaseAdmin client (service role) — bypasses RLS
+-- Never expose service role key client side
+```
+
+---
+
+## Realtime Patterns
+
+### Subscribe to table changes
+```typescript
+const channel = supabase
+  .channel('table-changes')
+  .on('postgres_changes',
+    { event: '*', schema: 'public', table: 'your_table' },
+    (payload) => {
+      console.info(`[INFO] realtime event: ${payload.eventType}`)
+    }
+  )
+  .subscribe()
+
+// Cleanup
+channel.unsubscribe()
+```
+
+---
+
+## Storage Patterns
+
+### Upload file
+```typescript
+async function uploadFile(bucket: string, path: string, file: File) {
+  try {
+    const { data, error } = await supabase.storage
+      .from(bucket)
+      .upload(path, file, { upsert: true })
+
+    if (error) throw error
+    return data
+  } catch (err) {
+    handleError(err, 'lib/storage.ts', 'uploadFile')
+    return null
+  }
+}
+```
+
+### Get public URL
+```typescript
+function getPublicUrl(bucket: string, path: string): string {
+  const { data } = supabase.storage.from(bucket).getPublicUrl(path)
+  return data.publicUrl
+}
+```
+
+---
+
+## Common Gotchas
+
+| Gotcha | Rule |
+|--------|------|
+| RLS blocks everything by default | Always add policies after enabling RLS |
+| `.single()` throws if no row found | Use `.maybeSingle()` if row may not exist |
+| Service role bypasses RLS | Never use service role client on frontend |
+| Auth session expires | Always check session before DB operations |
+| Migration order matters | Never edit existing migration files |
+| `.select()` after insert needed | Add `.select().single()` to get inserted row back |
+
+---
+
+## What NOT to Do
+- Do not edit existing migration files — create new ones
+- Do not disable RLS on any table
+- Do not use service role key on client side
+- Do not call DB without checking session first
+- Do not use `.single()` when row might not exist

.claude/skills/testing.md

@@ -0,0 +1,220 @@
+# Skill — Reusable Test Patterns by Feature Type
+
+## Purpose
+Read this file when writing tests for a specific feature type.
+Contains reusable test templates organised by category.
+Always follow naming conventions from docs/testing.md.
+
+---
+
+## Auth Feature Tests
+
+```typescript
+// tests/unit/auth/session.test.ts
+describe('session handling', () => {
+  it('returns null when no session exists', async () => {
+    mockSupabase.auth.getSession.mockResolvedValueOnce({
+      data: { session: null }, error: null
+    })
+    const result = await getSession()
+    expect(result).toBeNull()
+  })
+
+  it('returns session when authenticated', async () => {
+    mockSupabase.auth.getSession.mockResolvedValueOnce({
+      data: { session: mockSession }, error: null
+    })
+    const result = await getSession()
+    expect(result).toEqual(mockSession)
+  })
+
+  it('handles auth error gracefully', async () => {
+    mockSupabase.auth.getSession.mockResolvedValueOnce({
+      data: { session: null }, error: new Error('auth failed')
+    })
+    const result = await getSession()
+    expect(result).toBeNull()
+  })
+})
+```
+
+---
+
+## DB Query Tests
+
+```typescript
+// tests/unit/lib/users.test.ts
+describe('fetchUser', () => {
+  it('returns user for valid id', async () => {
+    mockSupabase.from().select().eq.mockResolvedValueOnce({
+      data: mockUser, error: null
+    })
+    const result = await fetchUser('valid-uuid')
+    expect(result).toEqual(mockUser)
+  })
+
+  it('returns null for null id', async () => {
+    const result = await fetchUser(null as any)
+    expect(result).toBeNull()
+  })
+
+  it('returns null for empty string id', async () => {
+    const result = await fetchUser('')
+    expect(result).toBeNull()
+  })
+
+  it('returns null on DB error', async () => {
+    mockSupabase.from().select().eq.mockResolvedValueOnce({
+      data: null, error: new Error('DB error')
+    })
+    const result = await fetchUser('valid-uuid')
+    expect(result).toBeNull()
+  })
+
+  it('returns null when DB returns null data', async () => {
+    mockSupabase.from().select().eq.mockResolvedValueOnce({
+      data: null, error: null
+    })
+    const result = await fetchUser('valid-uuid')
+    expect(result).toBeNull()
+  })
+})
+```
+
+---
+
+## API Route Tests
+
+```typescript
+// tests/integration/api/users.integration.test.ts
+describe('POST /api/users', () => {
+  it('returns 400 when userId is missing', async () => {
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify({})
+    })
+    expect(res.status).toBe(400)
+  })
+
+  it('returns 401 when not authenticated', async () => {
+    mockGetSession.mockResolvedValueOnce(null)
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify({ userId: 'uuid' })
+    })
+    expect(res.status).toBe(401)
+  })
+
+  it('returns 200 with valid input and session', async () => {
+    mockGetSession.mockResolvedValueOnce(mockSession)
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify({ userId: 'uuid' })
+    })
+    expect(res.status).toBe(200)
+  })
+
+  it('returns 500 on unexpected server error', async () => {
+    mockGetSession.mockRejectedValueOnce(new Error('unexpected'))
+    const res = await fetch('/api/users', {
+      method: 'POST',
+      body: JSON.stringify({ userId: 'uuid' })
+    })
+    expect(res.status).toBe(500)
+  })
+})
+```
+
+---
+
+## React Component Tests
+
+```typescript
+// tests/components/UserCard.test.tsx
+import { render, screen } from '@testing-library/react'
+import UserCard from '@/components/UserCard'
+
+describe('UserCard', () => {
+  it('renders user name when user exists', () => {
+    render(<UserCard user={mockUser} />)
+    expect(screen.getByText(mockUser.name)).toBeInTheDocument()
+  })
+
+  it('renders nothing when user is null', () => {
+    const { container } = render(<UserCard user={null} />)
+    expect(container.firstChild).toBeNull()
+  })
+
+  it('renders loading state when isLoading is true', () => {
+    render(<UserCard user={null} isLoading={true} />)
+    expect(screen.getByTestId('skeleton')).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Utility Function Tests
+
+```typescript
+// tests/unit/utils/validation.test.ts
+describe('isValidId', () => {
+  it('returns true for valid uuid', () => {
+    expect(isValidId('550e8400-e29b-41d4-a716-446655440000')).toBe(true)
+  })
+
+  it('returns false for null', () => {
+    expect(isValidId(null)).toBe(false)
+  })
+
+  it('returns false for empty string', () => {
+    expect(isValidId('')).toBe(false)
+  })
+
+  it('returns false for whitespace only', () => {
+    expect(isValidId('   ')).toBe(false)
+  })
+
+  it('returns false for undefined', () => {
+    expect(isValidId(undefined)).toBe(false)
+  })
+})
+```
+
+---
+
+## Mock Templates
+
+### Mock user
+```typescript
+export const mockUser = {
+  id: '550e8400-e29b-41d4-a716-446655440000',
+  email: 'test@example.com',
+  created_at: '2025-01-01T00:00:00Z'
+}
+```
+
+### Mock session
+```typescript
+export const mockSession = {
+  access_token: 'mock-token',
+  user: mockUser,
+  expires_at: Date.now() + 3600
+}
+```
+
+### Reset mocks between tests
+```typescript
+beforeEach(() => {
+  jest.clearAllMocks()
+})
+```
+
+---
+
+## What NOT to Do
+- Do not write tests that always pass regardless of logic
+- Do not skip null and undefined test cases
+- Do not forget to reset mocks between tests
+- Do not test implementation details — test behaviour
+- Do not mock everything — let utility functions run real logic

.gitattributes

@@ -0,0 +1,2 @@
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text

claude.md

@@ -0,0 +1,80 @@
+# Claude.md — Global Instructions
+
+## Identity
+You are a focused, phase-gated AI engineer on this project.
+Read only what is needed. Act only on the current phase prompt.
+
+---
+
+## On Every Session Start
+1. Read `docs/index.md` to orient yourself
+2. Read `session/phase-log.md` to know current progress
+3. Read `session/context.md` for any carry-over from last session
+4. Load the current phase prompt from `prompts/phase-X.md`
+5. Do NOT read all docs at once — load on demand only
+
+---
+
+## Mandatory Rules (Non-Negotiable)
+
+### Phase Gating
+- Work only on the current phase prompt
+- Do not proceed to next phase without explicit user confirmation
+- Confirm all tests pass before marking a phase done
+
+### Error Handling
+- Follow `docs/debugging.md` for all error handling patterns
+- Every error must log: file name, function, reason, fix hint
+- When debugging: check the specific file first, nothing else
+
+### Testing
+- Follow `docs/testing.md` for all test patterns
+- Update test files after every feature, not at project end
+- Provide CLI commands to run tests with every implementation
+
+### Supabase
+- Follow `.claude/skills/supabase.md` for all DB operations
+- Always provide CLI command first, dashboard steps if CLI not possible
+
+### Code Quality
+- Handle all edge cases inline
+- No infinite loops, no redundant API calls
+- Fail fast, log clearly
+
+---
+
+## On Every Session End
+1. Give a one-liner git commit message for every change made
+2. Do NOT push to GitHub
+3. Update `session/summary.md` with what was done
+4. Append one line to `session/phase-log.md`
+5. Update `docs/progress.md` with completed items
+6. If something failed or a workaround was used → add to `docs/learnings.md`
+
+---
+
+## Reference Map (Load on Demand)
+
+| Need | File |
+|------|------|
+| What does each file do | `docs/index.md` |
+| Requirements + phases | `docs/prd.md` |
+| Current progress | `docs/progress.md` |
+| Past failures + fixes | `docs/learnings.md` |
+| System architecture | `docs/architecture.md` |
+| Error handling patterns | `docs/debugging.md` |
+| Test strategy + commands | `docs/testing.md` |
+| Supabase operations | `.claude/skills/supabase.md` |
+| Deploy steps | `docs/deployment.md` |
+| Feature workflow | `docs/workflows/feature.md` |
+| Bug fix workflow | `docs/workflows/bugfix.md` |
+| Refactor workflow | `docs/workflows/refactor.md` |
+
+---
+
+## Never Do
+- Do not read all `.md` files at session start
+- Do not push to GitHub
+- Do not skip writing tests for a feature
+- Do not proceed to next phase without user confirmation
+- Do not guess Supabase schema — always confirm before migrating

docs/architecture.md

@@ -0,0 +1,123 @@
+# Architecture — Stack, Structure & Data Models
+
+## Purpose
+Read this file when building or modifying any structural part
+of the project. Update this file when architecture changes.
+Do not guess the stack — confirm here first.
+
+---
+
+## Tech Stack
+Frontend:     [e.g. Next.js 14, React, TypeScript]
+Styling:      [e.g. Tailwind CSS, shadcn/ui]
+Backend:      [e.g. Next.js API Routes / Edge Functions]
+Database:     Supabase (PostgreSQL)
+Auth:         Supabase Auth
+Storage:      Supabase Storage
+Deployment:   [e.g. Vercel / Railway]
+Testing:      Jest, ts-jest, React Testing Library
+Package Mgr:  [e.g. npm / pnpm]
+
+---
+
+## Folder Structure
+project-root/
+├── src/
+│   ├── app/                  ← Next.js app router pages
+│   │   ├── (auth)/           ← auth route group
+│   │   ├── (dashboard)/      ← protected route group
+│   │   └── api/              ← API routes
+│   ├── components/           ← reusable UI components
+│   │   ├── ui/               ← base components (shadcn)
+│   │   └── [feature]/        ← feature specific components
+│   ├── lib/                  ← shared utilities and clients
+│   │   ├── supabase.ts       ← supabase client
+│   │   ├── supabase-server.ts← server side supabase client
+│   │   └── utils.ts          ← shared utility functions
+│   ├── hooks/                ← custom React hooks
+│   ├── types/                ← TypeScript type definitions
+│   └── constants/            ← app wide constants
+├── supabase/
+│   └── migrations/           ← all DB migration files
+├── tests/                    ← all test files
+├── docs/                     ← project documentation
+├── scripts/                  ← shell scripts
+└── logs/                     ← runtime and test logs
+
+---
+
+## Database Schema
+
+### Tables
+[Update this section as tables are created]
+users
+id            UUID PRIMARY KEY DEFAULT gen_random_uuid()
+email         TEXT NOT NULL UNIQUE
+created_at    TIMESTAMPTZ DEFAULT NOW()
+updated_at    TIMESTAMPTZ DEFAULT NOW()
+
+### Relationships
+[Document foreign keys and relationships here]
+users.id ← referenced by [table].[column]
+
+### RLS Summary
+[Document which tables have RLS enabled and policy types]
+Table         RLS     Policies
+
+users         YES     owner CRUD
+
+---
+
+## Auth Flow
+
+User lands on /login
+Supabase Auth handles email/OAuth
+On success → session stored in cookie
+Protected routes check session via middleware
+API routes validate session server side
+On signout → session cleared, redirect to /login
+
+
+---
+
+## API Routes
+[Document API routes as they are created]
+POST  /api/auth/login     ← handle login
+POST  /api/auth/logout    ← handle logout
+GET   /api/user           ← get current user
+
+---
+
+## Environment Variables
+NEXT_PUBLIC_SUPABASE_URL          ← supabase project URL
+NEXT_PUBLIC_SUPABASE_ANON_KEY     ← supabase anon key
+SUPABASE_SERVICE_ROLE_KEY         ← server only, never expose
+
+---
+
+## Key Architectural Decisions
+[Document WHY decisions were made as project grows]
+[YYYY-MM-DD] — Used app router over pages router for better
+server component support
+[YYYY-MM-DD] — Used Supabase RLS over API-level auth checks
+for defence in depth
+
+---
+
+## Constraints
+[Document hard technical constraints]
+
+No direct DB access from client side components
+Service role key only used in server side code
+All DB changes must go through migration files
+RLS must be enabled on every table
+
+
+---
+
+## Rules for This File
+- Update when a new table is added
+- Update when a new API route is created
+- Update when a key architectural decision is made
+- Keep schema section in sync with actual migrations
+- Do not document implementation details — only structure

docs/debugging.md

@@ -0,0 +1,126 @@
+# Debugging — Error Handling, Logging & Debug Strategy
+
+## Purpose
+Read this file when an error occurs or when implementing error
+handling for any feature. Do not guess — follow this exactly.
+
+---
+
+## Core Principle
+**Check the specific file where the error occurred. Nothing else.**
+Do not scan the entire codebase. Logs must tell you:
+- WHERE it broke (file + function)
+- WHY it broke (reason)
+- HOW to fix it (hint)
+
+---
+
+## Standard Error Log Format
+
+Every error logged must follow this exact structure:
+
+[ERROR] [timestamp] [file:function] — reason — fix hint
+
+**Example:**
+[ERROR] [2025-01-15T10:32:00Z] [lib/supabase.ts:fetchUser] — user_id is null — check auth session before calling fetchUser
+
+---
+
+## Error Handler Template
+
+### TypeScript / Next.js
+```typescript
+function handleError(error: unknown, file: string, fn: string): void {
+  const timestamp = new Date().toISOString()
+  const reason = error instanceof Error ? error.message : String(error)
+  const hint = getFixHint(reason)
+
+  console.error(`[ERROR] [${timestamp}] [${file}:${fn}] — ${reason} — ${hint}`)
+
+  // Write to logs/errors.log in dev
+  if (process.env.NODE_ENV === 'development') {
+    appendToLog('logs/errors.log', `[ERROR] [${timestamp}] [${file}:${fn}] — ${reason} — ${hint}`)
+  }
+}
+
+function getFixHint(reason: string): string {
+  if (reason.includes('null')) return 'check for null before using this value'
+  if (reason.includes('undefined')) return 'confirm the value exists before accessing'
+  if (reason.includes('network')) return 'check network connection and API endpoint'
+  if (reason.includes('permission')) return 'verify Supabase RLS policies'
+  if (reason.includes('timeout')) return 'increase timeout or check slow query'
+  return 'check function inputs and dependencies'
+}
+```
+
+### Usage in any function
+```typescript
+// file: lib/supabase.ts
+async function fetchUser(userId: string) {
+  try {
+    if (!userId) throw new Error('user_id is null')
+    const { data, error } = await supabase.from('users').select('*').eq('id', userId)
+    if (error) throw error
+    return data
+  } catch (err) {
+    handleError(err, 'lib/supabase.ts', 'fetchUser')
+    return null
+  }
+}
+```
+
+---
+
+## Logging Levels
+
+| Level | When to Use |
+|-------|------------|
+| `[ERROR]` | Something broke, feature cannot continue |
+| `[WARN]` | Something unexpected but recoverable |
+| `[INFO]` | Key state changes, successful operations |
+| `[DEBUG]` | Verbose, dev-only, remove before production |
+
+---
+
+## Debug Steps — When Something Breaks
+
+1. Read `logs/errors.log` — find the exact `[file:function]`
+2. Open only that file
+3. Check the function mentioned in the log
+4. Verify inputs to that function
+5. Check for null/undefined before the failure point
+6. Fix inline, do not refactor adjacent code
+7. Re-run the specific test for that function only
+
+**Do not open other files unless the log explicitly points to them.**
+
+---
+
+## Supabase Specific Errors
+
+| Error | Likely Cause | Fix |
+|-------|-------------|-----|
+| `permission denied` | RLS policy blocking query | Check policy in Supabase dashboard → Auth → Policies |
+| `relation does not exist` | Migration not applied | Run `supabase db push` |
+| `violates foreign key` | Referenced row missing | Insert parent record first |
+| `JWT expired` | Auth token stale | Refresh session with `supabase.auth.refreshSession()` |
+| `null value in column` | Missing required field | Validate inputs before insert |
+
+---
+
+## Edge Case Checklist
+Before shipping any function, verify:
+- [ ] What happens if input is null or undefined?
+- [ ] What happens if the DB returns empty array?
+- [ ] What happens if the API call times out?
+- [ ] What happens if the user is not authenticated?
+- [ ] What happens if this runs twice simultaneously?
+
+---
+
+## What NOT to Do
+- Do not use `console.log` for errors — use `console.error` with the format above
+- Do not catch an error and do nothing with it
+- Do not log sensitive data (passwords, tokens, PII)
+- Do not open unrelated files to debug an error
+- Do not refactor while debugging — fix first, refactor later

docs/deployment.md

@@ -0,0 +1,255 @@
+# Deployment — Supabase CLI & Dashboard Instructions
+
+## Purpose
+Read this file when deploying any change to Supabase or your
+environment. Always try CLI first. Use dashboard only if CLI
+is not possible — dashboard steps will be clearly marked.
+
+---
+
+## Core Principle
+**CLI first. Dashboard only when CLI cannot do it.**
+Every deployment step must be logged and reversible.
+
+---
+
+## Prerequisites
+```bash
+# Install Supabase CLI
+npm install -g supabase
+
+# Login
+supabase login
+
+# Link to your project (run once per project)
+supabase link --project-ref YOUR_PROJECT_REF
+
+# Confirm link
+supabase status
+```
+
+---
+
+## Environment Variables
+```bash
+# .env.local (never commit this file)
+NEXT_PUBLIC_SUPABASE_URL=your_project_url
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
+SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
+```
+
+**Where to find these:**
+Dashboard → Project Settings → API → Project URL + Keys
+
+---
+
+## Database Migrations
+
+### Create a new migration
+```bash
+supabase migration new migration_name
+# Creates: supabase/migrations/[timestamp]_migration_name.sql
+# Write your SQL inside this file, then push
+```
+
+### Push migration to remote
+```bash
+supabase db push
+```
+
+### Check migration status
+```bash
+supabase migration list
+```
+
+### Reset local DB (dev only)
+```bash
+supabase db reset
+```
+
+### Pull remote schema to local
+```bash
+supabase db pull
+```
+
+---
+
+## Local Development
+
+### Start local Supabase
+```bash
+supabase start
+# Gives you local URL, anon key, service role key
+```
+
+### Stop local Supabase
+```bash
+supabase stop
+```
+
+### View local DB in browser
+```bash
+supabase studio
+# Opens Supabase Studio at localhost:54323
+```
+
+---
+
+## Edge Functions
+
+### Create a new edge function
+```bash
+supabase functions new function-name
+```
+
+### Serve locally
+```bash
+supabase functions serve function-name --env-file .env.local
+```
+
+### Deploy edge function
+```bash
+supabase functions deploy function-name
+```
+
+### Set environment secret for edge function
+```bash
+supabase secrets set KEY=value
+```
+
+### List secrets
+```bash
+supabase secrets list
+```
+
+---
+
+## Storage
+
+### CLI — not fully supported for bucket creation
+**→ Use Dashboard for bucket creation**
+
+#### Dashboard Steps — Create Storage Bucket
+
+Go to Supabase Dashboard → Storage
+Click "New bucket"
+Enter bucket name
+Toggle public/private
+Click "Create bucket"
+
+### Upload file via CLI
+```bash
+supabase storage cp ./local-file.png ss:///bucket-name/path/file.png
+```
+
+---
+
+## Row Level Security (RLS)
+
+### CLI — enable RLS on a table
+```sql
+-- Inside a migration file
+ALTER TABLE your_table ENABLE ROW LEVEL SECURITY;
+```
+
+### CLI — create a policy via migration
+```sql
+CREATE POLICY "Users can view own data"
+ON your_table
+FOR SELECT
+USING (auth.uid() = user_id);
+```
+
+### Dashboard Steps — RLS Policy (if migration not possible)
+
+Go to Supabase Dashboard → Authentication → Policies
+Select your table
+Click "New Policy"
+Choose template or write custom
+Click "Review" then "Save Policy"
+
+---
+
+## Auth Configuration
+
+### CLI — not supported for OAuth provider setup
+**→ Use Dashboard for OAuth setup**
+
+#### Dashboard Steps — Enable OAuth Provider
+
+Go to Dashboard → Authentication → Providers
+Select provider (Google, GitHub, etc.)
+Enter Client ID and Secret
+Copy callback URL → paste into provider's OAuth app
+Click "Save"
+
+### Set auth email templates
+
+Dashboard → Authentication → Email Templates
+→ Edit confirm signup / reset password templates
+
+---
+
+## scripts/deploy.sh
+```bash
+#!/bin/bash
+echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Starting deployment..." >> logs/errors.log
+
+# Run tests first — abort if they fail
+bash scripts/test.sh
+if [ $? -ne 0 ]; then
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Deployment aborted — tests failed" >> logs/errors.log
+  exit 1
+fi
+
+# Push DB migrations
+echo "Pushing DB migrations..."
+supabase db push
+if [ $? -ne 0 ]; then
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Migration failed — check supabase logs" >> logs/errors.log
+  exit 1
+fi
+
+echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Deployment complete" >> logs/errors.log
+```
+
+---
+
+## Rollback
+
+### Rollback last migration
+```bash
+# Supabase does not have auto-rollback
+# Write a reverse migration manually
+
+supabase migration new rollback_migration_name
+# Write reverse SQL (DROP TABLE, ALTER, etc.)
+supabase db push
+```
+
+### Dashboard Steps — Rollback (if CLI fails)
+
+Go to Dashboard → Database → Migrations
+Identify the migration to reverse
+Go to Dashboard → SQL Editor
+Write and run reverse SQL manually
+
+---
+
+## Deployment Checklist
+- [ ] All tests pass (`bash scripts/test.sh`)
+- [ ] `.env.local` is not committed
+- [ ] Migration file created for every schema change
+- [ ] RLS enabled on every new table
+- [ ] Edge functions tested locally before deploy
+- [ ] `supabase db push` confirms no errors
+- [ ] One-liner git commit message written
+
+---
+
+## What NOT to Do
+- Do not edit schema directly in Dashboard without a migration file
+- Do not push migrations without running tests first
+- Do not commit `.env.local` or any file with keys
+- Do not disable RLS on any table in production
+- Do not deploy edge functions without local testing first

docs/index.md

@@ -0,0 +1,78 @@
+# Index — What Every File Does & When to Read It
+
+## Purpose
+This is your orientation file. Read this once at session start.
+It tells you what exists, what it does, and when to load it.
+
+---
+
+## Core Files
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `claude.md` | Global rules, session start/end checklist | Every session start |
+| `docs/index.md` | This file — master map | Every session start |
+| `session/phase-log.md` | One-liner per phase, current status | Every session start |
+| `session/context.md` | Carry-over notes from last session | Every session start |
+| `session/summary.md` | What was done in last session | Only if context is unclear |
+
+---
+
+## Project State Files
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `docs/prd.md` | Full PRD, all 8 phases, requirements | Phase start or on demand |
+| `docs/progress.md` | One-liner per feature, pass/fail status | When checking what's done |
+| `docs/learnings.md` | Past failures, workarounds, gotchas | When hitting a repeated error |
+| `docs/architecture.md` | Stack, data models, folder structure | When building or modifying structure |
+
+---
+
+## How-To Reference Files
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `docs/debugging.md` | Error format, log structure, debug steps | When an error occurs |
+| `docs/testing.md` | Test strategy, CLI commands, log format | When writing or running tests |
+| `docs/deployment.md` | Supabase CLI + dashboard deploy steps | When deploying any change |
+| `.claude/skills/supabase.md` | Supabase patterns, queries, migrations | When writing DB code |
+| `.claude/skills/debugging.md` | Reusable debug snippets by error type | When stuck on a specific error |
+| `.claude/skills/testing.md` | Reusable test patterns by feature type | When writing tests |
+
+---
+
+## Workflow Files
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `docs/workflows/feature.md` | Step-by-step for building a new feature | Every new feature |
+| `docs/workflows/bugfix.md` | Step-by-step for fixing a bug | Every bug fix |
+| `docs/workflows/refactor.md` | Step-by-step for refactoring code | Every refactor |
+
+---
+
+## Phase Prompts
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `prompts/phase-1.md` through `phase-8.md` | Individual phase instructions | Only the current phase |
+
+---
+
+## Scripts & Logs
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `scripts/test.sh` | Run all tests with logging | When running tests |
+| `scripts/dev.sh` | Start dev environment | When starting dev |
+| `scripts/deploy.sh` | Deploy to Supabase + environment | When deploying |
+| `logs/errors.log` | Runtime error output | When debugging a failure |
+| `logs/test.log` | Test run output | When a test fails |
+
+---
+
+## Rules for This File
+- Do not add implementation details here
+- Do not add code here
+- Only update this file if a new reference file is added to the project

docs/learnings.md

@@ -0,0 +1,56 @@
+# Learnings — Failures, Workarounds & Time Savers
+
+## Purpose
+Read this file when hitting a repeated error or unexpected behaviour.
+Each bullet is a one-liner under 15 words.
+No explanations. Only things that save time in future sessions.
+
+---
+
+## Rules for This File
+- One line per learning, under 15 words
+- Add immediately when a failure or workaround is found
+- Never delete a line — they compound over time
+- Group by category as list grows
+
+---
+
+## Supabase
+- [ ] Add learnings here as they are discovered
+
+## Auth
+- [ ] Add learnings here as they are discovered
+
+## Testing
+- [ ] Add learnings here as they are discovered
+
+## Next.js
+- [ ] Add learnings here as they are discovered
+
+## Deployment
+- [ ] Add learnings here as they are discovered
+
+## General
+- [ ] Add learnings here as they are discovered
+
+---
+
+## Example Format (remove when real entries exist)
+```
+## Supabase
+- RLS blocks all queries by default — always add select policy first
+- supabase db push fails silently if migration has syntax error
+- Foreign key inserts require parent row to exist first
+
+## Auth
+- JWT expires after 1hr — always call refreshSession before DB ops
+- getSession returns null on hard refresh — use onAuthStateChange instead
+
+## Testing
+- Jest mock must be reset between tests or state bleeds across cases
+- Supabase client must be mocked at module level not inside test
+
+## Next.js
+- useEffect runs twice in strict mode — guard with cleanup function
+- API routes do not have access to cookies without explicit parsing
+```

docs/prd.md

@@ -0,0 +1,244 @@
+# PRD — Product Requirements Document
+
+## Purpose
+Read this file at phase start to understand requirements.
+Contains full product vision, all phases and acceptance criteria.
+Do not implement anything not listed here without user confirmation.
+
+---
+
+## Product Overview
+Product Name:   [name]
+Description:    [one paragraph max]
+Primary User:   [who is this for]
+Core Problem:   [what problem does this solve]
+
+---
+
+## Success Metrics
+
+[metric one — measurable]
+[metric two — measurable]
+[metric three — measurable]
+
+
+---
+
+## Technical Constraints
+
+[constraint one]
+[constraint two]
+[constraint three]
+
+
+---
+
+## Phase Overview
+Phase 1 — [name] — [one liner]
+Phase 2 — [name] — [one liner]
+Phase 3 — [name] — [one liner]
+Phase 4 — [name] — [one liner]
+Phase 5 — [name] — [one liner]
+Phase 6 — [name] — [one liner]
+Phase 7 — [name] — [one liner]
+Phase 8 — [name] — [one liner]
+
+---
+
+## Phase 1 — [Phase Name]
+
+### Goal
+[One paragraph — what this phase achieves]
+
+### Features
+
+[feature name] — [one liner description]
+[feature name] — [one liner description]
+[feature name] — [one liner description]
+
+
+### Acceptance Criteria
+
+ [specific testable criterion]
+ [specific testable criterion]
+ [specific testable criterion]
+
+
+### Out of Scope for This Phase
+
+[what is explicitly NOT included]
+[what is explicitly NOT included]
+
+
+---
+
+## Phase 2 — [Phase Name]
+
+### Goal
+[One paragraph]
+
+### Features
+
+[feature name] — [one liner]
+[feature name] — [one liner]
+
+
+### Acceptance Criteria
+
+ [criterion]
+ [criterion]
+
+
+### Out of Scope for This Phase
+
+[excluded item]
+
+
+---
+
+## Phase 3 — [Phase Name]
+
+### Goal
+[One paragraph]
+
+### Features
+
+[feature name] — [one liner]
+
+
+### Acceptance Criteria
+
+ [criterion]
+
+
+### Out of Scope for This Phase
+
+[excluded item]
+
+
+---
+
+## Phase 4 — [Phase Name]
+
+### Goal
+[One paragraph]
+
+### Features
+
+[feature name] — [one liner]
+
+
+### Acceptance Criteria
+
+ [criterion]
+
+
+### Out of Scope for This Phase
+
+[excluded item]
+
+
+---
+
+## Phase 5 — [Phase Name]
+
+### Goal
+[One paragraph]
+
+### Features
+
+[feature name] — [one liner]
+
+
+### Acceptance Criteria
+
+ [criterion]
+
+
+### Out of Scope for This Phase
+
+[excluded item]
+
+
+---
+
+## Phase 6 — [Phase Name]
+
+### Goal
+[One paragraph]
+
+### Features
+
+[feature name] — [one liner]
+
+
+### Acceptance Criteria
+
+ [criterion]
+
+
+### Out of Scope for This Phase
+
+[excluded item]
+
+
+---
+
+## Phase 7 — [Phase Name]
+
+### Goal
+[One paragraph]
+
+### Features
+
+[feature name] — [one liner]
+
+
+### Acceptance Criteria
+
+ [criterion]
+
+
+### Out of Scope for This Phase
+
+[excluded item]
+
+
+---
+
+## Phase 8 — [Phase Name]
+
+### Goal
+[One paragraph]
+
+### Features
+
+[feature name] — [one liner]
+
+
+### Acceptance Criteria
+
+ [criterion]
+
+
+### Out of Scope for This Phase
+
+[excluded item]
+
+
+---
+
+## Phase Gate Rules
+- Do not start a phase without user confirmation
+- Do not proceed to next phase if current tests are failing
+- Do not implement features outside current phase scope
+- Mark acceptance criteria as complete before closing phase
+- All criteria must be checked before phase is marked COMPLETE
+
+---
+
+## Rules for This File
+- Fill in placeholders before starting Phase 1
+- Do not modify acceptance criteria mid phase
+- Do not add features to a phase that is in progress
+- New features go into the next available phase or a new phase

docs/progress.md

@@ -0,0 +1,58 @@
+# Progress — Feature & Phase Status
+
+## Purpose
+Read this file to know exactly what is done, in progress, or pending.
+One liner per feature. Update after every feature implementation.
+Do not read entire codebase to understand progress — read this file.
+
+---
+
+## Status Legend
+
+✅ done        — implemented, tested, committed
+🔄 in progress — currently being worked on
+⏳ pending     — not started yet
+❌ blocked     — cannot proceed, reason noted
+🐛 bug         — implemented but has known failing test
+
+---
+
+## Phase 1 — [Phase Name]
+⏳ [feature name] — [one line description]
+⏳ [feature name] — [one line description]
+⏳ [feature name] — [one line description]
+
+## Phase 2 — [Phase Name]
+⏳ [feature name] — [one line description]
+⏳ [feature name] — [one line description]
+
+## Phase 3 — [Phase Name]
+⏳ [feature name] — [one line description]
+
+## Phase 4 — [Phase Name]
+⏳ [feature name] — [one line description]
+
+## Phase 5 — [Phase Name]
+⏳ [feature name] — [one line description]
+
+## Phase 6 — [Phase Name]
+⏳ [feature name] — [one line description]
+
+## Phase 7 — [Phase Name]
+⏳ [feature name] — [one line description]
+
+## Phase 8 — [Phase Name]
+⏳ [feature name] — [one line description]
+
+---
+
+## Blocked Items
+❌ [feature name] — blocked by: [reason]
+
+---
+
+## Rules for This File
+- One line per feature, no paragraphs
+- Update status after every feature, not at end of phase
+- Never delete a line — only update its status
+- If blocked, note the reason inline

docs/testing.md

@@ -0,0 +1,199 @@
+# Testing — Strategy, Patterns & CLI Commands
+
+## Purpose
+Read this file when writing tests or running them.
+Follow this exactly for every feature implementation.
+
+---
+
+## Core Principle
+**Write tests after every feature. Never at the end of the project.**
+Every test failure must tell you:
+- WHICH test failed (test name + file)
+- WHY it failed (expected vs received)
+- WHERE it failed (line number)
+
+---
+
+## Testing Stack
+- **Unit + Integration:** Jest + ts-jest
+- **API Routes:** Supertest
+- **UI Components:** React Testing Library
+- **DB (Supabase):** Mocked with jest.mock or Supabase local instance
+
+---
+
+## Folder Structure
+
+tests/
+├── unit/
+│   ├── lib/
+│   └── utils/
+├── integration/
+│   ├── api/
+│   └── db/
+├── components/
+└── setup.ts
+
+---
+
+## Test File Naming Convention
+[feature-name].test.ts        ← unit test
+[feature-name].integration.test.ts  ← integration test
+[component-name].test.tsx     ← component test
+
+---
+
+## Standard Test Template
+
+```typescript
+// tests/unit/lib/fetchUser.test.ts
+import { fetchUser } from '@/lib/supabase'
+
+describe('fetchUser', () => {
+  it('returns user when valid userId is provided', async () => {
+    const result = await fetchUser('valid-uuid')
+    expect(result).not.toBeNull()
+    expect(result).toHaveProperty('id')
+  })
+
+  it('returns null when userId is null', async () => {
+    const result = await fetchUser(null as any)
+    expect(result).toBeNull()
+  })
+
+  it('returns null when userId is empty string', async () => {
+    const result = await fetchUser('')
+    expect(result).toBeNull()
+  })
+
+  it('handles DB error gracefully', async () => {
+    // mock supabase to throw
+    jest.spyOn(supabase, 'from').mockImplementationOnce(() => {
+      throw new Error('DB connection failed')
+    })
+    const result = await fetchUser('valid-uuid')
+    expect(result).toBeNull()
+  })
+})
+```
+
+---
+
+## Edge Cases to Test for Every Feature
+
+| Scenario | What to Test |
+|----------|-------------|
+| Empty input | null, undefined, empty string |
+| Auth state | unauthenticated user, expired token |
+| DB response | empty array, null, malformed data |
+| Network | timeout, connection failure |
+| Duplicates | calling same function twice simultaneously |
+| Boundary | max length strings, zero values, negative numbers |
+
+---
+
+## CLI Commands
+
+### Run all tests
+```bash
+npm test 2>&1 | tee logs/test.log
+```
+
+### Run a specific test file
+```bash
+npm test -- tests/unit/lib/fetchUser.test.ts 2>&1 | tee logs/test.log
+```
+
+### Run tests in watch mode
+```bash
+npm test -- --watch
+```
+
+### Run tests with coverage
+```bash
+npm test -- --coverage 2>&1 | tee logs/test.log
+```
+
+### Run only failed tests
+```bash
+npm test -- --onlyFailures 2>&1 | tee logs/test.log
+```
+
+---
+
+## Test Log Format
+All test output pipes to `logs/test.log`.
+When a test fails, the log will show:
+
+FAIL tests/unit/lib/fetchUser.test.ts
+● fetchUser › returns null when userId is null
+
+expect(received).toBeNull()
+
+Received: { id: 'abc', name: 'test' }
+
+  14 |   it('returns null when userId is null', async () => {
+  15 |     const result = await fetchUser(null as any)
+> 16 |     expect(result).toBeNull()
+     |                    ^
+  17 |   })
+
+at Object.<anonymous> (tests/unit/lib/fetchUser.test.ts:16:20)
+
+---
+
+## scripts/test.sh
+```bash
+#!/bin/bash
+echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] Starting test run..." >> logs/test.log
+npm test 2>&1 | tee -a logs/test.log
+EXIT_CODE=${PIPESTATUS[0]}
+if [ $EXIT_CODE -ne 0 ]; then
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] TESTS FAILED — see above for details" >> logs/test.log
+else
+  echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] ALL TESTS PASSED" >> logs/test.log
+fi
+exit $EXIT_CODE
+```
+
+---
+
+## Test Update Rules
+- [ ] Write tests immediately after each feature is implemented
+- [ ] Never delete existing tests — only add or update
+- [ ] If a test is skipped, add a comment explaining why
+- [ ] All tests must pass before marking a phase complete
+- [ ] Run full test suite before every deployment
+
+---
+
+## Mocking Supabase
+```typescript
+// tests/setup.ts
+jest.mock('@/lib/supabase', () => ({
+  supabase: {
+    from: jest.fn().mockReturnValue({
+      select: jest.fn().mockReturnValue({
+        eq: jest.fn().mockResolvedValue({ data: [], error: null })
+      }),
+      insert: jest.fn().mockResolvedValue({ data: null, error: null }),
+      update: jest.fn().mockResolvedValue({ data: null, error: null }),
+      delete: jest.fn().mockResolvedValue({ data: null, error: null })
+    }),
+    auth: {
+      getSession: jest.fn().mockResolvedValue({ data: { session: null }, error: null }),
+      refreshSession: jest.fn().mockResolvedValue({ data: null, error: null })
+    }
+  }
+}))
+```
+
+---
+
+## What NOT to Do
+- Do not write tests after the entire project is done
+- Do not mock everything — integration tests must hit real logic
+- Do not skip edge case tests to save time
+- Do not ignore a failing test — fix it before moving on
+- Do not write tests that always pass regardless of logic

docs/workflows/bugfix.md

@@ -0,0 +1,152 @@
+# Workflow — Fixing a Bug
+
+## Purpose
+Read this file every time you need to fix a bug.
+Follow steps in order. Do not open files not mentioned in the log.
+
+---
+
+## Core Principle
+**The log tells you where to look. Trust the log. Check one file.**
+Do not scan the codebase. Do not refactor while fixing.
+
+---
+
+## Step 1 — Read the Error First
+Before touching any code:
+- [ ] Read `logs/errors.log` — find the exact error entry
+- [ ] Identify: file, function, reason, fix hint from the log
+- [ ] Read `docs/learnings.md` — has this failed before?
+- [ ] If yes → apply the known fix, skip to Step 5
+
+Error log format to look for:
+
+[ERROR] [timestamp] [file:function] — reason — fix hint
+
+---
+
+## Step 2 — Isolate Before Fixing
+State this out loud before touching code:
+Error in: [file:function]
+Reason: [from log]
+Fix hint: [from log]
+Only file I will open: [file]
+
+- [ ] Open only the file named in the log
+- [ ] Find only the function named in the log
+- [ ] Do not open any other file unless the log explicitly points there
+
+---
+
+## Step 3 — Understand the Failure
+Inside the identified function:
+- [ ] Check what input is coming in
+- [ ] Check where exactly it breaks (line from log)
+- [ ] Check if it is a null/undefined issue
+- [ ] Check if it is an auth/session issue
+- [ ] Check if it is a Supabase RLS issue
+- [ ] Reference `docs/debugging.md` → Supabase Specific Errors table
+
+---
+
+## Step 4 — Write the Fix
+- [ ] Fix only the broken logic
+- [ ] Do not rename variables or restructure the function
+- [ ] Do not fix adjacent code that looks messy
+- [ ] Add or improve error handling inline if it was missing
+- [ ] Confirm fix hint from log is addressed
+
+---
+
+## Step 5 — Write or Update the Test
+- [ ] Find the existing test file for this feature
+- [ ] If the failing case was not covered → add a test for it now
+- [ ] The test must reproduce the exact failure condition
+- [ ] Run only the test for this file first:
+```bash
+npm test -- tests/unit/[feature-name].test.ts 2>&1 | tee logs/test.log
+```
+- [ ] Confirm it passes before running full suite
+
+---
+
+## Step 6 — Run Full Test Suite
+```bash
+bash scripts/test.sh
+```
+- [ ] All tests pass
+- [ ] No previously passing test is now failing
+- [ ] If a new failure appears → treat it as a new bug, do not chain fixes
+
+---
+
+## Step 7 — Update Docs
+- [ ] Add one-liner to `docs/progress.md` under the feature
+- [ ] If this was a repeated failure or needed a workaround → add to `docs/learnings.md`
+- [ ] Append one line to `session/phase-log.md`
+- [ ] Update `session/summary.md`
+
+---
+
+## Step 8 — Git Commit Message
+Provide one-liner commit message in this format:
+
+fix([scope]): [what was broken and what fixed it]
+Examples:
+fix(auth): handle null session before calling fetchUser
+fix(dashboard): return empty array instead of null on no results
+fix(db): add missing RLS policy for users table select
+
+**Do NOT push to GitHub. Hand the message to the user.**
+
+---
+
+## Step 9 — Confirm with User
+- [ ] Show exactly what was changed and in which file
+- [ ] Show test results
+- [ ] Show commit message
+- [ ] Ask: "Confirmed fixed — ready to continue?"
+- [ ] Do NOT proceed until user confirms
+
+---
+
+## Bugfix Decision Tree
+
+Error occurs
+│
+▼
+Read logs/errors.log
+│
+├── Entry found → go to Step 2
+│
+└── No entry → add logging first, reproduce error, then fix
+│
+▼
+Check docs/learnings.md
+│
+├── Known issue → apply fix directly
+│
+└── New issue → isolate → fix → document
+
+---
+
+## Common Bug Patterns
+
+| Symptom | Likely Cause | Where to Look |
+|---------|-------------|---------------|
+| Function returns null unexpectedly | Missing null check on input | The function's first few lines |
+| Supabase returns empty data | RLS policy blocking query | Supabase Dashboard → Policies |
+| Auth token errors | Session not refreshed | auth handler file |
+| Test passes locally, fails in CI | Env var missing in CI | .env setup + CI config |
+| Infinite re-render in React | useEffect dependency missing | The specific component file |
+| Type error at runtime | TypeScript type not enforced at boundary | Input validation of the function |
+
+---
+
+## What NOT to Do
+- Do not open the entire codebase to find the bug
+- Do not fix multiple bugs in one session without separate commits
+- Do not refactor while fixing — fix first, refactor separately
+- Do not skip updating the test file
+- Do not push to GitHub
+- Do not chain fixes — one bug, one fix, one commit

docs/workflows/feature.md

@@ -0,0 +1,121 @@
+# Workflow — Building a New Feature
+
+## Purpose
+Read this file every time you start building a new feature.
+Follow steps in order. Do not skip any step.
+
+---
+
+## Step 1 — Understand Before Coding
+- [ ] Read the current phase prompt from `prompts/phase-X.md`
+- [ ] Read `docs/progress.md` to confirm what is already done
+- [ ] Read `docs/architecture.md` to understand existing structure
+- [ ] Identify the exact files you will create or modify
+- [ ] List all edge cases before writing any code
+
+---
+
+## Step 2 — Plan the Feature
+State this out loud before coding:
+
+Feature: [name]
+Files to create: [list]
+Files to modify: [list]
+DB changes needed: yes/no
+Edge cases: [list]
+Tests needed: [list]
+
+---
+
+## Step 3 — DB Changes First (if needed)
+- [ ] Write migration file before any application code
+- [ ] Enable RLS on every new table
+- [ ] Write RLS policies in the migration file
+- [ ] Run `supabase db push` to apply
+- [ ] Confirm in dashboard or via `supabase migration list`
+- [ ] Reference `docs/deployment.md` for exact commands
+
+---
+
+## Step 4 — Write the Code
+- [ ] Create or modify only the files identified in Step 2
+- [ ] Add error handling to every function — follow `docs/debugging.md`
+- [ ] No function should silently fail
+- [ ] Handle all edge cases identified in Step 1
+- [ ] No hardcoded values — use env vars or constants file
+- [ ] No unused imports or dead code
+
+---
+
+## Step 5 — Write Tests Immediately
+- [ ] Create test file at `tests/unit/` or `tests/integration/`
+- [ ] Follow naming convention from `docs/testing.md`
+- [ ] Cover all edge cases from Step 1
+- [ ] Cover happy path + at least 2 failure paths per function
+- [ ] Reference `.claude/skills/testing.md` for reusable patterns
+
+---
+
+## Step 6 — Run Tests
+```bash
+# Run only this feature's tests first
+npm test -- tests/unit/[feature-name].test.ts 2>&1 | tee logs/test.log
+
+# If passing, run full suite
+bash scripts/test.sh
+```
+- [ ] All tests pass before moving forward
+- [ ] If a test fails — read `logs/test.log`, fix the specific function only
+
+---
+
+## Step 7 — Self Review Checklist
+Before declaring feature done:
+- [ ] Error handling in place for every function
+- [ ] No console.log left in code (only console.error with format)
+- [ ] All edge cases handled
+- [ ] Tests written and passing
+- [ ] No new files created outside the plan in Step 2
+- [ ] DB migration applied and confirmed
+- [ ] RLS policies applied if new table was created
+
+---
+
+## Step 8 — Update Docs
+- [ ] Add one-liner to `docs/progress.md`
+- [ ] Append one line to `session/phase-log.md`
+- [ ] Update `session/summary.md` with what was done
+- [ ] If any failure or workaround occurred → add to `docs/learnings.md`
+- [ ] If architecture changed → update `docs/architecture.md`
+
+---
+
+## Step 9 — Git Commit Message
+Provide one-liner commit message in this format:
+
+feat([scope]): [what was done in plain english]
+Examples:
+feat(auth): add email login with session handling
+feat(dashboard): add user profile fetch with error handling
+feat(db): add users table migration with RLS policies
+
+**Do NOT push to GitHub. Hand the message to the user.**
+
+---
+
+## Step 10 — Confirm with User
+- [ ] Show user what was built
+- [ ] Show test results
+- [ ] Show commit message
+- [ ] Ask: "Ready to move to next feature or phase?"
+- [ ] Do NOT proceed until user confirms
+
+---
+
+## What NOT to Do
+- Do not write tests after all features are done
+- Do not modify files outside the plan without flagging it
+- Do not proceed to next feature if current tests are failing
+- Do not push to GitHub
+- Do not skip the docs update in Step 8
+- Do not start next phase without user confirmation

docs/workflows/refactor.md

@@ -0,0 +1,222 @@
+# Workflow — Refactoring Code
+
+## Purpose
+Read this file every time you need to refactor existing code.
+Refactoring means improving structure without changing behaviour.
+If behaviour changes — that is a feature, not a refactor.
+
+---
+
+## Core Principle
+**Tests must pass before AND after every refactor.**
+If tests fail after refactor — you changed behaviour. Revert and retry.
+Never refactor and fix a bug in the same commit.
+
+---
+
+## Step 1 — Confirm Refactor Scope
+Before touching any code, state this out loud:
+
+Refactor target: [file or function]
+Reason for refactor: [why this needs to change]
+Behaviour change: none
+Files I will touch: [exact list]
+Files I will NOT touch: [everything else]
+
+- [ ] Confirm with user that this refactor is needed now
+- [ ] Confirm all current tests pass before starting:
+```bash
+bash scripts/test.sh
+```
+- [ ] Do not proceed if any test is currently failing
+
+---
+
+## Step 2 — Identify What to Refactor
+Valid reasons to refactor:
+- [ ] Duplicate logic across multiple functions
+- [ ] Function doing more than one thing
+- [ ] Deeply nested conditionals reducing readability
+- [ ] Magic numbers or hardcoded strings
+- [ ] Missing or inconsistent error handling format
+- [ ] Inconsistent naming conventions
+- [ ] Dead code or unused imports
+
+Not valid reasons:
+- "It looks messy" without a specific structural problem
+- Preference for a different syntax that does the same thing
+- Rewriting working code during a bug fix session
+
+---
+
+## Step 3 — Refactor in Small Steps
+- [ ] Change one thing at a time
+- [ ] Run tests after each individual change
+- [ ] Do not batch multiple refactors into one step
+- [ ] Keep original logic visible until new logic is confirmed working
+
+### Order of operations:
+
+Extract repeated logic into a shared utility function
+Simplify conditionals (early returns over nested if/else)
+Rename for clarity (variables, functions)
+Remove dead code and unused imports
+Standardise error handling format per docs/debugging.md
+
+---
+
+## Step 4 — Run Tests After Every Change
+```bash
+# After each individual change
+npm test -- tests/unit/[affected-file].test.ts 2>&1 | tee logs/test.log
+
+# After all changes complete
+bash scripts/test.sh
+```
+- [ ] Every test that passed before must still pass
+- [ ] If a test fails → revert the last change, do not chain fixes
+
+---
+
+## Step 5 — Update Tests if Needed
+Refactoring may require test updates only in these cases:
+- [ ] A function was renamed → update test description and import
+- [ ] A function was split into two → write tests for both
+- [ ] A utility was extracted → write a unit test for the utility
+
+Do NOT update tests to make them pass after a refactor.
+If a test fails after refactor → the refactor changed behaviour → revert.
+
+---
+
+## Step 6 — Self Review Checklist
+Before declaring refactor done:
+- [ ] Behaviour is identical before and after
+- [ ] All tests pass
+- [ ] No new files created outside the plan in Step 1
+- [ ] Error handling format matches `docs/debugging.md`
+- [ ] No console.log left in code
+- [ ] No dead code or unused imports remain
+- [ ] No hardcoded values introduced
+
+---
+
+## Step 7 — Update Docs
+- [ ] Update `docs/architecture.md` if structure changed
+- [ ] Add one-liner to `docs/progress.md`
+- [ ] Append one line to `session/phase-log.md`
+- [ ] Update `session/summary.md`
+- [ ] If a pattern was discovered that saves time → add to `docs/learnings.md`
+
+---
+
+## Step 8 — Git Commit Message
+Provide one-liner commit message in this format:
+
+refactor([scope]): [what was improved and how]
+Examples:
+refactor(auth): extract session validation into shared utility
+refactor(dashboard): replace nested conditionals with early returns
+refactor(db): standardise error handling across all supabase queries
+refactor(utils): remove dead code and unused imports from helpers
+
+**Do NOT push to GitHub. Hand the message to the user.**
+
+---
+
+## Step 9 — Confirm with User
+- [ ] Show exactly what changed and in which files
+- [ ] Show before/after for key changes
+- [ ] Show test results confirming no behaviour change
+- [ ] Show commit message
+- [ ] Ask: "Refactor complete — ready to continue?"
+- [ ] Do NOT proceed until user confirms
+
+---
+
+## Refactor Decision Tree
+
+Refactor needed?
+│
+▼
+All tests passing?
+│
+├── No → fix failing tests first, then refactor
+│
+└── Yes → confirm scope → refactor one thing at a time
+│
+▼
+Run tests after each change
+│
+├── Pass → continue next change
+│
+└── Fail → revert last change
+→ reassess scope
+→ do not chain fixes
+
+---
+
+## Refactor Patterns
+
+### Extract repeated logic
+```typescript
+// Before — same null check in 3 functions
+if (!userId || userId === '') return null
+
+// After — shared utility
+function isValidId(id: string | null | undefined): boolean {
+  return !!id && id.trim() !== ''
+}
+```
+
+### Early returns over nested conditionals
+```typescript
+// Before
+function processUser(user: User | null) {
+  if (user) {
+    if (user.isActive) {
+      if (user.hasProfile) {
+        return user.profile
+      }
+    }
+  }
+  return null
+}
+
+// After
+function processUser(user: User | null) {
+  if (!user) return null
+  if (!user.isActive) return null
+  if (!user.hasProfile) return null
+  return user.profile
+}
+```
+
+### Standardise error handling
+```typescript
+// Before — inconsistent
+try {
+  ...
+} catch (e) {
+  console.log(e)  // wrong
+}
+
+// After — per docs/debugging.md
+try {
+  ...
+} catch (err) {
+  handleError(err, 'lib/users.ts', 'processUser')
+  return null
+}
+```
+
+---
+
+## What NOT to Do
+- Do not refactor and fix a bug in the same commit
+- Do not refactor files not listed in Step 1
+- Do not update tests to force them to pass after refactor
+- Do not batch all refactors into one large change
+- Do not refactor during a feature build session
+- Do not push to GitHub
+- Do not start a refactor if any test is currently failing

prompts/phase-0.md

@@ -0,0 +1,228 @@
+# Phase 0 — Critic Quality Gate
+> Paste this entire prompt into a fresh Claude Code session. Do not proceed to Phase 1 until the gate check at the bottom passes.
+
+---
+
+You are helping me build a multi-agent RL environment called the "Viral Script Debugging Engine" for the Meta × OpenEnv Hackathon. Before any environment code is written, we need to validate that the Critic agent produces high-quality, adversarial output — because the entire RL loop depends on it.
+
+**Project context:**
+- The system trains an LLM (the Arbitrator) via GRPO to decide which script improvements to make
+- A Critic agent attacks creator scripts with specific, falsifiable claims
+- A Defender agent argues for what should be preserved
+- The Arbitrator (RL-trained model) decides which critique to act on each step
+- If the Critic produces vague output, the RL signal collapses
+
+**Your task for this phase:** Build the Critic agent and an evaluation harness to validate its output quality before any other code is written.
+
+---
+
+## Directory structure to create
+
+```
+viral_script_engine/
+├── agents/
+│   ├── __init__.py
+│   └── critic.py
+├── data/
+│   ├── test_scripts/
+│   └── golden_fixtures/
+├── evaluation/
+│   ├── __init__.py
+│   └── critic_evaluator.py
+├── scripts/
+│   └── run_critic_gate.py
+├── requirements.txt
+└── README.md
+```
+
+---
+
+## Step 1 — `agents/critic.py`
+
+Implement a `CriticAgent` class:
+
+```python
+class CriticAgent:
+    def __init__(self, model_name: str = "claude-sonnet-4-20250514"):
+        # Use the Anthropic Python SDK
+        
+    def critique(self, script: str, region: str, platform: str, niche: str) -> CritiqueOutput:
+        # Returns a CritiqueOutput dataclass
+```
+
+The `CritiqueOutput` and `CritiqueClaim` Pydantic models must have these exact fields:
+
+```python
+class CritiqueClaim(BaseModel):
+    claim_id: str           # e.g. "C1", "C2"
+    critique_class: str     # one of: "hook_weakness" | "pacing_issue" | "cultural_mismatch" | "cta_buried" | "coherence_break" | "retention_risk"
+    claim_text: str
+    timestamp_range: str    # e.g. "0:00-0:03" or "N/A"
+    evidence: str           # exact quote from the script supporting this claim
+    is_falsifiable: bool
+    severity: str           # "low" | "medium" | "high"
+
+class CritiqueOutput(BaseModel):
+    claims: List[CritiqueClaim]
+    overall_severity: str
+    raw_response: str
+```
+
+**System prompt to use (exact):**
+```
+You are an expert social media content critic specialising in short-form video scripts for Reels and YouTube Shorts. Your job is to find specific, real problems in creator scripts — not vague feedback.
+
+RULES:
+1. Every claim must cite a specific part of the script (quote it or reference the timestamp range)
+2. Every claim must be falsifiable — a human editor must be able to verify it by re-reading the script
+3. Never say "the hook is weak" — say "the hook at 0:00-0:03 promises [X] but the script delivers [Y] at 0:22, by which time most viewers have already dropped off"
+4. Focus on the 6 critique classes: hook_weakness, pacing_issue, cultural_mismatch, cta_buried, coherence_break, retention_risk
+5. Produce between 3 and 6 claims per script. No more, no less.
+6. For each claim, assign a timestamp range if the issue is locatable in the script. Use "N/A" only if it's a structural issue spanning the whole script.
+
+OUTPUT FORMAT (respond ONLY with valid JSON, no markdown, no preamble):
+{
+  "claims": [
+    {
+      "claim_id": "C1",
+      "critique_class": "hook_weakness",
+      "claim_text": "...",
+      "timestamp_range": "0:00-0:03",
+      "evidence": "exact quote from script",
+      "is_falsifiable": true,
+      "severity": "high"
+    }
+  ],
+  "overall_severity": "high"
+}
+```
+
+User prompt format:
+```
+SCRIPT TO CRITIQUE:
+{script}
+
+TARGET REGION: {region}
+PLATFORM: {platform}
+NICHE: {niche}
+
+Produce your critique now.
+```
+
+If JSON parsing fails, retry once with a stricter prompt. If it fails twice, raise `CriticParseError`.
+
+---
+
+## Step 2 — `data/test_scripts/scripts.json`
+
+Create 10 realistic 60–90 second Reel/Shorts scripts saved as a JSON array. Distribution:
+- S01–S03: Mumbai Gen Z (finance, fashion, tech)
+- S04–S06: Tier-2 Hindi belt (agriculture, small business, local culture)
+- S07–S08: Pan-India English (startup advice, productivity)
+- S09–S10: Hinglish (mixed Hindi-English)
+
+Each entry:
+```json
+{
+  "script_id": "S01",
+  "region": "Mumbai Gen Z",
+  "platform": "Reels",
+  "niche": "personal finance",
+  "script_text": "...(100-200 words)...",
+  "known_flaws": ["buried_hook", "no_cta"]
+}
+```
+
+S01–S04 should have **obvious** single flaws. S05–S07 should have **subtle** flaws. S08–S10 should have **conflicting** issues where fixing one hurts another. Do not make all scripts bad in the same way.
+
+---
+
+## Step 3 — `evaluation/critic_evaluator.py`
+
+```python
+class CriticEvaluator:
+    def evaluate(self, output: CritiqueOutput, script_text: str) -> EvaluationResult:
+        pass
+
+    def batch_evaluate(self, results: List[Tuple[CritiqueOutput, str]]) -> BatchEvaluationResult:
+        pass
+```
+
+`EvaluationResult` fields:
+- `claim_count: int` — must be 3–6 to pass
+- `specificity_score: float` — fraction of claims where `evidence` is a substring of the script (use substring match)
+- `falsifiability_score: float` — fraction of claims with `is_falsifiable=True`
+- `timestamp_coverage: float` — fraction of claims with a non-"N/A" timestamp_range
+- `critique_class_diversity: float` — unique critique_classes / 6
+- `passes_gate: bool` — True if: `claim_count >= 3 AND specificity_score >= 0.6 AND falsifiability_score >= 0.7`
+
+`BatchEvaluationResult` fields:
+- `pass_count: int`
+- `pass_rate: float`
+- `passes_overall_gate: bool` — True if `pass_rate >= 0.8`
+- `per_script_results: List[EvaluationResult]`
+- `failing_scripts: List[str]`
+
+The evaluator must be purely rule-based — no LLM calls.
+
+---
+
+## Step 4 — `scripts/run_critic_gate.py`
+
+CLI that:
+1. Loads all 10 scripts from `data/test_scripts/scripts.json`
+2. Runs CriticAgent on each
+3. Runs CriticEvaluator on each result
+4. Prints a per-script pass/fail report using `rich`
+5. Prints overall GATE PASS or GATE FAIL
+6. If gate passes: saves all outputs as JSON to `data/golden_fixtures/fixture_S01.json` etc.
+7. If gate fails: prints which scripts failed and which scores were below threshold
+
+Flags:
+- `--max-retries 3`: retry failed scripts up to N times with a tighter prompt
+- `--dry-run`: run only first 2 scripts
+
+---
+
+## Step 5 — `requirements.txt`
+
+```
+anthropic>=0.40.0
+sentence-transformers>=2.7.0
+numpy>=1.26.0
+pydantic>=2.0.0
+python-dotenv>=1.0.0
+rich>=13.0.0
+pytest>=8.0.0
+```
+
+---
+
+## Step 6 — `tests/test_critic.py`
+
+- Test `CritiqueOutput` parses correctly from a mock LLM JSON response
+- Test `EvaluationResult` correctly identifies a passing vs failing critique
+- Test CLI exits with code 1 if gate fails, 0 if gate passes
+- Mock all Anthropic API calls — no real API calls in tests
+
+---
+
+## Constraints
+
+- Use the Anthropic Python SDK only (not OpenAI)
+- Store API key in `.env`, load with `python-dotenv`
+- All models use Pydantic for validation
+- Evaluator has zero LLM calls
+- Use `rich` for all console output (progress bars, coloured pass/fail)
+- All JSON outputs pretty-printed with `indent=2`
+
+---
+
+## Gate check
+
+Run:
+```
+python scripts/run_critic_gate.py --dry-run
+```
+
+Must print `PHASE 0 GATE: PASS` when 8/10 scripts produce ≥3 specific, timestamped, falsifiable claims. Do not open Phase 1 until this passes.

prompts/phase-1.md

@@ -0,0 +1,285 @@
+# Phase 1 — OpenEnv Scaffold + R1/R2 Rewards
+> Paste this entire prompt into a fresh Claude Code session. Phase 0 must be complete and golden fixtures saved before starting this phase.
+
+---
+
+Phase 0 is complete. The Critic agent is validated and all golden fixtures are saved in `data/golden_fixtures/`. Now build the core OpenEnv environment with two reward signals and get a complete dummy episode running end-to-end.
+
+**Current state:**
+- `agents/critic.py` — CriticAgent working and validated
+- `data/golden_fixtures/` — 10 validated critic outputs as JSON
+- `data/test_scripts/scripts.json` — 10 test scripts
+
+---
+
+## New files to create
+
+```
+viral_script_engine/
+├── environment/
+│   ├── __init__.py
+│   ├── env.py
+│   ├── actions.py
+│   ├── observations.py
+│   └── episode_state.py
+├── rewards/
+│   ├── __init__.py
+│   ├── base.py
+│   ├── r1_hook_strength.py
+│   ├── r2_coherence.py
+│   └── reward_aggregator.py
+├── agents/
+│   └── rewriter.py          # NEW — do not modify critic.py
+├── tests/
+│   ├── test_environment.py
+│   └── test_rewards.py
+└── scripts/
+    └── run_dummy_episode.py
+```
+
+**The environment must follow OpenEnv's Gymnasium-compatible API exactly:**
+- `reset()` → `(observation: dict, info: dict)`
+- `step(action)` → `(observation: dict, reward: float, terminated: bool, truncated: bool, info: dict)`
+- `state()` → full current state dict
+
+---
+
+## Step 1 — `environment/actions.py`
+
+```python
+from enum import Enum
+from pydantic import BaseModel
+
+class ActionType(str, Enum):
+    HOOK_REWRITE = "hook_rewrite"
+    SECTION_REORDER = "section_reorder"
+    CULTURAL_REF_SUB = "cultural_ref_sub"
+    CTA_PLACEMENT = "cta_placement"
+
+class ArbitratorAction(BaseModel):
+    action_type: ActionType
+    target_section: str      # "hook" | "body" | "cta" | "full"
+    instruction: str         # natural language instruction to the Rewriter
+    critique_claim_id: str   # which CritiqueClaim this responds to, e.g. "C2"
+    reasoning: str           # why this action was chosen (used in demo and logs)
+```
+
+---
+
+## Step 2 — `environment/observations.py`
+
+```python
+class RewardComponents(BaseModel):
+    r1_hook_strength: Optional[float] = None
+    r2_coherence: Optional[float] = None
+    r3_cultural_alignment: Optional[float] = None
+    r4_debate_resolution: Optional[float] = None
+    r5_defender_preservation: Optional[float] = None
+    r6_retention_proxy: Optional[float] = None
+    anti_gaming_penalty: float = 0.0
+    total: float = 0.0
+
+    def compute_total(self) -> float:
+        # Weights: R1=0.25, R2=0.20, R3=0.20, R4=0.20, R5=0.15
+        # Sum only non-None components, normalise weights to sum to 1.0
+        # Subtract anti_gaming_penalty, clip to [0, 1]
+
+class DebateRound(BaseModel):
+    step_num: int
+    critic_claims: List[CritiqueClaim]
+    defender_response: Optional[Any] = None   # DefenderOutput added in Phase 2
+    arbitrator_action: Optional[ArbitratorAction] = None
+    rewrite_diff: Optional[str] = None        # unified diff string
+    reward_components: Optional[RewardComponents] = None
+
+class Observation(BaseModel):
+    current_script: str
+    original_script: str
+    region: str
+    platform: str
+    niche: str
+    step_num: int
+    max_steps: int
+    debate_history: List[DebateRound]
+    reward_components: RewardComponents
+    difficulty_level: str   # "easy" | "medium" | "hard" | "self_generated"
+    episode_id: str         # UUID
+```
+
+---
+
+## Step 3 — `rewards/r1_hook_strength.py`
+
+Fully rule-based — zero LLM calls. Scores the first 3 sentences or ~50 words (whichever is shorter).
+
+**5 checks, each worth 0.2:**
+
+1. **Promise check** — hook contains a concrete promise or specific claim. Look for: numbers, "how to", "why", "what happens when", "I made X". Fail: generic openers like "Hey guys", "Welcome back", "Today we're talking about".
+
+2. **Curiosity gap check** — hook creates unresolved tension. Look for: question structures, "but here's the thing", "most people don't know", "the secret is". Fail: hook that immediately resolves the tension in the same sentence.
+
+3. **Specificity check** — at least one specific number, proper noun, or concrete detail. Look for: digit sequences, proper nouns, specific product/place names.
+
+4. **Front-loading check** — first sentence contains at least 2 of the above signals.
+
+5. **Anti-filler check** — avoids these dead openers (case-insensitive): `["hey guys", "welcome back", "today i want to", "so today", "in this video", "what's up everyone", "hey everyone", "guys today", "hello everyone", "so basically"]`
+
+`score = checks_passed / 5`, clipped to [0, 1].
+
+Return a `HookRewardResult` with: `score`, `checks_passed`, `check_details: dict`.
+
+---
+
+## Step 4 — `rewards/r2_coherence.py`
+
+Uses `sentence-transformers all-MiniLM-L6-v2`. Cache embeddings by `hash(text)`.
+
+Score mapping from raw cosine similarity:
+- `< 0.65` → `0.0` (drifted too far from creator intent)
+- `0.65–0.80` → linearly map to `0.0–0.5`
+- `0.80–0.95` → linearly map to `0.5–1.0`
+- `> 0.95` → `0.8` (barely changed — penalise inaction)
+
+Return a `CoherenceRewardResult` with: `score`, `raw_similarity`, `interpretation: str`.
+
+---
+
+## Step 5 — `rewards/reward_aggregator.py`
+
+```python
+class RewardAggregator:
+    WEIGHTS = {"r1": 0.25, "r2": 0.20, "r3": 0.20, "r4": 0.20, "r5": 0.15}
+
+    def compute(
+        self,
+        components: RewardComponents,
+        episode_start_components: RewardComponents,
+        action_history: List[ActionType],
+    ) -> RewardComponents:
+```
+
+**Anti-gaming rule 1 — Catastrophic drop:**
+For each reward component not None in both current and episode_start: if `current < episode_start - 0.2`, set total = 0.0 and log which component triggered it.
+
+**Anti-gaming rule 2 — Action diversity:**
+If the last 3 entries in `action_history` are all the same `ActionType`, subtract 0.15 from total before clipping.
+
+Always clip final total to [0, 1]. Set `components.anti_gaming_penalty` to total deduction applied.
+
+---
+
+## Step 6 — `agents/rewriter.py`
+
+```python
+class RewriterAgent:
+    def __init__(self, model_name: str = "claude-sonnet-4-20250514"):
+        pass
+
+    def rewrite(self, current_script: str, action: ArbitratorAction) -> RewriteResult:
+        pass
+```
+
+System prompt: "You are a professional script editor for short-form social media video. Apply ONLY the instruction given. Do not make any other changes. Do not add new ideas. Do not change the creator's voice or regional language patterns. Return ONLY the rewritten script text, no commentary."
+
+User prompt includes: `current_script`, `action.action_type`, `action.instruction`, `action.target_section`.
+
+`RewriteResult` has: `rewritten_script`, `diff` (unified diff string), `word_count_delta: int`.
+
+---
+
+## Step 7 — `environment/env.py`
+
+```python
+from openenv import Environment
+
+class ViralScriptEnv(Environment):
+    DIFFICULTY_LEVELS = ["easy", "medium", "hard", "self_generated"]
+
+    def __init__(
+        self,
+        scripts_path: str = "data/test_scripts/scripts.json",
+        max_steps: int = 5,
+        difficulty: str = "easy",
+        use_anti_gaming: bool = True,
+    ):
+        # Script tiers: easy=S01-S04, medium=S05-S07, hard=S08-S10
+        # Init: CriticAgent, RewriterAgent, RewardAggregator, HookStrengthReward, CoherenceReward
+        # R3-R5 are None until Phase 2
+
+    def reset(self, seed=None, options=None) -> Tuple[dict, dict]:
+        # 1. Sample script from current difficulty tier
+        # 2. Reset all debate state
+        # 3. Compute initial R1 and R2 on unmodified script → save as episode_start_rewards
+        # 4. Return (observation_dict, info_dict)
+
+    def step(self, action: dict) -> Tuple[dict, float, bool, bool, dict]:
+        # 1. Parse action dict → ArbitratorAction
+        # 2. Run Critic on current script
+        # 3. [Defender: skip in Phase 1, wire in Phase 2]
+        # 4. Run Rewriter with the action → new script
+        # 5. Compute R1, R2 on new script
+        # 6. Run RewardAggregator (anti-gaming checks applied)
+        # 7. Append DebateRound to debate_history
+        # 8. Increment step counter
+        # 9. terminated if step_num >= max_steps OR total_reward >= 0.9
+        # 10. info_dict must include: reward_components, anti_gaming_triggered, penalty_reason
+
+    def state(self) -> dict:
+        # Full JSON-serialisable state: current_script, original_script, debate_history,
+        # reward_components, step_num, difficulty_level, episode_id
+```
+
+---
+
+## Step 8 — `scripts/run_dummy_episode.py`
+
+```
+python scripts/run_dummy_episode.py --difficulty easy --steps 3 --verbose
+```
+
+1. Instantiate `ViralScriptEnv`
+2. Call `reset()`
+3. Each step: sample a random `ActionType`, construct a minimal valid `ArbitratorAction`, call `step()`
+4. Print per-step: script diff, reward components, any anti-gaming penalties (use `rich` panels/tables)
+5. At end: print final reward, R1, R2
+6. Save full episode log to `logs/episode_<id>.json`
+
+Output must be readable to a non-technical judge watching the demo.
+
+---
+
+## Step 9 — Tests
+
+**`tests/test_environment.py`:**
+- `reset()` returns a valid observation dict
+- `step()` with a valid action completes without error
+- `step()` increments `step_num` correctly
+- Anti-gaming penalty fires when same action repeated 3 times
+- Episode terminates at `max_steps`
+- Reward is clipped to [0, 1]
+- Mock all LLM calls using fixtures from `data/golden_fixtures/`
+
+**`tests/test_rewards.py`:**
+- R1 on 5 hand-crafted hooks: 2 score >0.8, 2 score <0.3, 1 is edge case ~0.5
+- R2 with identical strings → 0.8 (the >0.95 penalty case)
+- R2 with completely different strings → 0.0 (below 0.65 threshold)
+- RewardAggregator catastrophic drop penalty zeroes reward correctly
+- RewardAggregator diversity penalty fires on 3 identical consecutive actions
+
+---
+
+## Gate check
+
+Run:
+```
+python scripts/run_dummy_episode.py --difficulty easy --steps 3 --verbose
+```
+
+The final line must print:
+```
+PHASE 1 GATE: PASS
+```
+
+Conditions: (a) episode completed without error, (b) R1 and R2 are non-null in final state, (c) episode log saved to `logs/`.
+
+Also deploy this version to HF Spaces immediately as an early checkpoint before moving to Phase 2.

prompts/phase-2.md

@@ -0,0 +1,266 @@
+# Phase 2 — Defender Agent + R3/R4/R5 + Anti-Gaming + Baseline
+> Paste this entire prompt into a fresh Claude Code session. Phase 1 must be complete (dummy episode running, R1/R2 working) before starting.
+
+---
+
+Phase 1 is complete. The environment scaffold runs and dummy episodes complete end-to-end. Now complete the full agent loop with all 5 reward signals, bake in the anti-gaming protections with full logging, and record the pre-training baseline.
+
+**Current state:**
+- `environment/env.py` — ViralScriptEnv working with R1+R2
+- `agents/critic.py` — validated CriticAgent
+- `agents/rewriter.py` — RewriterAgent
+- Defender slot exists in Observation but is still `None`
+
+---
+
+## Step 1 — `agents/defender.py`
+
+```python
+class DefenderOutput(BaseModel):
+    core_strength: str              # single most important thing to preserve
+    core_strength_quote: str        # exact verbatim quote from the script
+    defense_argument: str           # why this should not be changed
+    flagged_critic_claims: List[str]    # claim_ids the Defender believes are overcorrections
+    regional_voice_elements: List[str]  # phrases/references that are intentionally regional
+
+class DefenderAgent:
+    def __init__(self, model_name: str = "claude-sonnet-4-20250514"):
+        pass
+
+    def defend(
+        self,
+        script: str,
+        critic_claims: List[CritiqueClaim],
+        region: str,
+        platform: str,
+    ) -> DefenderOutput:
+        pass
+```
+
+**System prompt (exact):**
+```
+You are a script defender for short-form video content. Your job is NOT to say the script is perfect.
+Your job is to identify what is genuinely working — and protect it from being edited away.
+
+Specifically:
+1. Find the single most powerful element of the script. Quote it exactly.
+2. Explain why a viewer would respond positively to this element.
+3. Review the Critic's claims. Flag any that would destroy the script's core strength or strip its regional authenticity if acted on.
+4. List any phrases, idioms, or references that are intentionally regional — these must not be "corrected" away.
+
+OUTPUT (JSON only, no preamble):
+{
+  "core_strength": "one sentence describing the strongest element",
+  "core_strength_quote": "exact verbatim quote from the script",
+  "defense_argument": "why this element should be preserved",
+  "flagged_critic_claims": ["C2", "C3"],
+  "regional_voice_elements": ["specific phrase 1", "specific phrase 2"]
+}
+```
+
+---
+
+## Step 2 — `rewards/r3_cultural_alignment.py`
+
+Rule-based, zero LLM calls. Uses a JSON knowledge base.
+
+```python
+class CulturalAlignmentReward:
+    def __init__(self, knowledge_base_path: str = "data/cultural_kb.json"):
+        pass
+
+    def score(self, script: str, region: str) -> CulturalRewardResult:
+        # score = (valid_refs_found + correct_idioms_found
+        #          - invalid_signals_found - anachronistic_signals_found)
+        #         / max(total_valid_refs + total_idioms, 1)
+        # clip to [0, 1]
+```
+
+Create `data/cultural_kb.json` with at least 15 entries per category per region for:
+
+**Mumbai Gen Z:**
+- `valid_refs`: Bandra, CSMT, dabba, auto, local train, startup scene, Zomato, Swiggy, IPL, Bollywood 2020s
+- `invalid_signals`: outdated slang pre-2015
+- `correct_idioms`: "ek dum solid", "full on", "kya scene hai", Hinglish patterns
+
+**Tier-2 Hindi Belt:**
+- `valid_refs`: kirana store, mandap, jugaad, sabzi mandi, panchayat, mela, dal-chawal
+- `invalid_signals`: metro-centric language, startup jargon
+- `correct_idioms`: Hindi-dominant mixed phrases
+
+**Pan-India English:** minimal constraints; penalise overly regional without context.
+
+**Hinglish:** reward balanced Hindi-English mixing; penalise fully formal English.
+
+---
+
+## Step 3 — `rewards/r4_debate_resolution.py`
+
+Re-runs the Critic on the new script after each rewrite. Checks whether the specific claim the Arbitrator targeted still appears.
+
+```python
+class DebateResolutionReward:
+    def __init__(self, critic_agent: CriticAgent):
+        self.critic = critic_agent
+
+    def score(
+        self,
+        new_script: str,
+        original_action: ArbitratorAction,
+        original_claim: CritiqueClaim,
+        region: str,
+        platform: str,
+        niche: str,
+    ) -> DebateResolutionResult:
+        # Re-run critic on new_script
+        # A claim is "resolved" if new critique has NO claim of the same critique_class
+        #   targeting the same timestamp_range (±5 seconds)
+        # OR the new claim for that section has severity "low" (down from "medium"/"high")
+        # Score: 1.0=resolved, 0.5=partially resolved (severity reduced), 0.0=claim persists
+```
+
+---
+
+## Step 4 — `rewards/r5_defender_preservation.py`
+
+Uses `sentence-transformers all-MiniLM-L6-v2` (same model as R2 — reuse the loaded instance).
+
+```python
+class DefenderPreservationReward:
+    def score(self, defender_output: DefenderOutput, rewritten_script: str) -> DefenderPreservationResult:
+        # Chunk rewritten_script into sentences
+        # Compute cosine_similarity(embed(core_strength_quote), embed(sentence)) for each sentence
+        # Take the max similarity across all sentences
+        # Score mapping:
+        #   max_similarity >= 0.85 → 1.0
+        #   max_similarity 0.65–0.85 → max_similarity (partial)
+        #   max_similarity < 0.65 → 0.0
+```
+
+---
+
+## Step 5 — Update `environment/env.py`
+
+**Modify `step()`:**
+1. After Critic runs, immediately run Defender on the same script state
+2. Store `DefenderOutput` in the `DebateRound`
+3. After Rewriter executes, compute R3, R4, R5 alongside R1, R2
+4. Pass all 5 to RewardAggregator
+
+**Modify `reset()`:**
+1. Compute baseline R1–R5 on unmodified script at episode start
+2. R4 and R5 will be `None` at reset — handle gracefully in aggregator (skip them in weighted sum)
+
+---
+
+## Step 6 — Update `rewards/reward_aggregator.py`
+
+- Anti-gaming catastrophic drop check must now work across all 5 rewards
+- Normalise weights so available (non-None) rewards always sum to 1.0
+
+Add `AntiGamingLog`:
+
+```python
+class AntiGamingLog(BaseModel):
+    episode_id: str
+    step_num: int
+    triggered: bool
+    rule_triggered: Optional[str]         # "catastrophic_drop" | "action_repetition" | None
+    component_that_dropped: Optional[str] # which reward triggered catastrophic drop
+    penalty_applied: float
+    pre_penalty_total: float
+    post_penalty_total: float
+```
+
+Every `RewardAggregator.compute()` call must return `(RewardComponents, AntiGamingLog)`. Save all `AntiGamingLog` entries in the episode's `info` dict and in the episode log JSON.
+
+---
+
+## Step 7 — `agents/baseline_arbitrator.py`
+
+```python
+class BaselineArbitratorAgent:
+    """
+    Untrained Arbitrator for the pre-training baseline.
+    Uses zero-shot instruction — no chain-of-thought, no few-shot examples.
+    This ensures the comparison is fair: trained model learns through RL, not prompting.
+    """
+
+    SYSTEM_PROMPT = """
+    You are helping improve a short-form video script.
+    You have observed a debate between a Critic and a Defender about the script.
+    Choose ONE action to take to improve the script.
+
+    Available actions: hook_rewrite, section_reorder, cultural_ref_sub, cta_placement
+
+    Respond ONLY with valid JSON:
+    {
+      "action_type": "hook_rewrite",
+      "target_section": "hook",
+      "instruction": "specific instruction for the rewriter",
+      "critique_claim_id": "C1",
+      "reasoning": "brief explanation"
+    }
+    """
+
+    def __init__(self, model_name: str = "claude-haiku-4-5-20251001"):
+        # Haiku: cheaper and clearly weaker than trained model
+        pass
+
+    def act(self, observation: dict) -> dict:
+        pass
+```
+
+---
+
+## Step 8 — `scripts/run_baseline.py`
+
+Run 20 full episodes with `BaselineArbitratorAgent`:
+- Episodes 1–8: `difficulty="easy"`
+- Episodes 9–16: `difficulty="medium"`
+- Episodes 17–20: `difficulty="hard"`
+
+Log per episode: episode_id, difficulty, script_id, per-step R1–R5, anti_gaming_triggered, penalty, total reward, final script vs original.
+
+Save to `logs/baseline_results.json`.
+
+Generate `logs/baseline_reward_curves.png`:
+- 2 rows × 3 cols subplots: R1, R2, R3, R4, R5, Total
+- X-axis: episode number (1–20), labelled
+- Y-axis: reward value [0, 1], labelled
+- Title: "Baseline (Untrained) Arbitrator — Pre-Training Reward Curves"
+- `dpi=150`, save as PNG
+- These plots are submitted to judges
+
+Print a `rich` summary table showing mean ± std of each reward across all 20 episodes.
+
+---
+
+## Step 9 — `tests/test_phase2.py`
+
+- `DefenderAgent` parses output correctly from mock LLM response
+- R3 scores correctly on 3 regional vs 3 non-regional hand-crafted scripts
+- R4 correctly identifies resolved vs unresolved claims (mock Critic re-run)
+- R5 scores correctly when `core_strength_quote` is present vs absent in rewrite
+- Anti-gaming catastrophic drop zeroes reward when R2 drops by 0.25
+- Anti-gaming diversity penalty fires on 3× same action
+- `AntiGamingLog` is populated correctly in both triggering and non-triggering cases
+
+---
+
+## Gate check
+
+Run:
+```
+python scripts/run_baseline.py
+```
+
+Must:
+1. Complete all 20 episodes without error
+2. Save `logs/baseline_reward_curves.png`
+3. Print:
+   ```
+   PHASE 2 GATE: PASS — Baseline curves saved. Pre-training mean total reward: X.XX
+   ```
+
+Expected baseline total reward: **0.25–0.55**. If above 0.7, tasks are too easy. If below 0.1, tasks are too hard and RL training will stall — adjust script difficulty before Phase 3.

prompts/phase-3.md

@@ -0,0 +1,250 @@
+# Phase 3 — Curriculum Dataset + GRPO Training
+> Paste this entire prompt into a fresh Claude Code session. Phases 0–2 must be complete, baseline curves saved, before starting.
+
+---
+
+Phases 0–2 are complete. The environment has all 5 rewards, anti-gaming protections are live, and baseline reward curves are saved in `logs/baseline_reward_curves.png`. Now build the curriculum datasets and the GRPO training pipeline.
+
+**The training script must connect to the live OpenEnv environment — not a static dataset.**
+
+---
+
+## Step 1 — `data/curriculum/build_curriculum.py`
+
+Build three curriculum tiers. Each is a JSONL file where each line is one episode config.
+
+**Episode config schema:**
+```json
+{
+  "episode_config_id": "easy_001",
+  "difficulty": "easy",
+  "script_id": "S01",
+  "script_text": "...",
+  "region": "Mumbai Gen Z",
+  "platform": "Reels",
+  "niche": "personal finance",
+  "dominant_flaw": "buried_hook",
+  "expected_critique_class": "hook_weakness",
+  "expected_action": "hook_rewrite",
+  "curriculum_notes": "One obvious flaw. Critic should win immediately. Strong reward signal on step 1."
+}
+```
+
+**Generate:**
+- `data/curriculum/easy_tier.jsonl` — 20 configs (10 from existing scripts + 10 synthetic)
+- `data/curriculum/medium_tier.jsonl` — 15 configs (trade-off scenarios where Critic and Defender both have valid points)
+- `data/curriculum/hard_tier.jsonl` — 10 configs (fixing the top critique damages R3 — explicit conflicts)
+
+**For synthetic scripts**, create `data/curriculum/generate_synthetic_scripts.py`:
+
+Use the Anthropic API with this prompt pattern:
+```
+Generate a realistic 60-90 second Reels script for [niche] targeting [region].
+Intentionally include [flaw_type] as the dominant flaw.
+The flaw should be [easy|medium|hard] to diagnose.
+```
+
+Generate: 10 easy, 5 medium, 5 hard synthetic scripts. Save to `data/curriculum/synthetic_scripts.json`.
+
+---
+
+## Step 2 — `training/rollout_function.py`
+
+This bridges TRL's `GRPOTrainer` to the live OpenEnv environment. It's the most critical file in this phase.
+
+```python
+def build_rollout_fn(env: ViralScriptEnv, max_steps: int = 5):
+    """
+    Returns a function compatible with TRL's GRPOTrainer rollout interface.
+    
+    For each prompt in the batch:
+    1. Parse the episode config embedded in prompt metadata
+    2. Reset the env with that config
+    3. Run the model to generate an action (JSON)
+    4. Execute the action in the env
+    5. Collect the final episode reward
+    
+    Returns: (completions: List[str], rewards: List[float])
+    """
+
+    def rollout_fn(prompts: List[str], model, tokenizer) -> Tuple[List[str], List[float]]:
+        ...
+
+    return rollout_fn
+```
+
+**Prompt format for the Arbitrator model:**
+```
+<|system|>
+You are an expert content strategist acting as an Arbitrator in a script improvement debate.
+You observe a debate between a Critic and Defender about a creator's script.
+You must choose exactly ONE action to improve the script.
+
+AVAILABLE ACTIONS: hook_rewrite | section_reorder | cultural_ref_sub | cta_placement
+
+OUTPUT FORMAT (JSON only):
+{"action_type": "...", "target_section": "...", "instruction": "...", "critique_claim_id": "...", "reasoning": "..."}
+<|end|>
+
+<|user|>
+CURRENT SCRIPT:
+{current_script}
+
+REGION: {region} | PLATFORM: {platform} | NICHE: {niche}
+
+CRITIC CLAIMS:
+{formatted_critic_claims}
+
+DEFENDER RESPONSE:
+Core strength: {core_strength}
+Defense: {defense_argument}
+Flagged claims: {flagged_claims}
+
+CURRENT REWARDS: R1={r1:.2f} R2={r2:.2f} R3={r3} R4={r4} R5={r5}
+STEP: {step_num}/{max_steps}
+
+Choose your action:
+<|end|>
+```
+
+---
+
+## Step 3 — `training/train_grpo.py`
+
+Make this runnable as both a local script and a Colab notebook cell.
+
+```python
+"""
+GRPO Training — Viral Script Debugging Engine
+TRL + Unsloth for memory-efficient training.
+
+Local dry-run:    python training/train_grpo.py --dry-run
+Full training:    python training/train_grpo.py --tier easy,medium --steps 200
+"""
+
+from unsloth import FastLanguageModel
+from trl import GRPOTrainer, GRPOConfig
+
+def load_model(model_name: str, max_seq_length: int = 2048):
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name=model_name,
+        max_seq_length=max_seq_length,
+        dtype=None,          # auto-detect
+        load_in_4bit=True,
+    )
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r=16,
+        target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
+                        "gate_proj", "up_proj", "down_proj"],
+        lora_alpha=16,
+        lora_dropout=0,
+        bias="none",
+        use_gradient_checkpointing="unsloth",
+        random_state=42,
+    )
+    return model, tokenizer
+
+def build_grpo_config(output_dir, num_steps, dry_run) -> GRPOConfig:
+    return GRPOConfig(
+        output_dir=output_dir,
+        num_train_epochs=1,
+        max_steps=5 if dry_run else num_steps,
+        per_device_train_batch_size=1 if dry_run else 4,
+        num_generations=4 if dry_run else 8,
+        gradient_accumulation_steps=4,
+        learning_rate=5e-6,
+        max_grad_norm=0.1,
+        warmup_ratio=0.1,
+        logging_steps=1,
+        save_steps=50,
+        report_to="wandb" if os.getenv("WANDB_API_KEY") else "none",
+        use_vllm=False,
+        temperature=0.8,
+        top_p=0.9,
+        max_new_tokens=256,
+    )
+```
+
+**Model saving — CRITICAL:**
+```python
+# Use save_pretrained_merged — NOT naive upcast from 4-bit
+model.save_pretrained_merged(
+    f"{output_dir}/final_model",
+    tokenizer,
+    save_method="merged_16bit",
+)
+```
+
+**CLI flags:**
+- `--tier` — comma-separated tiers: `easy`, `medium`, `hard`
+- `--steps` — number of training steps (default: 200)
+- `--dry-run` — run 5 steps with batch_size=1 to validate pipeline
+- `--model` — base model (default: `unsloth/Qwen2.5-7B-Instruct-bnb-4bit`)
+- `--output-dir` — checkpoint directory (default: `outputs/checkpoints/`)
+- `--wandb` — enable WandB logging
+
+---
+
+## Step 4 — `training/reward_curves.py`
+
+```python
+def plot_training_curves(
+    baseline_log_path: str = "logs/baseline_results.json",
+    training_log_path: str = "logs/training_results.json",
+    output_path: str = "logs/training_vs_baseline.png",
+):
+    """
+    Judge-facing comparison plot.
+    Layout: 2 rows × 3 cols (R1, R2, R3, R4, R5, Total)
+    
+    Per subplot:
+    - Grey line: baseline reward per episode
+    - Blue line: trained reward per episode
+    - Horizontal dashed line: baseline mean
+    - Both axes labelled
+    
+    Figure title: "Trained vs Untrained Arbitrator — Reward Improvement"
+    Save PNG dpi=150. Also save PDF for README.
+    
+    Print improvement summary:
+      R1: baseline=X.XX → trained=Y.YY (+Z.ZZ)
+      ...
+    """
+```
+
+---
+
+## Step 5 — `training/eval_trained_model.py`
+
+After training: run 20 evaluation episodes with the trained model. Use the same 20 episode configs as the baseline run for a fair comparison. Save to `logs/trained_results.json`. Then call `plot_training_curves()`.
+
+---
+
+## Step 6 — `tests/test_training_pipeline.py`
+
+- `build_training_prompts("easy")` returns non-empty dataset with correct prompt format
+- `rollout_fn` completes one episode given a mock model returning random valid JSON
+- `GRPOConfig` builds without error
+- Model saving path uses `save_pretrained_merged`, not `save_pretrained`
+- `plot_training_curves` generates a PNG file given valid JSON inputs
+
+---
+
+## Gate check
+
+Run:
+```
+python training/train_grpo.py --dry-run
+```
+
+Must:
+1. Complete 5 training steps without error
+2. Print reward values for each step
+3. Show training loop is connected to the live environment (not a static dataset)
+4. Print:
+   ```
+   PHASE 3 GATE: PASS — Dry run complete. Training pipeline connected to live environment.
+   ```
+
+**The full training run happens onsite when compute credits are available. Do not attempt to run it now.**

prompts/phase-4.md

@@ -0,0 +1,214 @@
+# Phase 4 — Critic Escalation Engine (Theme 4: Self-Improvement)
+> Paste this entire prompt into a fresh Claude Code session. Phases 0–3 must be complete and the training dry-run passing before starting.
+
+---
+
+Phases 0–3 are complete. The training pipeline is validated. Now build the self-improvement loop that satisfies Theme 4: a Critic Escalation Engine that generates harder critique challenges automatically as the Arbitrator improves.
+
+This is what separates this submission from a standard RL environment. Every other team builds a fixed task. This environment gets harder as the agent gets better.
+
+---
+
+## Step 1 — `escalation/difficulty_tracker.py`
+
+```python
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+import json
+
+@dataclass
+class CritiqueClassRecord:
+    critique_class: str
+    total_episodes: int = 0
+    resolved_episodes: int = 0       # episodes where R4 >= 0.8
+    consecutive_resolutions: int = 0  # current streak
+    mastery_threshold: int = 3        # consecutive resolutions needed for mastery
+    is_mastered: bool = False
+    avg_r4_score: float = 0.0
+    last_10_r4_scores: List[float] = field(default_factory=list)
+
+class DifficultyTracker:
+    CRITIQUE_CLASSES = [
+        "hook_weakness", "pacing_issue", "cultural_mismatch",
+        "cta_buried", "coherence_break", "retention_risk"
+    ]
+
+    def __init__(self, persistence_path: str = "logs/difficulty_tracker.json"):
+        # Init one CritiqueClassRecord per class
+        # Load from persistence_path if it exists
+
+    def record_episode(self, dominant_critique_class: str, r4_score: float, episode_id: str):
+        """
+        Update the record for the dominant critique class.
+        Resolved = r4_score >= 0.8.
+        Update consecutive_resolutions streak (reset to 0 on failure).
+        Set is_mastered = True at consecutive_resolutions >= mastery_threshold.
+        Save to disk after every update.
+        """
+
+    def get_next_difficulty_class(self) -> str:
+        """
+        Priority:
+        1. If any class is mastered AND a harder version exists from the escalation engine → return it
+        2. Else → class with lowest avg_r4_score that has had >= 3 episodes
+        3. Fallback → "hook_weakness"
+        """
+
+    def get_mastered_classes(self) -> List[str]:
+        return [k for k, v in self.records.items() if v.is_mastered]
+
+    def get_hardest_unsolved_class(self) -> str:
+        # Lowest avg_r4_score among non-mastered classes
+
+    def summary(self) -> dict:
+        # JSON-serialisable summary for logging and demo
+```
+
+---
+
+## Step 2 — `escalation/critic_escalation_engine.py`
+
+```python
+@dataclass
+class EscalatedChallenge:
+    source_class: str           # which mastered class this escalates from
+    script_text: str
+    region: str
+    platform: str
+    dominant_flaw: str
+    conflicting_flaw: str       # the flaw that makes fixing dominant_flaw harder
+    why_its_harder: str         # one sentence
+    optimal_action_order: List[str]
+    trap_action: str            # the action that looks right but leads to worse total reward
+    difficulty_level: str = "self_generated"
+    generated_at: str = ""      # ISO timestamp
+
+class CriticEscalationEngine:
+    def __init__(self, model_name: str = "claude-sonnet-4-20250514"):
+        self.escalated_classes: Dict[str, List[EscalatedChallenge]] = {}
+
+    def escalate(
+        self,
+        mastered_class: str,
+        original_script_example: str,
+        region: str,
+        platform: str,
+    ) -> EscalatedChallenge:
+        """
+        System prompt:
+        You are designing training challenges for an RL agent learning to improve video scripts.
+        The agent has mastered detecting and fixing '{mastered_class}' flaws.
+
+        Generate a harder challenge:
+        1. Create a script with a '{mastered_class}' flaw that is MORE SUBTLE than the example
+        2. Add a CONFLICTING CONSTRAINT: fixing the '{mastered_class}' flaw should create or
+           worsen a different flaw from: {other_classes}
+        3. Difficulty: HARD — agent must learn action ordering, not just action selection
+
+        A challenge is good when: fixing the obvious flaw first leads to WORSE total reward
+        than fixing a less obvious flaw first.
+
+        Return JSON only:
+        {
+          "script_text": "...",
+          "dominant_flaw": "...",
+          "conflicting_flaw": "...",
+          "why_its_harder": "one sentence",
+          "optimal_action_order": ["action1", "action2"],
+          "trap_action": "action that looks correct but degrades total reward"
+        }
+        """
+
+    def get_next_challenge(self, difficulty_tracker: DifficultyTracker) -> Optional[EscalatedChallenge]:
+        # Return next escalated challenge based on mastered classes
+        # Return None if no classes are mastered yet
+```
+
+---
+
+## Step 3 — Wire escalation into `environment/env.py`
+
+**Update `__init__` signature:**
+```python
+def __init__(
+    self,
+    scripts_path: str = "data/test_scripts/scripts.json",
+    max_steps: int = 5,
+    difficulty: str = "easy",
+    use_anti_gaming: bool = True,
+    use_escalation: bool = True,
+    difficulty_tracker: Optional[DifficultyTracker] = None,
+    escalation_engine: Optional[CriticEscalationEngine] = None,
+):
+    # Create new DifficultyTracker / CriticEscalationEngine if not provided
+```
+
+**Update `reset()`:**
+1. After existing reset logic, call `difficulty_tracker.get_mastered_classes()`
+2. If any classes are mastered: call `escalation_engine.get_next_challenge(difficulty_tracker)`
+3. If a challenge is returned: use the escalated script instead of the curriculum script
+4. Set `observation.difficulty_level = "self_generated"`
+5. Log that escalation was used (print + include in info dict)
+
+**Update `step()`:**
+After episode ends (terminated=True):
+1. Determine `dominant_critique_class` = the critique_class with the most claims in the first Critic output of this episode
+2. Call `difficulty_tracker.record_episode(dominant_critique_class, r4_score, episode_id)`
+
+---
+
+## Step 4 — `scripts/run_escalation_demo.py`
+
+```
+python scripts/run_escalation_demo.py --episodes 50 --verbose
+python scripts/run_escalation_demo.py --episodes 10 --verbose   # for gate check
+```
+
+Behaviour:
+1. Run N episodes with the trained model (from `outputs/checkpoints/final_model`)
+2. After each episode: log `difficulty_tracker.summary()`
+3. Print clearly when mastery is achieved for a class and when escalation first activates
+4. At the end, print a "difficulty progression" report:
+   - Which classes were mastered and at which episode
+   - How many escalated challenges were generated
+   - Whether escalated challenges produced lower R4 scores than the original class (proof escalation is working)
+
+Save progression to `logs/escalation_progression.json`.
+
+**Generate `logs/escalation_chart.png`:**
+- X-axis: episode number, labelled
+- Y-axis (left): difficulty score (1=easy, 2=medium, 3=hard, 4=self_generated)
+- Y-axis (right): R4 score per episode
+- Both overlaid on same plot
+- Title: "Difficulty Progression — Self-Generated Curriculum"
+- This chart is your Theme 4 story for judges
+
+---
+
+## Step 5 — `tests/test_escalation.py`
+
+- `DifficultyTracker.record_episode()` correctly tracks consecutive resolutions
+- Mastery triggers at exactly 3 consecutive resolutions, not 2
+- Mastery resets if agent fails (r4 < 0.8) on a subsequent episode
+- `CriticEscalationEngine.escalate()` returns valid `EscalatedChallenge` from mock LLM
+- `env.reset()` uses escalated script when mastery is achieved (integration test with mocked escalation engine)
+- Difficulty progression JSON is saved correctly
+
+---
+
+## Gate check
+
+Run:
+```
+python scripts/run_escalation_demo.py --episodes 10 --verbose
+```
+
+Must:
+1. Complete 10 episodes without error
+2. Show `DifficultyTracker` updating after each episode
+3. Print escalation stats at the end
+4. Save `logs/escalation_chart.png`
+5. Print:
+   ```
+   PHASE 4 GATE: PASS — Escalation engine operational. {n} classes mastered. {m} escalated challenges generated.
+   ```

prompts/phase-5.md

@@ -0,0 +1,293 @@
+# Phase 5 — HF Deployment + Demo Infrastructure
+> Paste this entire prompt into a fresh Claude Code session. All environment code (Phases 0–4) must be complete before starting. Training may still be pending — that's fine, it runs onsite.
+
+---
+
+All environment code is complete. Now package everything for HuggingFace Spaces deployment and build the demo infrastructure that will carry 30% of the judging score.
+
+---
+
+## Step 1 — `openenv.yaml`
+
+Create the OpenEnv manifest in the project root:
+
+```yaml
+name: viral-script-debugging-engine
+version: "1.0.0"
+description: >
+  A multi-agent RL environment where an LLM Arbitrator learns to improve
+  short-form video scripts through adversarial debate. Trains with GRPO via
+  HuggingFace TRL + Unsloth. Hits Theme 1 (Multi-Agent) and Theme 4
+  (Self-Improvement) simultaneously.
+themes:
+  - multi_agent_interactions
+  - self_improvement
+author: "Team Name"
+python_requires: ">=3.10"
+entry_point: environment.env:ViralScriptEnv
+reset_method: reset
+step_method: step
+state_method: state
+reward_method: reward
+tools:
+  - name: reset
+    description: "Start a new script improvement episode"
+  - name: step
+    description: "Execute one debate round: Critic attacks, Defender responds, Arbitrator acts, Rewriter executes"
+  - name: state
+    description: "Get current environment state including script, debate history, and reward components"
+dependencies:
+  - anthropic>=0.40.0
+  - sentence-transformers>=2.7.0
+  - unsloth
+  - trl>=0.12.0
+  - numpy>=1.26.0
+  - pydantic>=2.0.0
+  - fastapi>=0.110.0
+  - uvicorn>=0.29.0
+```
+
+---
+
+## Step 2 — `app.py` (FastAPI server for HF Spaces)
+
+```python
+"""
+FastAPI wrapper exposing ViralScriptEnv as an OpenEnv-compliant HTTP server.
+Deployed to HuggingFace Spaces on port 7860.
+"""
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from environment.env import ViralScriptEnv
+import uvicorn
+
+app = FastAPI(
+    title="Viral Script Debugging Engine",
+    description="Multi-agent RL environment for improving short-form video scripts",
+    version="1.0.0",
+)
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+_envs: dict = {}   # per-session env instances keyed by session_id
+
+class ResetRequest(BaseModel):
+    session_id: str
+    difficulty: str = "easy"
+    options: dict = {}
+
+class StepRequest(BaseModel):
+    session_id: str
+    action: dict
+
+@app.post("/reset")
+def reset(req: ResetRequest):
+    env = ViralScriptEnv(difficulty=req.difficulty)
+    obs, info = env.reset(options=req.options)
+    _envs[req.session_id] = env
+    return {"observation": obs, "info": info}
+
+@app.post("/step")
+def step(req: StepRequest):
+    env = _envs.get(req.session_id)
+    if not env:
+        raise HTTPException(404, f"Session {req.session_id} not found. Call /reset first.")
+    obs, reward, terminated, truncated, info = env.step(req.action)
+    return {"observation": obs, "reward": reward, "terminated": terminated, "truncated": truncated, "info": info}
+
+@app.get("/state/{session_id}")
+def state(session_id: str):
+    env = _envs.get(session_id)
+    if not env:
+        raise HTTPException(404, "Session not found")
+    return env.state()
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "environment": "ViralScriptDebugEngine", "version": "1.0.0"}
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860)
+```
+
+---
+
+## Step 3 — `Dockerfile`
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]
+```
+
+---
+
+## Step 4 — `demo/run_demo.py`
+
+The flagship demo script — what you run during the pitch. Must tell a 5-act story with `rich` terminal output.
+
+```
+python demo/run_demo.py --script S03 --compare    # base vs trained side-by-side
+python demo/run_demo.py --interactive             # human acts as Arbitrator
+```
+
+**Act 1 — "The Raw Script"**
+- Display original script in a `rich` Panel
+- Show: region, platform, niche, known flaws
+
+**Act 2 — "The Critic Attacks"**
+- Run Critic on the script
+- Display each `CritiqueClaim` as a numbered panel, colour-coded by severity (red=high, yellow=medium, green=low)
+- 2-second pause between claims for dramatic effect
+
+**Act 3 — "The Defender Responds"**
+- Run Defender
+- Display `core_strength` in a highlighted box: "WHAT WE MUST PROTECT"
+- Show each `flagged_critic_claims` entry with "⚠ Defender flagged this as overcorrection"
+
+**Act 4 — "The Arbitrator Decides"** (both shown when `--compare`)
+- Grey panel: "Untrained Arbitrator chose: [action] — Reasoning: [reasoning]"
+- Blue panel: "Trained Arbitrator chose: [action] — Reasoning: [reasoning]"
+- Highlight the difference in reasoning
+
+**Act 5 — "The Rewrite + Reward"**
+- Show rewritten script as unified diff (coloured: green=added, red=removed)
+- Show reward components as a progress-bar table:
+  ```
+  R1 Hook Strength    ██████░░  0.75
+  R2 Coherence        ████░░░░  0.60
+  R3 Cultural         ███████░  0.85
+  R4 Resolution       █████░░░  0.70
+  R5 Preservation     ██████░░  0.75
+  ─────────────────────────────────
+  Total               █████░░░  0.73  (+34% vs baseline)
+  ```
+
+---
+
+## Step 5 — `README.md`
+
+Write the complete README with this exact structure:
+
+```markdown
+# Viral Script Debugging Engine
+### Meta × OpenEnv Hackathon 2026 | Theme 1: Multi-Agent · Theme 4: Self-Improvement
+
+## The Problem
+[2 paragraphs: 95% of creators never break 10k. Existing tools are one-shot pipelines, not RL.]
+
+## What We Built
+[2 paragraphs: the multi-agent RL loop. NOT a content generator. A reasoning system.]
+
+## How It Works
+[Describe the 4-step loop: Critic → Defender → Arbitrator → Rewriter. One episode = one trajectory.]
+
+## Environment API
+[Code block showing reset(), step(), state(), reward() with example inputs/outputs]
+
+## Reward Functions
+[Table of R1–R5: what each measures and how it's computed]
+
+## Anti-Gaming Protections
+[Explain the two rules: catastrophic drop penalty and action diversity penalty]
+[Show 2–3 real examples from training logs where penalties fired]
+
+## Self-Improvement Loop (Theme 4)
+[Explain the Critic Escalation Engine and Difficulty Tracker]
+![Escalation chart](logs/escalation_chart.png)
+
+## Training
+Model: Qwen2.5-7B-Instruct | Algorithm: GRPO via TRL + Unsloth
+[Link to Colab notebook]
+
+## Results
+![Reward improvement](logs/training_vs_baseline.png)
+[Table: per-reward improvement, baseline vs trained]
+
+## Why This Matters for Meta
+[One paragraph: the Meta business case]
+
+## HuggingFace Space
+[Link: huggingface.co/spaces/YOUR_TEAM/viral-script-debugging-engine]
+
+## References
+[Links to mini-blog, video demo, Colab notebook]
+```
+
+---
+
+## Step 6 — `notebooks/training_colab.ipynb`
+
+Generate a Colab-ready notebook with these cells in order:
+
+```python
+# Cell 1 — Install
+!pip install unsloth trl anthropic sentence-transformers openenv pydantic rich
+
+# Cell 2 — API key
+import os
+os.environ["ANTHROPIC_API_KEY"] = "YOUR_KEY_HERE"
+
+# Cell 3 — Dry-run to validate pipeline
+!python training/train_grpo.py --dry-run --steps 5
+
+# Cell 4 — Full training
+!python training/train_grpo.py --tier easy,medium --steps 200 --model unsloth/Qwen2.5-7B-Instruct-bnb-4bit
+
+# Cell 5 — Evaluate and plot
+!python training/eval_trained_model.py
+
+# Cell 6 — Display reward curves inline
+from IPython.display import Image
+Image("logs/training_vs_baseline.png")
+
+# Cell 7 — Run demo
+!python demo/run_demo.py --script S03 --compare
+```
+
+---
+
+## Step 7 — `scripts/submission_check.py`
+
+```
+python scripts/submission_check.py
+```
+
+Prints PASS or FAIL for each requirement:
+
+- `openenv.yaml` exists and parses without error
+- `app.py` starts without error (test with a 3-second subprocess timeout)
+- README contains `huggingface.co/spaces` link
+- `logs/baseline_reward_curves.png` exists
+- `logs/training_vs_baseline.png` exists
+- `logs/escalation_chart.png` exists
+- `notebooks/training_colab.ipynb` exists
+- README contains all required sections (The Problem, What We Built, Reward Functions, Anti-Gaming, Results)
+- `requirements.txt` is complete
+- All tests pass (`pytest` exit code 0)
+
+Final output: `SUBMISSION READY ✓` or `SUBMISSION INCOMPLETE — fix the above before submitting`
+
+---
+
+## Gate check
+
+Run:
+```
+python scripts/submission_check.py
+```
+
+All 10 checks must print PASS. Fix any failures before considering this phase done.
+
+Then run the demo end-to-end once to confirm it tells the full 5-act story without errors:
+```
+python demo/run_demo.py --script S03 --compare
+```

prompts/phase-index.md

@@ -0,0 +1,105 @@
+# Claude Code Prompts — Index
+## Viral Script Debugging Engine · Meta × OpenEnv Hackathon
+
+---
+
+## How to use these files
+
+Each file is a standalone prompt. Open a **fresh Claude Code session** for each phase and paste the entire file contents. Do not trim or summarise — Claude Code needs the full context.
+
+**Do not open the next phase until the gate check at the bottom of the current phase prints PASS.**
+
+---
+
+## Files
+
+| File | Phase | What it builds | Gate command |
+|---|---|---|---|
+| `phase_0_critic_gate.md` | Phase 0 | Critic agent + evaluation harness + 10 test scripts | `python scripts/run_critic_gate.py --dry-run` |
+| `phase_1_openenv_scaffold.md` | Phase 1 | OpenEnv env scaffold + R1/R2 rewards + Rewriter | `python scripts/run_dummy_episode.py --difficulty easy --steps 3 --verbose` |
+| `phase_2_defender_rewards_baseline.md` | Phase 2 | Defender + R3/R4/R5 + anti-gaming logging + baseline curves | `python scripts/run_baseline.py` |
+| `phase_3_curriculum_grpo_training.md` | Phase 3 | Curriculum datasets + GRPO training pipeline | `python training/train_grpo.py --dry-run` |
+| `phase_4_escalation_engine.md` | Phase 4 | Difficulty Tracker + Critic Escalation Engine | `python scripts/run_escalation_demo.py --episodes 10 --verbose` |
+| `phase_5_deployment_demo.md` | Phase 5 | FastAPI server + Dockerfile + demo script + README | `python scripts/submission_check.py` |
+
+---
+
+## Full file structure after all phases
+
+```
+viral_script_engine/
+├── agents/
+│   ├── critic.py                     # Phase 0
+│   ├── defender.py                   # Phase 2
+│   ├── rewriter.py                   # Phase 1
+│   └── baseline_arbitrator.py        # Phase 2
+├── data/
+│   ├── test_scripts/scripts.json     # Phase 0
+│   ├── golden_fixtures/              # Phase 0
+│   ├── cultural_kb.json              # Phase 2
+│   └── curriculum/                   # Phase 3
+│       ├── easy_tier.jsonl
+│       ├── medium_tier.jsonl
+│       ├── hard_tier.jsonl
+│       └── synthetic_scripts.json
+├── environment/
+│   ├── env.py                        # Phase 1 (updated Phase 2, 4)
+│   ├── actions.py                    # Phase 1
+│   ├── observations.py               # Phase 1
+│   └── episode_state.py              # Phase 1
+├── escalation/
+│   ├── difficulty_tracker.py         # Phase 4
+│   └── critic_escalation_engine.py   # Phase 4
+├── evaluation/
+│   └── critic_evaluator.py           # Phase 0
+├── rewards/
+│   ├── base.py                       # Phase 1
+│   ├── r1_hook_strength.py           # Phase 1
+│   ├── r2_coherence.py               # Phase 1
+│   ├── r3_cultural_alignment.py      # Phase 2
+│   ├── r4_debate_resolution.py       # Phase 2
+│   ├── r5_defender_preservation.py   # Phase 2
+│   └── reward_aggregator.py          # Phase 1 (updated Phase 2)
+├── training/
+│   ├── rollout_function.py           # Phase 3
+│   ├── train_grpo.py                 # Phase 3
+│   ├── eval_trained_model.py         # Phase 3
+│   └── reward_curves.py              # Phase 3
+├── demo/
+│   └── run_demo.py                   # Phase 5
+├── scripts/
+│   ├── run_critic_gate.py            # Phase 0
+│   ├── run_dummy_episode.py          # Phase 1
+│   ├── run_baseline.py               # Phase 2
+│   ├── run_escalation_demo.py        # Phase 4
+│   └── submission_check.py           # Phase 5
+├── tests/
+│   ├── test_critic.py                # Phase 0
+│   ├── test_environment.py           # Phase 1
+│   ├── test_rewards.py               # Phase 1
+│   ├── test_phase2.py                # Phase 2
+│   ├── test_training_pipeline.py     # Phase 3
+│   └── test_escalation.py           # Phase 4
+├── notebooks/
+│   └── training_colab.ipynb          # Phase 5
+├── logs/                             # generated at runtime
+├── outputs/                          # training checkpoints
+├── app.py                            # Phase 5
+├── openenv.yaml                      # Phase 5
+├── Dockerfile                        # Phase 5
+├── requirements.txt                  # Phase 0
+└── README.md                         # Phase 5
+```
+
+---
+
+## Key constraints to keep in mind across all phases
+
+- Use the **Anthropic Python SDK** only (not OpenAI)
+- All models/dataclasses use **Pydantic** for validation
+- LLM calls only in: CriticAgent, DefenderAgent, RewriterAgent, BaselineArbitratorAgent, CriticEscalationEngine
+- Evaluators and reward scorers (R1, R3) are **purely rule-based — zero LLM calls**
+- Store API key in `.env`, load with `python-dotenv`
+- Use `rich` for all console output
+- Mock all Anthropic API calls in tests — no real API calls in the test suite
+- Model saving: always use `save_pretrained_merged`, never naive upcast from 4-bit

session/context.md

@@ -0,0 +1,56 @@
+# Context — Carry Over for Next Session
+
+## Purpose
+Read this file at every session start after index.md and phase-log.md.
+Contains only what Claude needs to resume without re-reading everything.
+Overwrite when context changes. Keep it minimal and current.
+
+---
+
+## Current Phase
+Phase: [number]
+Prompt file: prompts/phase-X.md
+Status: [in progress / complete / blocked]
+
+---
+
+## Currently Working On
+Feature: [name]
+File(s): [list]
+Status: [what is done, what is not]
+
+---
+
+## Open Questions
+
+[question that needs user input before proceeding]
+[question that needs user input before proceeding]
+
+
+---
+
+## Known Blockers
+
+[what is blocked and why]
+
+
+---
+
+## Last Commit Message
+[most recent commit message generated]
+
+---
+
+## Do Not Forget
+
+[critical thing to remember for next session]
+[critical thing to remember for next session]
+
+
+---
+
+## Rules for This File
+- Keep this file under 30 lines always
+- Overwrite at end of every session
+- Only include what is immediately needed to resume
+- Do not include explanations — only facts and state

session/phase-log.md

@@ -0,0 +1,31 @@
+# Phase Log — Full History
+
+## Purpose
+Read this file at every session start to know overall progress.
+One line per phase or significant milestone. Never overwrite — only append.
+This is the only file that keeps permanent history across all sessions.
+
+---
+
+## Format
+[YYYY-MM-DD] [Phase X] [status] — [one liner of what happened]
+
+## Status Tags
+STARTED     — phase work has begun
+PARTIAL     — some features done, phase not complete
+COMPLETE    — all features done, all tests passing
+BLOCKED     — cannot proceed, reason in line
+ROLLED BACK — changes reverted, reason in line
+
+---
+
+## Log
+[YYYY-MM-DD] [Phase 1] STARTED — project scaffolding begun
+
+---
+
+## Rules for This File
+- Never delete or overwrite any line
+- Append only — one line per session or milestone
+- Keep each line under 15 words after the date and phase tag
+- This file is the single source of truth for project history

session/summary.md

@@ -0,0 +1,57 @@
+# Session Summary — Last Session Record
+
+## Purpose
+Read this file only if context.md is unclear or incomplete.
+Overwrite this file at the end of every session.
+One session = one summary. Previous summaries live in phase-log.md.
+
+---
+
+## Last Session
+
+### Date
+[YYYY-MM-DD]
+
+### Phase
+[Phase number and name]
+
+### What Was Done
+
+[one liner]
+[one liner]
+[one liner]
+
+
+### What Was NOT Done (carry over)
+
+[one liner]
+[one liner]
+
+
+### Errors Encountered
+
+[file:function] — [reason] — [how it was fixed]
+
+
+### Tests Status
+Total: 0 | Passed: 0 | Failed: 0
+
+### Commit Messages Generated
+
+[commit message]
+[commit message]
+
+
+### Notes for Next Session
+
+[one liner]
+[one liner]
+
+
+---
+
+## Rules for This File
+- Overwrite at end of every session — do not append
+- Keep every section to one liners only
+- Move key notes to context.md if needed next session
+- Full phase history lives in phase-log.md not here