feat: add 2 new rules (27 total) - verify-before-use, context-management + major upgrades to ai-collaboration and error-handling

- verify-before-use.mdc: Forces type checking, file re-reading, schema verification (inspired by Claude Code's skeptical retrieval)
- context-management.mdc: Prevents context bloat in long sessions, sub-task splitting, structured summarization
- ai-collaboration.mdc: Major rewrite with ActionResponse pattern, verification checklist, skeptical retrieval
- error-handling.mdc: Added ActionResponse type, explicit no-leak rule, Supabase error patterns
- Updated all counts: 25 -> 27 across README.md, llms.txt

Author: vibestackdev

.cursor/rules/ai-collaboration.mdc

@@ -1,27 +1,105 @@
 ---
 description: Instructions for AI agent code generation workflow
 globs: ["*"]
+alwaysApply: true
 ---
 
 # AI Collaboration Guidelines
 
-The 3-stage agentic loop:
+## The 3-Stage Agentic Loop
 
-1. **PLAN:** 
-"Analyze the current codebase and plan how to implement [feature]. List the files you'll modify and why. Don't write code yet."
+Every code generation task MUST follow this loop:
 
-2. **IMPLEMENT:** 
-"Implement the plan. Follow all `.cursor/rules/` guidelines. If you're unsure about auth or RLS, check `supabase-auth-security.mdc`."
+### Stage 1: PLAN (gather context first)
 
-3. **REVIEW:** 
-"Review what you just generated. Check for:
-- `getSession()` usage (MUST be `getUser()`)
-- Missing error boundaries or `loading.tsx`
-- Next.js 15 async layout/page params
-- TypeScript `any` types (use `unknown` or define interface)
-Report any issues before I run it."
+Before writing ANY code, the AI MUST:
+1. Read the relevant source files to verify current state — do NOT rely on memory
+2. Identify which `.cursor/rules/` files apply to this task
+3. List the files to modify and explain why
+4. Do NOT write code yet
+
+Prompt template:
+```
+Analyze the current codebase and plan how to implement [feature]. 
+List the files you'll modify and why. Don't write code yet.
+```
+
+### Stage 2: IMPLEMENT (follow constraints)
+
+When generating code:
+- Follow ALL active `.cursor/rules/` constraints
+- If unsure about auth patterns, re-read `supabase-auth-security.mdc`
+- If unsure about params/layouts, re-read `nextjs15-params.mdc`
+- Use `unknown` + Zod validation instead of `any` for external data
+- Return `ActionResponse<T>` from all Server Actions (see below)
+
+### Stage 3: VERIFY (confirm before declaring done)
+
+After generating code, the AI MUST self-check:
+- [ ] No `getSession()` on the server (MUST be `getUser()`)
+- [ ] No synchronous `params` or `searchParams` access
+- [ ] No `@supabase/auth-helpers-nextjs` imports
+- [ ] No `any` types — use `unknown` + type narrowing
+- [ ] Every API route has Zod validation
+- [ ] Every error is caught and returns `{ error: string }`
+- [ ] New tables have RLS enabled
+- [ ] `loading.tsx` and `error.tsx` exist for data-fetching pages
+
+Report issues BEFORE the developer runs the code.
+
+## Skeptical Retrieval Rule
+
+NEVER trust stored knowledge about the codebase. Before modifying a file:
+1. Re-read the file to verify its current contents
+2. Check imports and exports to ensure they match expectations
+3. Verify that function signatures haven't changed
+
+This prevents generating code that references stale function signatures, 
+deleted files, or renamed exports.
+
+## Standard Patterns
+
+### ActionResponse Type (use for all Server Actions)
+```typescript
+type ActionResponse<T = void> = 
+  | { success: true; data: T }
+  | { success: false; error: string }
+```
+
+### Standard Server Action Structure
+```typescript
+'use server'
+import { createClient } from '@/lib/supabase/server'
+import { z } from 'zod'
+
+const Schema = z.object({ /* ... */ })
+
+export async function myAction(input: unknown): Promise<ActionResponse<MyType>> {
+  // 1. Auth
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) return { success: false, error: 'Unauthorized' }
+
+  // 2. Validate
+  const result = Schema.safeParse(input)
+  if (!result.success) return { success: false, error: 'Invalid input' }
+
+  // 3. Execute
+  try {
+    const { data, error } = await supabase.from('table').insert(result.data).select().single()
+    if (error) throw error
+    return { success: true, data }
+  } catch {
+    return { success: false, error: 'Operation failed' }
+  }
+}
+```
+
+## Task Constraints
+
+- NEVER give the AI a task longer than 200 words
+- NEVER let the AI implement more than 3-4 files in one turn
+- NEVER let the AI skip the verification checklist
+- ALWAYS review the Git diff before committing
+- When uncertain, ask the developer — do NOT guess
 
-Constraints:
-- NEVER give the AI a task longer than 200 words.
-- NEVER let the AI implement more than 3-4 files in one turn.
-- ALWAYS review the Git diff before committing.

.cursor/rules/context-management.mdc

@@ -0,0 +1,61 @@
+---
+description: Context window management — prevents AI from losing track during long sessions
+globs: ["*"]
+alwaysApply: false
+---
+
+# Context Management Rules
+
+## RULE 1: Break Large Tasks Into Sub-Tasks
+
+If a feature requires changes to more than 4 files, break it into sequential sub-tasks.
+Complete and verify each sub-task before starting the next.
+
+Example — "Add a blog feature with CRUD":
+1. Sub-task 1: Database migration + RLS policies
+2. Sub-task 2: Server Actions (create, read, update, delete)
+3. Sub-task 3: UI components (list, detail, form)
+4. Sub-task 4: Route handlers + API endpoints
+5. Sub-task 5: Integration testing
+
+## RULE 2: Summarize Before Continuing
+
+If the conversation has been going for more than 5 turns, summarize
+what has been done and what remains before generating more code.
+
+Template:
+```
+Before continuing, let me summarize:
+✅ Completed: [list of completed items]
+🔄 In progress: [current item]
+📋 Remaining: [list of remaining items]
+```
+
+## RULE 3: Reference Files By Full Path
+
+When discussing code, ALWAYS use the full path relative to the project root.
+This prevents confusion between similarly named files.
+
+✅ CORRECT: "Update `src/app/dashboard/page.tsx`"
+❌ WRONG: "Update the dashboard page"
+
+✅ CORRECT: "Import from `@/lib/supabase/server`"
+❌ WRONG: "Import the Supabase client"
+
+## RULE 4: One Concern Per Message
+
+Each AI message should address ONE concern clearly:
+- ONE file modification with before/after
+- ONE bug fix with explanation
+- ONE new feature with complete implementation
+
+Do NOT mix unrelated changes in a single response. This makes
+review harder and increases the chance of introducing bugs.
+
+## RULE 5: Keep Rule Files Under 150 Lines
+
+Individual `.mdc` rule files should stay under 150 lines.
+If a rule file grows beyond that, split it into focused sub-rules.
+
+This mirrors the principle from production AI harnesses:
+keep the index lightweight, put details in separate files.

.cursor/rules/error-handling.mdc

@@ -1,42 +1,135 @@
 ---
-description: Error boundaries and loading states guidelines
+description: Error boundaries, loading states, and server error handling
 globs: ["**/app/**"]
 ---
 
 # Error Handling and Loading States
 
-EVERY page in `app/` router MUST have sibling files if it does data fetching:
-- `loading.tsx` (Suspense boundary)
+## RULE 1: Every Data-Fetching Page Needs Sibling Files
+
+EVERY page in `app/` router that does data fetching MUST have:
+- `loading.tsx` (Suspense boundary — shown during streaming)
 - `error.tsx` (Error boundary — must be `'use client'`)
 
 `loading.tsx` template:
 ```tsx
 export default function Loading() {
-  return <div className="animate-pulse">Loading...</div>
+  return (
+    <div className="flex items-center justify-center min-h-[200px]">
+      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary" />
+    </div>
+  )
 }
 ```
 
 `error.tsx` template:
 ```tsx
 'use client'
-export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+
+export default function Error({ 
+  error, 
+  reset 
+}: { 
+  error: Error & { digest?: string }
+  reset: () => void 
+}) {
   return (
-    <div>
-      <h2>Something went wrong</h2>
-      <button onClick={reset}>Try again</button>
+    <div className="flex flex-col items-center justify-center min-h-[200px] gap-4">
+      <h2 className="text-xl font-semibold">Something went wrong</h2>
+      <p className="text-muted-foreground">An unexpected error occurred.</p>
+      <button 
+        onClick={reset}
+        className="px-4 py-2 bg-primary text-primary-foreground rounded-md"
+      >
+        Try again
+      </button>
     </div>
   )
 }
 ```
 
-Server Action error pattern:
+## RULE 2: NEVER Expose Internal Errors to Clients
+
+Server errors, database errors, and stack traces MUST stay server-side.
+Return generic messages to the client. Log the real error.
+
+✅ CORRECT:
+```typescript
+try {
+  const { data, error } = await supabase.from('posts').select()
+  if (error) throw error
+  return data
+} catch (error) {
+  console.error('[POSTS_FETCH_ERROR]', error) // Detailed log server-side
+  return NextResponse.json(
+    { error: 'Failed to fetch posts' }, // Generic message to client
+    { status: 500 }
+  )
+}
+```
+
+❌ WRONG:
+```typescript
+} catch (error) {
+  return NextResponse.json(
+    { error: error.message }, // Leaks: "relation 'posts' does not exist"
+    { status: 500 }
+  )
+}
+```
+
+## RULE 3: Use ActionResponse for All Server Actions
+
+Every Server Action MUST return a typed response — never throw.
+
 ```typescript
-export async function createItem(formData: FormData) {
-  try {
-    // ... operation
-    return { success: true }
-  } catch (error) {
-    return { error: 'Failed to create item' }
+type ActionResponse<T = void> = 
+  | { success: true; data: T }
+  | { success: false; error: string }
+
+// Usage:
+export async function createPost(input: unknown): Promise<ActionResponse<Post>> {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) return { success: false, error: 'Unauthorized' }
+
+  const parsed = PostSchema.safeParse(input)
+  if (!parsed.success) return { success: false, error: 'Invalid input' }
+
+  const { data, error } = await supabase
+    .from('posts')
+    .insert({ ...parsed.data, user_id: user.id })
+    .select()
+    .single()
+
+  if (error) {
+    console.error('[CREATE_POST_ERROR]', error)
+    return { success: false, error: 'Failed to create post' }
   }
+
+  revalidatePath('/dashboard')
+  return { success: true, data }
 }
 ```
+
+## RULE 4: Handle Supabase Errors Explicitly
+
+NEVER ignore the `error` field from Supabase queries.
+
+✅ CORRECT:
+```typescript
+const { data, error } = await supabase.from('posts').select()
+if (error) {
+  console.error('[SUPABASE_ERROR]', error.message, error.code)
+  throw new Error('Database query failed')
+}
+// data is now safely typed as non-null
+```
+
+❌ WRONG:
+```typescript
+const { data } = await supabase.from('posts').select()
+// data could be null if query failed — using it causes runtime crash
+return data.map(post => post.title) // TypeError: Cannot read property 'map' of null
+```
+