compress-claude 1.0.0

package/dist/generator.js

@@ -0,0 +1,3025 @@
+"use strict";
+// ---- generator.ts ----
+// Generated context files (CLAUDE.md, ai-docs/) for Claude Code sessions.
+// Converted from claude-context.js to TypeScript.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTRA_FILES = exports.SKILL_FILES = exports.ALL_DOMAIN_DOCS = void 0;
+exports.generateContextFiles = generateContextFiles;
+exports.claudeMd = claudeMd;
+exports.generateDomainDoc = generateDomainDoc;
+exports.getDomainFiles = getDomainFiles;
+exports.generatePromptFile = generatePromptFile;
+exports.getPromptFiles = getPromptFiles;
+exports.generateSkillFile = generateSkillFile;
+exports.generateExtraFile = generateExtraFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("./utils/logger");
+// ---------------------------------------------------------------------------
+// Prompts Index
+// ---------------------------------------------------------------------------
+function promptsIndex(stack) {
+    return `# PROMPTS.md — Pattern Library Index
+
+> Before writing any non-trivial code, check this index.
+> Load the relevant category file, find the pattern, follow Build → Verify → Debug.
+> This prevents hallucinated APIs, broken patterns, and wasted tokens.
+
+## How to Use
+1. Find your task in the index below
+2. Load the category file: \`Read /ai-docs/prompts/[category].md\`
+3. Follow the Build prompt exactly
+4. Run the Verify checklist before moving on
+5. If broken, use the Debug guide — don't guess
+
+## Categories
+
+| Category | File | Covers |
+|----------|------|--------|
+| Auth | \`/ai-docs/prompts/auth.md\` | Sign up, sign in, magic link, OAuth, session, middleware |
+| Database | \`/ai-docs/prompts/database.md\` | Schema, queries, migrations, relations, transactions |
+| Payments | \`/ai-docs/prompts/payments.md\` | Checkout, webhooks, portal, subscription gates, refunds |
+| API | \`/ai-docs/prompts/api.md\` | Route handlers, validation, errors, rate limiting, middleware |
+| Email | \`/ai-docs/prompts/email.md\` | Templates, triggers, testing, DNS |
+| UI | \`/ai-docs/prompts/ui.md\` | Pages, components, forms, tables, modals, loading states |
+| Deployment | \`/ai-docs/prompts/deployment.md\` | Railway deploy, env vars, crons, health checks, rollback |
+| Analytics | \`/ai-docs/prompts/analytics.md\` | GA4 events, Search Console, conversions, sitemap |
+| Security | \`/ai-docs/prompts/security.md\` | Auth checks, input validation, rate limiting, OWASP |
+| Testing | \`/ai-docs/prompts/testing.md\` | Unit tests, integration, mocks, coverage |
+
+## Quick Reference — Most Common Tasks
+
+\`\`\`
+Adding a new page          → ui.md        → "New Route/Page"
+Adding a new API endpoint  → api.md       → "New Route Handler"
+Changing DB schema         → database.md  → "Schema Change"
+Adding auth to a route     → auth.md      → "Protect a Route"
+New Stripe webhook event   → payments.md  → "Handle Webhook Event"
+Sending a transactional email → email.md → "Send Transactional Email"
+New cron job               → deployment.md → "Add Cron Job"
+Tracking a conversion      → analytics.md → "Track Custom Event"
+\`\`\`
+
+## Token-Saving Rules
+- Load ONE category file at a time — don't load all of them
+- Only load domain docs relevant to the current task
+- After finishing a task, you can unload the category file
+- Check MISTAKES.md before starting any task you've attempted before
+`;
+}
+;
+// ---------------------------------------------------------------------------
+// Prompts Auth
+// ---------------------------------------------------------------------------
+function authPrompts(stack) {
+    const auth = stack.auth || 'custom auth';
+    const isClerk = auth.includes('Clerk');
+    const isNextAuth = auth.includes('NextAuth');
+    const isSupabase = auth.includes('Supabase');
+    return `# Auth Prompts
+
+## Protect a Route (Middleware)
+
+### Build
+${isClerk ? `\`\`\`typescript
+// middleware.ts (root level)
+import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
+
+const isPublicRoute = createRouteMatcher([
+  '/', '/sign-in(.*)', '/sign-up(.*)', '/api/webhooks(.*)', '/api/health'
+]);
+
+export default clerkMiddleware((auth, req) => {
+  if (!isPublicRoute(req)) auth().protect();
+});
+
+export const config = { matcher: ['/((?!_next|[^?]*\\\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)'] };
+\`\`\`` : ''}
+${isNextAuth ? `\`\`\`typescript
+// middleware.ts
+export { default } from 'next-auth/middleware';
+export const config = { matcher: ['/dashboard/:path*', '/api/protected/:path*'] };
+\`\`\`` : ''}
+
+### Verify
+- [ ] Public routes accessible without auth (/, /sign-in, /api/health, /api/webhooks/*)
+- [ ] Protected routes redirect to sign-in when unauthenticated
+- [ ] API routes return 401 JSON (not redirect) when unauthenticated
+- [ ] Webhook endpoints explicitly excluded from auth middleware
+
+### Debug
+- Route redirecting when it shouldn't → check \`isPublicRoute\` matcher patterns
+- Webhook 401s → ensure \`/api/webhooks(.*)\` is in public routes
+- Middleware not running → check \`config.matcher\` excludes static files
+
+---
+
+## Get Current User (Server Component)
+
+### Build
+${isClerk ? `\`\`\`typescript
+import { auth, currentUser } from '@clerk/nextjs/server';
+
+// Just the ID (fastest — use this for auth checks)
+const { userId } = auth();
+if (!userId) redirect('/sign-in');
+
+// Full user object (slower — only when you need name/email)
+const user = await currentUser();
+\`\`\`` : ''}
+${isNextAuth ? `\`\`\`typescript
+import { getServerSession } from 'next-auth';
+import { authOptions } from '@/lib/auth';
+
+const session = await getServerSession(authOptions);
+if (!session) redirect('/sign-in');
+const { user } = session; // user.id, user.email, user.role
+\`\`\`` : ''}
+${isSupabase ? `\`\`\`typescript
+import { createServerClient } from '@supabase/auth-helpers-nextjs';
+import { cookies } from 'next/headers';
+
+const supabase = createServerClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+  { cookies: { get: (name) => cookies().get(name)?.value } }
+);
+const { data: { session } } = await supabase.auth.getSession();
+if (!session) redirect('/sign-in');
+\`\`\`` : ''}
+
+### Verify
+- [ ] Unauthenticated users redirected correctly
+- [ ] userId/session is typed (not \`any\`)
+- [ ] Not calling \`currentUser()\` when you only need \`userId\` (costs extra request)
+
+### Debug
+- \`userId\` is null in middleware but user is signed in → session cookie missing, check domain config
+- \`currentUser()\` returns null → user exists in Clerk but not synced, check webhook
+
+---
+
+## Get Current User (API Route / Server Action)
+
+### Build
+${isClerk ? `\`\`\`typescript
+// In API route or Server Action
+import { auth } from '@clerk/nextjs/server';
+
+export async function POST(req: Request) {
+  const { userId } = auth();
+  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  // ... rest of handler
+}
+\`\`\`` : ''}
+
+### Verify
+- [ ] Returns 401 JSON (not redirect) for API routes
+- [ ] userId checked BEFORE any DB query
+- [ ] Never trust userId from request body — always from session
+
+---
+
+## Sync User to Database (Webhook)
+
+### Build
+${isClerk ? `\`\`\`typescript
+// app/api/webhooks/clerk/route.ts
+import { Webhook } from 'svix';
+import { headers } from 'next/headers';
+import { db } from '@/lib/db';
+
+export async function POST(req: Request) {
+  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET;
+  if (!WEBHOOK_SECRET) throw new Error('Missing CLERK_WEBHOOK_SECRET');
+
+  const payload = await req.json();
+  const headerPayload = headers();
+  const svixHeaders = {
+    'svix-id': headerPayload.get('svix-id')!,
+    'svix-timestamp': headerPayload.get('svix-timestamp')!,
+    'svix-signature': headerPayload.get('svix-signature')!,
+  };
+
+  const wh = new Webhook(WEBHOOK_SECRET);
+  let evt: any;
+  try {
+    evt = wh.verify(JSON.stringify(payload), svixHeaders);
+  } catch {
+    return Response.json({ error: 'Invalid signature' }, { status: 400 });
+  }
+
+  if (evt.type === 'user.created') {
+    await db.user.create({
+      data: {
+        clerkId: evt.data.id,
+        email: evt.data.email_addresses[0].email_address,
+        name: \`\${evt.data.first_name} \${evt.data.last_name}\`.trim(),
+      },
+    });
+  }
+
+  if (evt.type === 'user.deleted') {
+    await db.user.update({
+      where: { clerkId: evt.data.id },
+      data: { deletedAt: new Date() },
+    });
+  }
+
+  return Response.json({ received: true });
+}
+\`\`\`` : ''}
+
+### Verify
+- [ ] Webhook signature verified before processing
+- [ ] Idempotent — re-running with same event doesn't create duplicates
+- [ ] \`user.created\`, \`user.updated\`, \`user.deleted\` all handled
+- [ ] Webhook secret in env vars, not hardcoded
+- [ ] Route in public routes (not behind auth middleware)
+
+### Debug
+- 400 on webhook → signature mismatch, check \`CLERK_WEBHOOK_SECRET\` matches dashboard
+- User not in DB → webhook not configured in Clerk dashboard, check endpoint URL
+- Duplicate users → missing idempotency check, add \`upsert\` instead of \`create\`
+
+---
+
+## Role-Based Access Control
+
+### Build
+\`\`\`typescript
+// src/lib/permissions.ts
+export type Role = 'admin' | 'user' | 'viewer';
+
+export const can = {
+  viewDashboard: (role: Role) => ['admin', 'user'].includes(role),
+  manageUsers: (role: Role) => role === 'admin',
+  exportData: (role: Role) => ['admin', 'user'].includes(role),
+};
+
+// Usage in Server Component or API route
+const user = await getUserFromDb(userId);
+if (!can.manageUsers(user.role)) {
+  return Response.json({ error: 'Forbidden' }, { status: 403 });
+}
+\`\`\`
+
+### Verify
+- [ ] Role checked server-side, never trusted from client
+- [ ] 403 returned (not 401) for wrong role — user is authenticated, just not authorized
+- [ ] Role stored in DB, not in JWT claims (claims can be stale)
+
+### Debug
+- Role check passing when it shouldn't → pulling role from JWT instead of DB, fix to query DB
+`;
+}
+;
+// ---------------------------------------------------------------------------
+// Prompts Database
+// ---------------------------------------------------------------------------
+function databasePrompts(stack) {
+    const db = stack.database || 'Prisma (PostgreSQL)';
+    const isPrisma = db.includes('Prisma');
+    const isDrizzle = db.includes('Drizzle');
+    return `# Database Prompts
+
+## Schema Change (Add Table or Column)
+
+### Build
+${isPrisma ? `1. Edit \`prisma/schema.prisma\`
+2. Run \`pnpm db:push\` (dev) or \`pnpm db:migrate\` (staging/prod)
+3. Regenerate client: \`pnpm prisma generate\`
+
+\`\`\`prisma
+// New table pattern
+model Post {
+  id        String   @id @default(cuid())
+  title     String
+  content   String?
+  published Boolean  @default(false)
+  authorId  String
+  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  deletedAt DateTime? // soft delete
+
+  @@index([authorId])
+  @@index([createdAt])
+}
+\`\`\`` : ''}
+${isDrizzle ? `1. Edit \`src/db/schema.ts\`
+2. Generate migration: \`pnpm drizzle-kit generate\`
+3. Run migration: \`pnpm drizzle-kit migrate\`
+
+\`\`\`typescript
+// src/db/schema.ts
+import { pgTable, text, boolean, timestamp, index } from 'drizzle-orm/pg-core';
+import { createId } from '@paralleldrive/cuid2';
+
+export const posts = pgTable('posts', {
+  id: text('id').primaryKey().$defaultFn(() => createId()),
+  title: text('title').notNull(),
+  content: text('content'),
+  published: boolean('published').default(false).notNull(),
+  authorId: text('author_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+  deletedAt: timestamp('deleted_at'),
+}, (table) => ({
+  authorIdx: index('posts_author_idx').on(table.authorId),
+  createdAtIdx: index('posts_created_at_idx').on(table.createdAt),
+}));
+\`\`\`` : ''}
+
+### Verify
+- [ ] Every table has: id, createdAt, updatedAt
+- [ ] Foreign keys have \`onDelete\` set (Cascade or SetNull — never default)
+- [ ] Indexes added for: all foreign keys + frequently filtered/sorted columns
+- [ ] Migration file generated and committed (don't skip migration for prod)
+- [ ] \`pnpm prisma generate\` run after schema change
+
+### Debug
+- Migration drift → \`pnpm prisma migrate reset\` (dev only!) then re-migrate
+- Type errors after schema change → forgot to run \`prisma generate\`
+- Slow queries → check missing indexes with \`EXPLAIN ANALYZE\` in Railway Postgres
+
+---
+
+## Query — Fetch with Relations
+
+### Build
+${isPrisma ? `\`\`\`typescript
+// ✅ Correct — select only what you need
+const posts = await prisma.post.findMany({
+  where: { authorId: userId, deletedAt: null },
+  select: {
+    id: true,
+    title: true,
+    published: true,
+    createdAt: true,
+    author: { select: { id: true, name: true } },
+  },
+  orderBy: { createdAt: 'desc' },
+  take: 20, // always paginate
+  skip: page * 20,
+});
+
+// ❌ Wrong — never do this
+const posts = await prisma.post.findMany(); // unbounded, returns everything
+\`\`\`` : ''}
+${isDrizzle ? `\`\`\`typescript
+// ✅ Correct
+const posts = await db
+  .select({
+    id: posts.id,
+    title: posts.title,
+    published: posts.published,
+    createdAt: posts.createdAt,
+    authorName: users.name,
+  })
+  .from(posts)
+  .leftJoin(users, eq(posts.authorId, users.id))
+  .where(and(eq(posts.authorId, userId), isNull(posts.deletedAt)))
+  .orderBy(desc(posts.createdAt))
+  .limit(20)
+  .offset(page * 20);
+\`\`\`` : ''}
+
+### Verify
+- [ ] Query is paginated (never unbounded)
+- [ ] Only selecting needed fields (not \`select *\` / full object)
+- [ ] \`deletedAt: null\` filter if using soft deletes
+- [ ] Sorted by a consistent field for stable pagination
+
+### Debug
+- N+1 queries → use \`include\`/\`join\` instead of looping and querying per item
+- Slow query → add missing index, or check if filtering on non-indexed column
+
+---
+
+## Multi-Step Write (Transaction)
+
+### Build
+${isPrisma ? `\`\`\`typescript
+// Always use transactions for multi-step writes
+const result = await prisma.$transaction(async (tx) => {
+  const user = await tx.user.update({
+    where: { id: userId },
+    data: { credits: { decrement: 1 } },
+  });
+
+  if (user.credits < 0) {
+    throw new Error('INSUFFICIENT_CREDITS'); // rolls back automatically
+  }
+
+  const job = await tx.job.create({
+    data: { userId, status: 'pending' },
+  });
+
+  return job;
+});
+\`\`\`` : ''}
+${isDrizzle ? `\`\`\`typescript
+const result = await db.transaction(async (tx) => {
+  const [updated] = await tx
+    .update(users)
+    .set({ credits: sql\`credits - 1\` })
+    .where(eq(users.id, userId))
+    .returning();
+
+  if (updated.credits < 0) throw new Error('INSUFFICIENT_CREDITS');
+
+  const [job] = await tx.insert(jobs).values({ userId, status: 'pending' }).returning();
+  return job;
+});
+\`\`\`` : ''}
+
+### Verify
+- [ ] All related writes inside a single transaction
+- [ ] Throws on invalid state (so transaction rolls back)
+- [ ] Return value is the final needed object, not intermediate results
+
+### Debug
+- Transaction timeout → operations inside are too slow, add indexes or split into background job
+- Deadlock → two transactions updating same rows in different order, standardize update order
+
+---
+
+## Soft Delete Pattern
+
+### Build
+\`\`\`typescript
+// Delete (soft)
+await prisma.post.update({
+  where: { id: postId, authorId: userId }, // scope to owner!
+  data: { deletedAt: new Date() },
+});
+
+// Always filter out deleted records in queries
+where: { deletedAt: null }
+
+// Hard delete (only for GDPR compliance / user data requests)
+await prisma.post.delete({ where: { id: postId } });
+\`\`\`
+
+### Verify
+- [ ] Soft delete scoped to owner (include \`authorId: userId\` in where)
+- [ ] All list queries include \`deletedAt: null\` filter
+- [ ] Hard delete available for GDPR requests only
+
+---
+
+## Seeding
+
+### Build
+\`\`\`typescript
+// prisma/seed.ts or scripts/seed.ts
+async function main() {
+  // Upsert so seed is idempotent (safe to re-run)
+  const admin = await prisma.user.upsert({
+    where: { email: 'admin@example.com' },
+    update: {},
+    create: {
+      email: 'admin@example.com',
+      name: 'Admin',
+      role: 'admin',
+    },
+  });
+  console.log('Seeded:', admin.email);
+}
+
+main().catch(console.error).finally(() => prisma.$disconnect());
+\`\`\`
+
+### Verify
+- [ ] Seed is idempotent — upsert not create
+- [ ] No hardcoded passwords or real data
+- [ ] Can be re-run safely in CI
+`;
+}
+;
+// ---------------------------------------------------------------------------
+// Prompts Payments
+// ---------------------------------------------------------------------------
+function paymentsPrompts(stack) {
+    return `# Payments Prompts
+
+## Create Checkout Session
+
+### Build
+\`\`\`typescript
+// app/api/checkout/route.ts
+import { stripe } from '@/lib/stripe';
+import { auth } from '@clerk/nextjs/server';
+import { db } from '@/lib/db';
+
+export async function POST(req: Request) {
+  const { userId } = auth();
+  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const { priceId } = await req.json();
+  const user = await db.user.findUnique({ where: { clerkId: userId } });
+  if (!user) return Response.json({ error: 'User not found' }, { status: 404 });
+
+  // Ensure Stripe customer exists
+  let customerId = user.stripeCustomerId;
+  if (!customerId) {
+    const customer = await stripe.customers.create({
+      email: user.email,
+      metadata: { userId: user.id },
+    });
+    customerId = customer.id;
+    await db.user.update({ where: { id: user.id }, data: { stripeCustomerId: customerId } });
+  }
+
+  const session = await stripe.checkout.sessions.create({
+    customer: customerId,
+    mode: 'subscription',
+    payment_method_types: ['card'],
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: \`\${process.env.NEXT_PUBLIC_APP_URL}/dashboard?upgraded=true\`,
+    cancel_url: \`\${process.env.NEXT_PUBLIC_APP_URL}/pricing\`,
+    metadata: { userId: user.id },
+  });
+
+  return Response.json({ url: session.url });
+}
+\`\`\`
+
+### Verify
+- [ ] Auth checked before creating session
+- [ ] Customer ID saved to DB (don't create duplicate customers)
+- [ ] \`success_url\` and \`cancel_url\` use env var, not hardcoded domain
+- [ ] Metadata includes \`userId\` for webhook reconciliation
+- [ ] Works in both test mode (test keys) and live mode
+
+### Debug
+- Customer already exists error → check \`stripeCustomerId\` in DB before creating
+- Redirect after checkout goes nowhere → check \`success_url\` env var is set in Railway
+- Webhook not updating subscription → confirm webhook is pointed at prod URL, not localhost
+
+---
+
+## Handle Webhook Events
+
+### Build
+\`\`\`typescript
+// app/api/webhooks/stripe/route.ts
+import Stripe from 'stripe';
+import { stripe } from '@/lib/stripe';
+import { db } from '@/lib/db';
+
+export async function POST(req: Request) {
+  const body = await req.text(); // MUST be text, not json()
+  const sig = req.headers.get('stripe-signature')!;
+
+  let event: Stripe.Event;
+  try {
+    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
+  } catch {
+    return Response.json({ error: 'Invalid signature' }, { status: 400 });
+  }
+
+  // Idempotency: check if already processed
+  const processed = await db.webhookEvent.findUnique({ where: { stripeEventId: event.id } });
+  if (processed) return Response.json({ received: true });
+
+  try {
+    switch (event.type) {
+      case 'checkout.session.completed': {
+        const session = event.data.object as Stripe.CheckoutSession;
+        await handleCheckoutComplete(session);
+        break;
+      }
+      case 'customer.subscription.updated':
+      case 'customer.subscription.deleted': {
+        const sub = event.data.object as Stripe.Subscription;
+        await handleSubscriptionChange(sub);
+        break;
+      }
+      case 'invoice.payment_failed': {
+        const invoice = event.data.object as Stripe.Invoice;
+        await handlePaymentFailed(invoice);
+        break;
+      }
+    }
+
+    // Mark as processed
+    await db.webhookEvent.create({ data: { stripeEventId: event.id, type: event.type } });
+  } catch (error) {
+    console.error('[STRIPE_WEBHOOK]', event.type, error);
+    return Response.json({ error: 'Webhook handler failed' }, { status: 500 });
+  }
+
+  return Response.json({ received: true });
+}
+
+async function handleCheckoutComplete(session: Stripe.CheckoutSession) {
+  const userId = session.metadata?.userId;
+  if (!userId) throw new Error('No userId in session metadata');
+
+  const subscription = await stripe.subscriptions.retrieve(session.subscription as string);
+  await db.user.update({
+    where: { id: userId },
+    data: {
+      subscriptionId: subscription.id,
+      subscriptionStatus: subscription.status,
+      subscriptionPriceId: subscription.items.data[0].price.id,
+      subscriptionCurrentPeriodEnd: new Date(subscription.current_period_end * 1000),
+    },
+  });
+}
+
+async function handleSubscriptionChange(sub: Stripe.Subscription) {
+  await db.user.update({
+    where: { stripeCustomerId: sub.customer as string },
+    data: {
+      subscriptionStatus: sub.status,
+      subscriptionPriceId: sub.items.data[0]?.price.id ?? null,
+      subscriptionCurrentPeriodEnd: new Date(sub.current_period_end * 1000),
+    },
+  });
+}
+
+async function handlePaymentFailed(invoice: Stripe.Invoice) {
+  // Send dunning email via Resend
+  const user = await db.user.findUnique({ where: { stripeCustomerId: invoice.customer as string } });
+  if (user) {
+    // await sendPaymentFailedEmail(user.email);
+    console.log('[PAYMENT_FAILED] User:', user.email);
+  }
+}
+\`\`\`
+
+### Verify
+- [ ] \`req.text()\` used (not \`req.json()\`) — signature breaks with json parsing
+- [ ] Signature verified BEFORE processing
+- [ ] Idempotency check — same event can arrive multiple times
+- [ ] All relevant event types handled: checkout.completed, subscription.updated, subscription.deleted, invoice.payment_failed
+- [ ] \`STRIPE_WEBHOOK_SECRET\` is the webhook endpoint secret (not API key)
+- [ ] Route excluded from auth middleware
+
+### Debug
+- 400 on webhook → almost always \`req.json()\` instead of \`req.text()\`
+- Duplicate subscription updates → missing idempotency check
+- Wrong secret → using API key instead of webhook endpoint secret (get it from Stripe dashboard → Webhooks → your endpoint)
+
+---
+
+## Subscription Gate (Feature Access)
+
+### Build
+\`\`\`typescript
+// src/lib/subscription.ts
+export type SubscriptionStatus = 'active' | 'trialing' | 'past_due' | 'canceled' | 'unpaid';
+
+export function isSubscriptionActive(status: SubscriptionStatus | null): boolean {
+  return status === 'active' || status === 'trialing';
+}
+
+// Usage in Server Component
+const user = await db.user.findUnique({ where: { clerkId: userId } });
+if (!isSubscriptionActive(user?.subscriptionStatus)) {
+  redirect('/pricing?reason=subscription_required');
+}
+
+// Usage in API route
+if (!isSubscriptionActive(user?.subscriptionStatus)) {
+  return Response.json({ error: 'Subscription required', code: 'SUBSCRIPTION_REQUIRED' }, { status: 403 });
+}
+\`\`\`
+
+### Verify
+- [ ] Check subscription in DB — never trust client-side claims
+- [ ] \`trialing\` treated same as \`active\` for access
+- [ ] \`past_due\` shows warning but doesn't fully lock out (give grace period)
+- [ ] Redirect includes reason param so pricing page can show contextual message
+
+---
+
+## Customer Billing Portal
+
+### Build
+\`\`\`typescript
+// app/api/billing/portal/route.ts
+export async function POST(req: Request) {
+  const { userId } = auth();
+  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const user = await db.user.findUnique({ where: { clerkId: userId } });
+  if (!user?.stripeCustomerId) {
+    return Response.json({ error: 'No billing account found' }, { status: 404 });
+  }
+
+  const session = await stripe.billingPortal.sessions.create({
+    customer: user.stripeCustomerId,
+    return_url: \`\${process.env.NEXT_PUBLIC_APP_URL}/dashboard/settings\`,
+  });
+
+  return Response.json({ url: session.url });
+}
+\`\`\`
+
+### Verify
+- [ ] Customer portal enabled in Stripe dashboard settings
+- [ ] \`return_url\` uses env var
+- [ ] User has \`stripeCustomerId\` before attempting (guard against new users)
+`;
+}
+;
+// ---------------------------------------------------------------------------
+// Prompts UI, API, Deployment, Email, Analytics, Security
+// ---------------------------------------------------------------------------
+function uiPrompts(stack) {
+    return `# UI Prompts
+
+## New Page / Route
+
+### Build
+\`\`\`typescript
+// app/dashboard/posts/page.tsx
+import { auth } from '@clerk/nextjs/server';
+import { redirect } from 'next/navigation';
+import { db } from '@/lib/db';
+
+export const metadata = { title: 'Posts | MyApp' };
+
+export default async function PostsPage() {
+  const { userId } = auth();
+  if (!userId) redirect('/sign-in');
+
+  const posts = await db.post.findMany({
+    where: { authorId: userId, deletedAt: null },
+    orderBy: { createdAt: 'desc' },
+    take: 20,
+  });
+
+  return (
+    <div className="container mx-auto py-8">
+      <h1 className="text-2xl font-bold mb-6">Posts</h1>
+      {posts.length === 0 ? (
+        <EmptyState message="No posts yet" action={{ label: 'Create post', href: '/dashboard/posts/new' }} />
+      ) : (
+        <PostList posts={posts} />
+      )}
+    </div>
+  );
+}
+\`\`\`
+
+### Verify
+- [ ] Auth check at top (before any DB query)
+- [ ] \`metadata\` exported for SEO
+- [ ] Empty state handled
+- [ ] Loading state (add \`loading.tsx\` sibling file if needed)
+- [ ] Error state (add \`error.tsx\` sibling file if needed)
+- [ ] Paginated if list could exceed 20 items
+
+### Debug
+- Page flickers on load → missing Suspense boundary, wrap async component
+- Auth redirecting logged-in users → middleware matcher too broad
+
+---
+
+## Form with Server Action
+
+### Build
+\`\`\`typescript
+// app/dashboard/posts/new/page.tsx + actions/posts.ts
+
+// actions/posts.ts
+'use server';
+import { auth } from '@clerk/nextjs/server';
+import { z } from 'zod';
+import { db } from '@/lib/db';
+import { revalidatePath } from 'next/cache';
+
+const CreatePostSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+});
+
+export async function createPost(formData: FormData) {
+  const { userId } = auth();
+  if (!userId) return { error: 'Unauthorized' };
+
+  const raw = { title: formData.get('title'), content: formData.get('content') };
+  const parsed = CreatePostSchema.safeParse(raw);
+  if (!parsed.success) return { error: parsed.error.flatten().fieldErrors };
+
+  const post = await db.post.create({
+    data: { ...parsed.data, authorId: userId },
+  });
+
+  revalidatePath('/dashboard/posts');
+  return { success: true, postId: post.id };
+}
+
+// Component
+'use client';
+import { useTransition } from 'react';
+import { createPost } from '@/actions/posts';
+
+export function CreatePostForm() {
+  const [isPending, startTransition] = useTransition();
+  const [error, setError] = useState<string | null>(null);
+
+  function handleSubmit(formData: FormData) {
+    startTransition(async () => {
+      const result = await createPost(formData);
+      if (result.error) setError(typeof result.error === 'string' ? result.error : 'Validation failed');
+    });
+  }
+
+  return (
+    <form action={handleSubmit} className="space-y-4">
+      <input name="title" required className="w-full border rounded px-3 py-2" />
+      <textarea name="content" required className="w-full border rounded px-3 py-2" />
+      {error && <p className="text-red-500 text-sm">{error}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create Post'}
+      </button>
+    </form>
+  );
+}
+\`\`\`
+
+### Verify
+- [ ] Server Action has auth check at top
+- [ ] Zod validation on server (never trust client-side validation alone)
+- [ ] \`revalidatePath\` called after mutation to refresh cached data
+- [ ] Loading state shown while pending
+- [ ] Error displayed to user (not just console.log)
+- [ ] No \`<form>\` with \`method="post"\` — use Server Actions
+
+---
+
+## Data Table with Pagination
+
+### Build
+\`\`\`typescript
+// Use URL search params for pagination state (shareable, no useState)
+// app/dashboard/posts/page.tsx
+
+export default async function PostsPage({ searchParams }: { searchParams: { page?: string } }) {
+  const page = Number(searchParams.page ?? 1) - 1;
+  const pageSize = 20;
+
+  const [posts, total] = await Promise.all([
+    db.post.findMany({
+      where: { deletedAt: null },
+      orderBy: { createdAt: 'desc' },
+      take: pageSize,
+      skip: page * pageSize,
+    }),
+    db.post.count({ where: { deletedAt: null } }),
+  ]);
+
+  const totalPages = Math.ceil(total / pageSize);
+
+  return (
+    <div>
+      <PostTable posts={posts} />
+      <Pagination currentPage={page + 1} totalPages={totalPages} />
+    </div>
+  );
+}
+\`\`\`
+
+### Verify
+- [ ] Pagination uses URL params (not useState) — shareable URLs
+- [ ] Total count fetched in parallel with data (\`Promise.all\`)
+- [ ] Page out of range handled gracefully (redirect to page 1)
+- [ ] Empty state shown when no results
+
+---
+
+## Loading & Error States
+
+### Build
+\`\`\`typescript
+// app/dashboard/posts/loading.tsx — automatic Suspense fallback
+export default function Loading() {
+  return <PostTableSkeleton />;
+}
+
+// app/dashboard/posts/error.tsx — catches thrown errors
+'use client';
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div className="text-center py-12">
+      <p className="text-red-500 mb-4">Something went wrong</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+\`\`\`
+
+### Verify
+- [ ] Every async page has a \`loading.tsx\` sibling
+- [ ] Every page that fetches data has an \`error.tsx\` sibling
+- [ ] Skeleton matches layout of loaded content (prevents layout shift)
+`;
+}
+;
+function apiPrompts(stack) {
+    return `# API Prompts
+
+## New Route Handler
+
+### Build
+\`\`\`typescript
+// app/api/posts/route.ts
+import { auth } from '@clerk/nextjs/server';
+import { z } from 'zod';
+import { db } from '@/lib/db';
+
+const CreatePostSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().optional(),
+});
+
+export async function POST(req: Request) {
+  // 1. Auth
+  const { userId } = auth();
+  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 });
+
+  // 2. Parse & validate
+  let body: unknown;
+  try { body = await req.json(); }
+  catch { return Response.json({ error: 'Invalid JSON' }, { status: 400 }); }
+
+  const parsed = CreatePostSchema.safeParse(body);
+  if (!parsed.success) {
+    return Response.json({ error: 'Validation failed', details: parsed.error.flatten() }, { status: 422 });
+  }
+
+  // 3. Business logic
+  const post = await db.post.create({
+    data: { ...parsed.data, authorId: userId },
+    select: { id: true, title: true, createdAt: true },
+  });
+
+  return Response.json({ data: post }, { status: 201 });
+}
+
+export async function GET(req: Request) {
+  const { userId } = auth();
+  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 });
+
+  const { searchParams } = new URL(req.url);
+  const page = Number(searchParams.get('page') ?? 1) - 1;
+
+  const posts = await db.post.findMany({
+    where: { authorId: userId, deletedAt: null },
+    orderBy: { createdAt: 'desc' },
+    take: 20,
+    skip: page * 20,
+    select: { id: true, title: true, published: true, createdAt: true },
+  });
+
+  return Response.json({ data: posts });
+}
+\`\`\`
+
+### Verify
+- [ ] Auth check is first line (before JSON parsing)
+- [ ] JSON parse wrapped in try/catch
+- [ ] Zod validation with specific error response
+- [ ] Returns \`{ data: T }\` on success, \`{ error: string }\` on failure
+- [ ] Correct HTTP status codes (201 for create, 200 for get, 422 for validation, 401/403 for auth)
+- [ ] Only returns fields needed (\`select\`)
+
+### Debug
+- 400 on valid request → JSON parse issue, check Content-Type header sent by client
+- Zod errors not showing → not returning \`parsed.error.flatten()\` in response
+- Auth passing but DB query wrong user's data → using \`userId\` from Clerk but querying with DB \`id\` (join on clerkId first)
+`;
+}
+;
+function deploymentPrompts(stack) {
+    return `# Deployment Prompts
+
+## Add Cron Job (Railway)
+
+### Build
+1. In Railway dashboard: New Service → Cron
+2. Set schedule (standard cron syntax)
+3. Set command: \`curl -X GET https://yourapp.com/api/cron/job-name -H "x-cron-secret: $CRON_SECRET"\`
+
+\`\`\`typescript
+// app/api/cron/[job]/route.ts
+export async function GET(req: Request, { params }: { params: { job: string } }) {
+  // Auth
+  const secret = req.headers.get('x-cron-secret');
+  if (secret !== process.env.CRON_SECRET) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const startTime = Date.now();
+  console.log(\`[CRON:\${params.job}] Starting\`);
+
+  try {
+    switch (params.job) {
+      case 'send-digests':
+        await sendWeeklyDigests();
+        break;
+      case 'expire-trials':
+        await expireTrials();
+        break;
+      default:
+        return Response.json({ error: 'Unknown job' }, { status: 404 });
+    }
+
+    const duration = Date.now() - startTime;
+    console.log(\`[CRON:\${params.job}] Done in \${duration}ms\`);
+    return Response.json({ success: true, duration });
+  } catch (error) {
+    console.error(\`[CRON:\${params.job}] Failed\`, error);
+    return Response.json({ error: 'Job failed' }, { status: 500 });
+  }
+}
+\`\`\`
+
+### Verify
+- [ ] \`CRON_SECRET\` set in Railway env vars
+- [ ] Job is idempotent (safe to run multiple times)
+- [ ] Execution time logged
+- [ ] Error logged with full context
+- [ ] Route in public routes (not behind auth middleware)
+- [ ] Job name validated (no default fallthrough)
+
+### Debug
+- 401 on cron → \`CRON_SECRET\` env var not set in Railway, or secret mismatch
+- Job runs but does nothing → check idempotency logic isn't skipping everything
+- Timeout → Railway cron has 10min timeout, split large jobs into batches
+
+---
+
+## New Environment Variable
+
+### Build
+1. Add to \`.env.example\` (with fake value — never real credentials)
+2. Add to \`.env.local\` (real dev value — gitignored)
+3. Add to Railway dashboard under service → Variables
+4. Add to \`src/env.ts\` validation (if using t3-env or similar)
+
+\`\`\`typescript
+// src/env.ts — validate all env vars at startup
+import { z } from 'zod';
+
+const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  CRON_SECRET: z.string().min(32),
+  RESEND_API_KEY: z.string().startsWith('re_'),
+  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
+  STRIPE_WEBHOOK_SECRET: z.string().startsWith('whsec_'),
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+  NEXT_PUBLIC_GA_MEASUREMENT_ID: z.string().startsWith('G-').optional(),
+});
+
+export const env = envSchema.parse(process.env);
+\`\`\`
+
+### Verify
+- [ ] Added to \`.env.example\` with placeholder
+- [ ] Added to Railway dashboard (staging + prod environments separately if applicable)
+- [ ] Validated in \`src/env.ts\` startup check
+- [ ] \`NEXT_PUBLIC_\` prefix only for vars that must be client-accessible
+- [ ] Never committed real values to git
+
+### Debug
+- Undefined in production → added to \`.env.local\` but not Railway dashboard
+- Client component getting undefined → missing \`NEXT_PUBLIC_\` prefix
+`;
+}
+;
+function emailPrompts(stack) {
+    return `# Email Prompts
+
+## Send Transactional Email
+
+### Build
+\`\`\`typescript
+// src/lib/send-email.ts — wrapper with logging
+import { resend } from '@/lib/email';
+
+interface SendEmailOptions {
+  to: string;
+  subject: string;
+  react: React.ReactElement;
+  userId?: string; // for logging
+  type: string;    // for logging
+}
+
+export async function sendEmail({ to, subject, react, userId, type }: SendEmailOptions) {
+  try {
+    const { data, error } = await resend.emails.send({
+      from: process.env.EMAIL_FROM!,
+      to,
+      subject,
+      react,
+    });
+
+    if (error) {
+      console.error(\`[EMAIL:\${type}] Failed\`, { error, to, userId });
+      return { success: false, error };
+    }
+
+    console.log(\`[EMAIL:\${type}] Sent\`, { id: data?.id, to, userId });
+    return { success: true, id: data?.id };
+  } catch (err) {
+    console.error(\`[EMAIL:\${type}] Exception\`, { err, to, userId });
+    return { success: false, error: err };
+  }
+}
+
+// Usage — never block the main flow on email
+const emailResult = await sendEmail({
+  to: user.email,
+  subject: 'Welcome!',
+  react: <WelcomeEmail name={user.name} />,
+  userId: user.id,
+  type: 'welcome',
+});
+// Continue even if email fails — log but don't throw
+\`\`\`
+
+### Verify
+- [ ] Called from server only (Server Action, API route, webhook handler)
+- [ ] Never blocks the user-facing response — fire after main operation succeeds
+- [ ] Errors logged with context but not thrown
+- [ ] \`EMAIL_FROM\` uses env var (domain verified in Resend)
+- [ ] \`type\` field used for log filtering
+
+### Debug
+- Emails not arriving → check Resend dashboard logs, verify domain DNS records
+- "From address not verified" → domain not verified in Resend, check DNS TXT/DKIM records
+- Email in spam → missing DKIM records, check Cloudflare DNS (must be grey cloud, not proxied)
+
+---
+
+## New Email Template
+
+### Build
+\`\`\`typescript
+// src/emails/payment-failed.tsx
+import {
+  Html, Head, Body, Container, Heading,
+  Text, Button, Hr
+} from '@react-email/components';
+
+interface PaymentFailedEmailProps {
+  userName: string;
+  updatePaymentUrl: string;
+}
+
+export function PaymentFailedEmail({ userName, updatePaymentUrl }: PaymentFailedEmailProps) {
+  return (
+    <Html>
+      <Head />
+      <Body style={{ fontFamily: 'sans-serif', backgroundColor: '#f9f9f9' }}>
+        <Container style={{ maxWidth: '560px', margin: '0 auto', padding: '40px 20px' }}>
+          <Heading>Payment failed</Heading>
+          <Text>Hi {userName},</Text>
+          <Text>
+            We couldn't process your payment. Please update your payment method
+            to continue using the service.
+          </Text>
+          <Button href={updatePaymentUrl} style={{ backgroundColor: '#000', color: '#fff', padding: '12px 24px' }}>
+            Update payment method
+          </Button>
+          <Hr />
+          <Text style={{ fontSize: '12px', color: '#666' }}>
+            If you have questions, reply to this email.
+          </Text>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+\`\`\`
+
+### Verify
+- [ ] Props are typed (no \`any\`)
+- [ ] Preview with \`email.react\` package: \`pnpm email dev\`
+- [ ] Mobile-friendly (single column, large tap targets)
+- [ ] Fallback plain text (Resend handles this automatically)
+- [ ] No tracking pixels unless consent obtained
+`;
+}
+;
+function analyticsPrompts(stack) {
+    return `# Analytics Prompts
+
+## Track Custom Event (GA4)
+
+### Build
+\`\`\`typescript
+// src/lib/analytics.ts
+export function trackEvent(event: {
+  action: string;
+  category: string;
+  label?: string;
+  value?: number;
+}) {
+  if (typeof window === 'undefined') return;
+  if (!process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID) return;
+
+  window.gtag('event', event.action, {
+    event_category: event.category,
+    event_label: event.label,
+    value: event.value,
+  });
+}
+
+// Standard events — use these names for GA4 reports
+export const events = {
+  signUp: (method: string) => trackEvent({ action: 'sign_up', category: 'auth', label: method }),
+  login: (method: string) => trackEvent({ action: 'login', category: 'auth', label: method }),
+  beginCheckout: (plan: string) => trackEvent({ action: 'begin_checkout', category: 'ecommerce', label: plan }),
+  purchase: (plan: string, value: number) => trackEvent({ action: 'purchase', category: 'ecommerce', label: plan, value }),
+  featureUsed: (feature: string) => trackEvent({ action: 'feature_used', category: 'engagement', label: feature }),
+  cancelSubscription: () => trackEvent({ action: 'cancel_subscription', category: 'billing' }),
+};
+\`\`\`
+
+### Verify
+- [ ] \`typeof window !== 'undefined'\` guard (runs in Server Components too)
+- [ ] Event names match GA4 recommended event names where possible
+- [ ] No PII in event labels (no emails, names, IDs)
+- [ ] Only fires if GA Measurement ID is present (safe in preview/dev)
+
+### Debug
+- Events not showing in GA4 → check real-time report in GA4 (takes up to 24h for standard reports)
+- Blocked by ad blocker → use GA4 Measurement Protocol for server-side events instead
+- \`gtag is not defined\` → GA script not loaded, check layout.tsx Script tags
+`;
+}
+;
+function securityPrompts(stack) {
+    return `# Security Prompts
+
+## Input Validation (All Entry Points)
+
+### Build
+\`\`\`typescript
+// Every API route and Server Action validates ALL inputs with Zod
+// Never trust: req.body, req.query, req.params, formData, searchParams
+
+import { z } from 'zod';
+
+// Strict schemas — reject anything unexpected
+const schema = z.object({
+  email: z.string().email().toLowerCase(),
+  name: z.string().min(1).max(100).trim(),
+  amount: z.number().int().positive().max(100_000), // cents
+  role: z.enum(['user', 'viewer']), // never accept 'admin' from input
+});
+
+// File uploads
+const fileSchema = z.object({
+  size: z.number().max(5 * 1024 * 1024), // 5MB max
+  type: z.enum(['image/jpeg', 'image/png', 'image/webp']),
+});
+\`\`\`
+
+### Verify
+- [ ] All API routes validate with Zod
+- [ ] Roles can never be escalated via input (never accept \`role: 'admin'\` from request)
+- [ ] String lengths bounded (prevents oversized payload attacks)
+- [ ] Email lowercased and trimmed
+- [ ] File uploads: size + mime type validated server-side
+
+---
+
+## Secure Direct Object References
+
+### Build
+\`\`\`typescript
+// ALWAYS scope queries to the current user's data
+// Never trust a resource ID without verifying ownership
+
+// ❌ Wrong — IDOR vulnerability
+const post = await db.post.findUnique({ where: { id: postId } });
+
+// ✅ Correct — always include userId in where clause
+const post = await db.post.findUnique({
+  where: { id: postId, authorId: userId }, // fails if not owner
+});
+
+if (!post) return Response.json({ error: 'Not found' }, { status: 404 });
+// Note: return 404, not 403 — don't reveal resource existence
+\`\`\`
+
+### Verify
+- [ ] Every query for user-owned data includes \`userId\` in where clause
+- [ ] Returns 404 (not 403) when resource not found or not owned
+- [ ] Admin endpoints have separate admin-only middleware
+
+---
+
+## Rate Limiting
+
+### Build
+\`\`\`typescript
+// Use Cloudflare for coarse rate limiting (set in dashboard)
+// Use in-memory or Upstash Redis for fine-grained app-level limits
+
+// Simple in-memory rate limiter (good for low traffic)
+const rateLimit = new Map<string, { count: number; resetAt: number }>();
+
+export function checkRateLimit(key: string, limit: number, windowMs: number): boolean {
+  const now = Date.now();
+  const entry = rateLimit.get(key);
+
+  if (!entry || now > entry.resetAt) {
+    rateLimit.set(key, { count: 1, resetAt: now + windowMs });
+    return true; // allowed
+  }
+
+  if (entry.count >= limit) return false; // blocked
+
+  entry.count++;
+  return true; // allowed
+}
+
+// Usage in API route
+const allowed = checkRateLimit(\`auth:\${ip}\`, 5, 60_000); // 5 per minute
+if (!allowed) {
+  return Response.json({ error: 'Too many requests' }, { status: 429 });
+}
+\`\`\`
+
+### Verify
+- [ ] Auth endpoints rate limited (sign-in, magic link, password reset)
+- [ ] Rate limit keyed by IP (for unauthed) or userId (for authed)
+- [ ] 429 returned with \`Retry-After\` header when possible
+- [ ] Cloudflare WAF rules set for aggressive bots (see cloudflare.md)
+`;
+}
+;
+// ---------------------------------------------------------------------------
+// Skills
+// ---------------------------------------------------------------------------
+function frontendSkill() {
+    return `# SKILL: Frontend Engineer
+
+> Load this at the start of a UI-heavy session.
+> Tell Claude: "Enter frontend mode" or "Load /ai-docs/skills/frontend.md"
+
+## Persona
+You are a senior frontend engineer. You think in components, user experience, and performance. You write clean, accessible, maintainable React code.
+
+## Priorities (in order)
+1. **Correctness** — does it work for all states (loading, error, empty, populated)?
+2. **Accessibility** — keyboard nav, ARIA labels, focus management
+3. **Performance** — no unnecessary re-renders, lazy load heavy components
+4. **Simplicity** — fewest components needed, no over-engineering
+
+## Defaults
+- Server Components unless you need client interactivity
+- Tailwind for all styling — never inline styles, never CSS modules
+- \`cn()\` (clsx + tailwind-merge) for conditional classes
+- \`useTransition\` for Server Actions (not \`useState\` + \`useEffect\` workarounds)
+- URL state for filters/pagination (not useState)
+- Zod validation in Server Actions — not just client-side
+
+## Component Checklist (before finishing)
+- [ ] Loading state handled
+- [ ] Error state handled  
+- [ ] Empty state handled
+- [ ] Mobile responsive (test at 375px)
+- [ ] Keyboard navigable
+- [ ] No hardcoded colors or spacing — Tailwind tokens only
+- [ ] TypeScript types complete (no \`any\`)
+
+## Common Mistakes to Avoid
+- \`useEffect\` to fetch data → use Server Component or React Query instead
+- useState for URL-based state → use searchParams
+- Prop drilling more than 2 levels → use context or Zustand
+- \`className\` string concatenation → use \`cn()\`
+- Missing \`key\` prop on lists
+- onClick on div → use button for accessibility
+
+## Token-Saving Mode
+When working on UI tasks:
+- Write the component first, then ask if you want tests
+- Don't explain every Tailwind class — just write them
+- Skip boilerplate comments unless asked
+- If the pattern is in /ai-docs/prompts/ui.md, follow it exactly — don't improvise
+`;
+}
+function backendSkill() {
+    return `# SKILL: Backend Engineer
+
+> Load this for API routes, database work, Server Actions, background jobs.
+> Tell Claude: "Enter backend mode" or "Load /ai-docs/skills/backend.md"
+
+## Persona
+You are a senior backend engineer. You think in data flow, correctness, and reliability. You write APIs that are secure by default, handle errors explicitly, and never trust user input.
+
+## Priorities (in order)
+1. **Security** — auth checked, input validated, ownership verified
+2. **Correctness** — handles all error states, atomic writes, idempotent operations
+3. **Performance** — indexed queries, paginated results, no N+1
+4. **Simplicity** — no premature abstraction, no over-engineering
+
+## Defaults
+- Validate everything with Zod — API routes AND Server Actions
+- Auth check is ALWAYS the first line of any handler
+- Transactions for multi-step writes
+- Soft deletes (deletedAt) for user data
+- Always paginate — never unbounded queries
+- Structured logging: \`console.error('[CONTEXT]', { userId, operation, error })\`
+
+## Response Shape (always consistent)
+\`\`\`typescript
+// Success
+{ data: T, error: null }    // or just Response.json({ data: T })
+
+// Error  
+{ data: null, error: { message: string, code: string } }
+\`\`\`
+
+## HTTP Status Codes
+- 200: success (GET, PUT, PATCH)
+- 201: created (POST)
+- 400: bad request (malformed JSON)
+- 401: unauthenticated (no session)
+- 403: unauthorized (wrong permissions / not owner)
+- 404: not found (use this even for "forbidden" to avoid IDOR)
+- 422: validation error (Zod failed)
+- 429: rate limited
+- 500: server error
+
+## Security Checklist (every endpoint)
+- [ ] Auth checked before any DB access
+- [ ] Input validated with Zod
+- [ ] Resource ownership verified (userId in where clause)
+- [ ] Returns 404 (not 403) for not-owned resources
+
+## Token-Saving Mode
+- Write the handler, then verify checklist items
+- Don't explain what each Zod field does
+- Follow /ai-docs/prompts/api.md patterns exactly
+- If it's a webhook, check /ai-docs/prompts/payments.md first
+`;
+}
+function devopsSkill() {
+    return `# SKILL: DevOps / Infrastructure
+
+> Load this for deployment, env vars, cron jobs, Railway config, Cloudflare.
+> Tell Claude: "Enter devops mode" or "Load /ai-docs/skills/devops.md"
+
+## Persona
+You are a senior DevOps engineer. You think in reliability, observability, and zero-downtime deploys. You treat configuration as code.
+
+## Stack
+- **Hosting:** Railway (web + postgres + cron)
+- **CDN/DNS:** Cloudflare
+- **Email:** Resend (transactional)
+- **Analytics:** GA4 + Google Search Console
+
+## Deployment Principles
+- Every env var validated at startup (fail fast, not silently)
+- Migrations run before the app starts (not after)
+- Health check at \`/api/health\` always available
+- Never store secrets in code or logs
+
+## Railway Checklist
+- [ ] \`DATABASE_URL\` linked from Railway PostgreSQL plugin (not hardcoded)
+- [ ] Start command includes migrations: \`pnpm db:migrate && pnpm start\`
+- [ ] Health check configured in Railway service settings
+- [ ] Custom domain added + SSL auto-generated
+- [ ] Cloudflare DNS pointing to Railway URL (proxied)
+
+## Cloudflare Checklist
+- [ ] SSL mode: Full (strict)
+- [ ] Cache rules set (static assets cached, /api/* bypassed)
+- [ ] Mail DNS records NOT proxied (Resend DKIM breaks behind Cloudflare proxy)
+- [ ] Security rules: rate limit /api/auth/signin
+
+## Cron Job Checklist
+- [ ] CRON_SECRET set (min 32 chars)
+- [ ] Job is idempotent
+- [ ] Job has timeout handling (Railway max: 10 min)
+- [ ] Job logs start time + duration
+- [ ] Railway cron service pointed at correct URL
+
+## Env Var Naming Convention
+\`\`\`
+DATABASE_URL              # always
+CRON_SECRET               # for cron auth
+STRIPE_SECRET_KEY         # sk_test_... / sk_live_...
+STRIPE_WEBHOOK_SECRET     # whsec_...
+RESEND_API_KEY            # re_...
+CLERK_SECRET_KEY          # sk_...
+CLERK_WEBHOOK_SECRET      # whsec_...
+NEXT_PUBLIC_APP_URL       # https://yourapp.com
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY   # pk_...
+NEXT_PUBLIC_GA_MEASUREMENT_ID       # G-XXXXXXX
+CLOUDFLARE_ZONE_ID        # for cache purge
+CLOUDFLARE_API_TOKEN      # scoped to cache purge only
+\`\`\`
+
+## Token-Saving Mode
+- Follow /ai-docs/deployment.md exactly
+- Don't explain Railway's UI — give the config values
+- List checklist items, don't prose-explain each one
+`;
+}
+function reviewerSkill() {
+    return `# SKILL: Code Reviewer
+
+> Load this when you want Claude to critically review code before shipping.
+> Tell Claude: "Review this as a senior engineer" or "Load /ai-docs/skills/reviewer.md"
+
+## Persona
+You are a principal engineer doing a pre-ship code review. You are thorough, specific, and constructive. You catch what junior engineers miss.
+
+## Review Order
+1. **Security holes** — auth missing, IDOR, unvalidated input, secret exposure
+2. **Correctness** — edge cases, error handling, race conditions
+3. **Performance** — N+1 queries, missing indexes, unbounded queries
+4. **Maintainability** — naming, complexity, duplication
+5. **Style** — only if everything above is clean
+
+## Security Red Flags (always call out)
+- Resource fetched without scoping to userId
+- Missing auth check in API route or Server Action
+- \`any\` type hiding a validation gap
+- User input used in DB query without Zod first
+- Secrets hardcoded or logged
+
+## Correctness Red Flags
+- Missing loading/error/empty states
+- \`useEffect\` with missing dependencies
+- Mutation without \`revalidatePath\` (stale cache)
+- Webhook without idempotency check
+- Multi-step write without transaction
+
+## Output Format
+For each issue:
+\`\`\`
+🔴 CRITICAL (Security/Data loss): [issue] → [fix]
+🟡 WARNING (Correctness/Performance): [issue] → [fix]  
+🟢 SUGGESTION (Style/Maintainability): [issue] → [fix]
+\`\`\`
+
+Only show 🟢 if there are no 🔴 or 🟡 issues.
+Stop at 🔴 — fix security issues before reviewing anything else.
+
+## Token-Saving Mode
+- Lead with the most critical issue
+- Don't compliment the code
+- Don't explain why security matters — just state the issue and fix
+- If code is clean, say "Looks good — no issues found" and stop
+`;
+}
+// ---------------------------------------------------------------------------
+// Extras (Security, Handover, Mistakes, Token Rules)
+// ---------------------------------------------------------------------------
+function securityDoc(stack) {
+    return `# Security
+
+## OWASP Top 10 — Applied to This Stack
+
+### A01 Broken Access Control
+**Risk:** User accesses another user's data by guessing IDs
+**Protection:**
+- Always include \`userId\` in DB queries for user-owned data
+- Return 404 (not 403) when resource not owned — don't reveal existence
+- Admin routes protected by role check, not just auth check
+- Test: log in as user A, try to access user B's resource by ID
+
+### A02 Cryptographic Failures
+**Risk:** Sensitive data exposed in logs, responses, or storage
+**Protection:**
+- Never log: passwords, tokens, full credit card numbers, SSNs
+- Never return: password hashes, internal IDs, raw Stripe keys
+- DB connection over SSL (Railway enforces this)
+- Env vars for all secrets — never in code
+
+### A03 Injection
+**Risk:** SQL injection via unsanitized input
+**Protection:** Prisma/Drizzle parameterize all queries automatically
+**Watch out for:** Raw SQL with template literals — use \`prisma.$queryRaw\` tag safely:
+\`\`\`typescript
+// ❌ Vulnerable
+prisma.$queryRawUnsafe(\`SELECT * FROM users WHERE id = '\${userId}'\`);
+
+// ✅ Safe
+prisma.$queryRaw\`SELECT * FROM users WHERE id = \${userId}\`;
+\`\`\`
+
+### A04 Insecure Design
+**Risk:** Business logic flaws (negative balances, skipping payment, etc.)
+**Protection:**
+- Validate business rules server-side: check credits before spending, check subscription before access
+- Use transactions for multi-step operations (can't spend credits without creating the job)
+- Never trust client on anything financial
+
+### A05 Security Misconfiguration
+**Risk:** Debug info exposed, unnecessary features enabled
+**Checklist:**
+- [ ] \`NODE_ENV=production\` in Railway
+- [ ] No \`.env\` files committed
+- [ ] Error responses don't expose stack traces (check production error responses)
+- [ ] Stripe in live mode (not test mode) in production
+- [ ] Clerk in production instance (not development)
+
+### A07 Identification & Authentication Failures
+**Risk:** Brute force, session fixation, credential stuffing
+**Protection:**
+- Clerk handles session management (don't roll your own)
+- Rate limit auth endpoints: 5 attempts per minute per IP (Cloudflare rule)
+- Magic link / OTP expiry: 15 minutes max
+- Never store session tokens in localStorage
+
+### A08 Software & Data Integrity
+**Risk:** Supply chain attacks via npm packages
+**Protection:**
+- Lock file committed (\`pnpm-lock.yaml\`)
+- Stripe webhook signature verified before processing
+- Clerk webhook (Svix) signature verified before processing
+
+### A09 Security Logging & Monitoring
+**What to log:**
+\`\`\`typescript
+// Auth events
+console.log('[AUTH]', { event: 'sign_in', userId, ip, method });
+console.error('[AUTH_FAIL]', { event: 'invalid_token', ip });
+
+// Financial events
+console.log('[BILLING]', { event: 'subscription_created', userId, plan, stripeSubId });
+console.error('[BILLING_FAIL]', { event: 'payment_failed', userId, invoiceId });
+
+// Security events
+console.error('[SECURITY]', { event: 'invalid_webhook_sig', source: 'stripe', ip });
+console.error('[SECURITY]', { event: 'rate_limit_exceeded', ip, endpoint });
+\`\`\`
+
+---
+
+## STRIDE Threat Model
+
+| Threat | Example | Mitigation |
+|--------|---------|------------|
+| **S**poofing | Faking another user's session | Clerk session management, verify userId server-side |
+| **T**ampering | Modifying request body to escalate role | Zod validation, never accept role from input |
+| **R**epudiation | User denies making a purchase | Stripe webhook log + DB WebhookEvent table |
+| **I**nfo Disclosure | Error leaks stack trace or DB schema | Generic error messages in production |
+| **D**oS | Flood API with requests | Cloudflare rate limiting + app-level rate limiter |
+| **E**levation | User accesses admin endpoints | Role check in admin middleware, not just auth |
+
+---
+
+## Pre-Ship Security Checklist
+
+### Authentication
+- [ ] All protected routes behind auth middleware
+- [ ] Webhook endpoints excluded from auth middleware
+- [ ] No auth secrets in client-side code (\`NEXT_PUBLIC_\`)
+
+### Authorization
+- [ ] Every DB query for user data scoped to \`userId\`
+- [ ] Admin-only operations check \`role === 'admin'\`
+- [ ] Resource not found = 404, not 403
+
+### Input
+- [ ] All API routes validate with Zod
+- [ ] All Server Actions validate with Zod
+- [ ] File uploads: size + mime type validated
+
+### Financial
+- [ ] Stripe webhook signature verified
+- [ ] Checkout session created server-side only
+- [ ] Subscription status checked from DB, never client
+
+### Secrets
+- [ ] \`.env\` in \`.gitignore\`
+- [ ] No secrets in client bundle
+- [ ] All secrets in Railway env vars
+`;
+}
+function handoverTemplate() {
+    return `# HANDOVER.md — Session Handover
+
+> Claude writes this at the end of a long session (or when asked).
+> The next session loads this file to resume instantly without re-exploration.
+> Command: "Write a handover doc for this session"
+
+---
+
+## Session Date
+[Date]
+
+## What We Were Building
+[1-2 sentence description of the feature/fix being worked on]
+
+## Current Status
+- [ ] **In progress** / **Completed** / **Blocked**
+- [What is done]
+- [What is NOT done yet]
+
+## Files Changed This Session
+\`\`\`
+src/app/dashboard/posts/page.tsx     - Added pagination
+src/actions/posts.ts                  - Added createPost Server Action
+src/components/PostList.tsx           - New component
+prisma/schema.prisma                  - Added Post model
+\`\`\`
+
+## Next Steps (in order)
+1. [First thing to do next session]
+2. [Second thing]
+3. [Third thing]
+
+## Decisions Made
+- [Decision]: [Reasoning] — e.g. "Used Server Actions over API routes: simpler, fewer files"
+- [Decision]: [Reasoning]
+
+## Blockers / Questions
+- [Any unresolved question or blocker]
+
+## Context to Load Next Session
+\`\`\`
+Read CLAUDE.md
+Read ai-docs/[relevant domain].md
+Read ai-docs/prompts/[relevant category].md
+Read HANDOVER.md
+Then continue from: [exact next step]
+\`\`\`
+
+---
+*Tip: Start next session with "Load HANDOVER.md and continue where we left off"*
+`;
+}
+function mistakesTemplate() {
+    return `# MISTAKES.md — Learn From These
+
+> Before starting any task, check if it's listed here.
+> Claude: if you're about to do something in this list, stop and do it the right way instead.
+> Add new mistakes here when they're discovered.
+
+## How to Add an Entry
+When Claude makes a mistake, add:
+\`\`\`
+### [Short title]
+**Mistake:** What was done wrong
+**Why it fails:** What breaks or why it's wrong
+**Correct approach:** What to do instead
+\`\`\`
+
+---
+
+## Auth
+
+### Using req.json() in Stripe Webhook Handler
+**Mistake:** \`const body = await req.json()\`
+**Why it fails:** Parses body before signature verification, destroys raw body — always 400
+**Correct approach:** \`const body = await req.text()\` — then verify signature, then parse
+
+### Redirecting API Routes Instead of Returning 401
+**Mistake:** \`redirect('/sign-in')\` in an API route handler
+**Why it fails:** Client gets a redirect response, not JSON — breaks fetch() callers
+**Correct approach:** \`return Response.json({ error: 'Unauthorized' }, { status: 401 })\`
+
+---
+
+## Database
+
+### Forgetting to Run prisma generate After Schema Change
+**Mistake:** Changing \`schema.prisma\` and running the app without regenerating client
+**Why it fails:** TypeScript types don't match new schema, runtime errors on new fields
+**Correct approach:** Always run \`pnpm prisma generate\` after any schema change
+
+### Unbounded Queries
+**Mistake:** \`db.post.findMany()\` with no \`take\` limit
+**Why it fails:** Returns all rows — kills performance, high DB cost
+**Correct approach:** Always add \`take: 20\` and pagination
+
+---
+
+## Payments
+
+### Wrong Webhook Secret
+**Mistake:** Using Stripe API key as webhook secret
+**Why it fails:** \`sk_...\` is the API key — webhook secret is \`whsec_...\` from the webhook endpoint page
+**Correct approach:** Get the secret from Stripe Dashboard → Webhooks → your endpoint → Signing secret
+
+---
+
+## Deployment
+
+### Adding Env Var to .env.local But Not Railway
+**Mistake:** Works locally, undefined in production
+**Why it fails:** Railway has its own env var store, separate from local files
+**Correct approach:** Add to Railway dashboard (service → Variables) AND .env.example
+
+---
+
+## Next.js
+
+### Calling currentUser() When Only userId Is Needed
+**Mistake:** \`const user = await currentUser()\` just to get the ID
+**Why it fails:** Makes an extra network request to Clerk on every request — wastes time + money
+**Correct approach:** \`const { userId } = auth()\` — only call \`currentUser()\` when you need name/email/etc.
+
+### Missing revalidatePath After Mutation
+**Mistake:** Server Action mutates DB but doesn't call \`revalidatePath\`
+**Why it fails:** Next.js cache not invalidated — UI shows stale data
+**Correct approach:** Always call \`revalidatePath('/relevant/path')\` at end of Server Action
+`;
+}
+function tokenRulesDoc() {
+    return `# TOKEN-RULES.md — Stay Lean
+
+> Claude reads this at the start of sessions to minimize token waste.
+> These rules override default verbosity.
+
+## Core Rule
+**Do less. Say less. Ask before adding.**
+
+Every unnecessary token costs money and eats into rate limits.
+Follow these rules every session.
+
+---
+
+## Response Rules
+
+### Be Terse
+- Answer the question asked — nothing more
+- Skip preamble: "Great question!" / "Sure, I can help with that" — just start
+- Skip postamble: "Let me know if you need anything else!" — just stop
+- Skip explaining obvious things: don't explain what Tailwind does, what TypeScript is
+
+### Code First
+- Write code immediately, explain only what's non-obvious
+- Don't describe what you're about to write — just write it
+- Don't re-show code that hasn't changed
+
+### Don't Gold-Plate
+- Build exactly what was asked — no "bonus" features
+- Don't add error handling that wasn't asked for (but do add it if it's critical)
+- Don't refactor adjacent code that wasn't mentioned
+- Don't add tests unless asked
+
+### Don't Re-Explain the Codebase
+- CLAUDE.md was already loaded — don't re-describe the stack
+- If you've already established a pattern, follow it silently
+- Don't say "as we discussed" — just use the established pattern
+
+---
+
+## Session Rules
+
+### Load Context Surgically
+- Load ONE domain doc at a time — only what the current task needs
+- Don't load all of /ai-docs/ at session start — load on demand
+- After finishing a task domain, you can stop referencing that doc
+
+### Check Before Exploring
+- Before reading multiple files to understand the codebase, ask: "Which file handles X?"
+- Don't grep the entire repo when you can ask
+- Don't read a file "just in case" — only read files directly relevant to the task
+
+### When Stuck, Ask — Don't Spiral
+- If uncertain about an approach, ask one clarifying question
+- Don't write 3 alternative implementations and ask which to use
+- Don't explore 5 files hunting for context — ask where to look
+
+---
+
+## Mistakes That Waste Tokens
+
+| Mistake | Cost | Fix |
+|---------|------|-----|
+| Re-reading CLAUDE.md mid-session | ~500 tokens | Trust the loaded context |
+| Explaining the stack after it's established | ~200 tokens | Skip it |
+| Writing 3 versions of the same code | 3x tokens | Write one, confirm approach first if unsure |
+| Exploring unrelated files | Variable | Ask which file to look at |
+| Long error explanations | ~300 tokens | State error + fix, skip the lecture |
+| Adding unasked features | Variable | Ask before adding |
+
+---
+
+## When to Ask vs Just Do
+
+**Just do it (no asking needed):**
+- Task is unambiguous
+- Pattern exists in /ai-docs/prompts/
+- You've done this before in the session
+
+**Ask first (one question max):**
+- Two valid approaches with different tradeoffs
+- The task scope is unclear
+- A decision will be hard to reverse
+
+**Never ask:**
+- "Should I add comments?" — no, unless the code is complex
+- "Want me to add tests?" — only if testing was mentioned
+- "Would you like me to refactor?" — only if asked
+`;
+}
+// ---------------------------------------------------------------------------
+// Domain Doc Templates
+// ---------------------------------------------------------------------------
+function claudeMd(stack, answers) {
+    const pm = stack.packageManager || 'npm';
+    const run = (script) => pm === 'npm' ? `npm run ${script}` : `${pm} ${script}`;
+    const lines = [];
+    lines.push(`# CLAUDE.md — AI Context for ${stack.name}`);
+    lines.push('');
+    lines.push('> This file is automatically loaded by Claude Code every session.');
+    lines.push('> Keep it under 300 tokens. For deeper context, see /ai-docs/.');
+    lines.push('');
+    // Project
+    lines.push('## Project');
+    lines.push(`**Name:** ${stack.name}`);
+    lines.push(`**Description:** ${answers.description}`);
+    if (stack.framework)
+        lines.push(`**Framework:** ${stack.framework}`);
+    if (stack.language)
+        lines.push(`**Language:** ${stack.language}`);
+    if (stack.database)
+        lines.push(`**Database:** ${stack.database}`);
+    if (stack.auth)
+        lines.push(`**Auth:** ${stack.auth}`);
+    if (stack.payments)
+        lines.push(`**Payments:** ${stack.payments}`);
+    if (stack.styling)
+        lines.push(`**Styling:** ${stack.styling}`);
+    if (stack.testing)
+        lines.push(`**Testing:** ${stack.testing}`);
+    if (stack.extras.length > 0)
+        lines.push(`**Extras:** ${stack.extras.join(', ')}`);
+    lines.push('');
+    // Commands
+    if (Object.keys(stack.commands).length > 0) {
+        lines.push('## Key Commands');
+        if (stack.commands.dev)
+            lines.push(`- **Dev:** \`${stack.commands.dev}\``);
+        if (stack.commands.build)
+            lines.push(`- **Build:** \`${stack.commands.build}\``);
+        if (stack.commands.test)
+            lines.push(`- **Test:** \`${stack.commands.test}\``);
+        if (stack.commands.lint)
+            lines.push(`- **Lint:** \`${stack.commands.lint}\``);
+        if (stack.commands.dbPush)
+            lines.push(`- **DB push:** \`${stack.commands.dbPush}\``);
+        if (stack.commands.dbMigrate)
+            lines.push(`- **DB migrate:** \`${stack.commands.dbMigrate}\``);
+        if (stack.commands.dbStudio)
+            lines.push(`- **DB studio:** \`${stack.commands.dbStudio}\``);
+        lines.push('');
+    }
+    // Conventions
+    if (answers.conventions && answers.conventions.length > 0) {
+        lines.push('## Coding Conventions (Always Follow)');
+        answers.conventions.forEach(c => lines.push(`- ${c}`));
+        lines.push('');
+    }
+    // Never do
+    if (answers.never && answers.never.length > 0) {
+        lines.push('## Never Do');
+        answers.never.forEach(n => lines.push(`- ❌ ${n}`));
+        lines.push('');
+    }
+    // Git
+    if (answers.gitFlow !== undefined) {
+        lines.push('## Git Workflow');
+        if (answers.gitFlow) {
+            lines.push('- Feature branches for all changes');
+            lines.push('- PRs required before merging to main');
+            lines.push('- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`');
+        }
+        else {
+            lines.push('- Direct commits to main branch');
+            lines.push('- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`');
+        }
+        lines.push('');
+    }
+    // Extra
+    if (answers.extra) {
+        lines.push('## Additional Context');
+        lines.push(answers.extra);
+        lines.push('');
+    }
+    // Domain docs pointer
+    lines.push('## AI Docs (Load When Relevant)');
+    lines.push('Deeper context files in `/ai-docs/` — load these when working on that domain:');
+    lines.push('');
+    const domainFiles = getDomainFiles(stack, answers);
+    domainFiles.forEach(d => lines.push(`- \`/ai-docs/${d.filename}\` — ${d.label}`));
+    lines.push('');
+    lines.push('---');
+    lines.push('*Generated by [claude-context](https://github.com/your-username/claude-context)*');
+    return lines.join('\n');
+}
+function databaseDoc(stack) {
+    const db = stack.database || 'your database';
+    return `# Database Context
+
+## Stack
+**ORM / Client:** ${db}
+${stack.hasMigrations ? '**Migrations:** Yes — always run migrations before deploying' : ''}
+
+## Patterns
+
+### Querying
+${db.includes('Prisma') ? `- Use \`prisma\` client from \`@/lib/prisma\`
+- Always use \`prisma.$transaction\` for multi-step writes
+- Use \`select\` to limit returned fields — never return full objects to the client
+- Soft deletes with \`deletedAt\` field where applicable` : ''}
+${db.includes('Supabase') ? `- Use the Supabase server client for server-side queries
+- Use the Supabase browser client only for real-time subscriptions
+- Row Level Security (RLS) is enabled — always check policies` : ''}
+${db.includes('Drizzle') ? `- Use \`db\` from \`@/lib/db\`
+- Prefer \`db.select().from(table).where(...)\` over raw SQL
+- Use \`db.transaction()\` for multi-step writes` : ''}
+${db.includes('Mongoose') ? `- Use models from \`@/models/\`
+- Always use \`.lean()\` for read-only queries
+- Use \`session\` for multi-document transactions` : ''}
+
+### Error Handling
+- Wrap all DB calls in try/catch
+- Log errors with context (userId, operation, tableName)
+- Return typed errors, never throw raw DB errors to the client
+
+### Performance
+- Add indexes for all foreign keys and frequently queried fields
+- Use pagination — never return unbounded lists
+- Avoid N+1 queries — use \`include\`/\`join\` or batch queries
+
+## Schema Conventions
+- All tables have: \`id\`, \`createdAt\`, \`updatedAt\`
+- Foreign key naming: \`userId\`, \`postId\` (camelCase)
+- Boolean fields: \`isActive\`, \`isPublished\` (not \`active\`, \`published\`)
+- Timestamps: \`createdAt\`, \`deletedAt\` — ISO 8601 strings
+
+## Files
+- Schema definition: \`prisma/schema.prisma\` or \`src/db/schema.ts\`
+- DB client: \`src/lib/db.ts\` or \`src/lib/prisma.ts\`
+- Seed data: \`prisma/seed.ts\` or \`scripts/seed.ts\`
+`;
+}
+function authDoc(stack) {
+    const auth = stack.auth || 'custom auth';
+    return `# Authentication Context
+
+## Stack
+**Provider:** ${auth}
+
+## How Auth Works in This App
+${auth.includes('NextAuth') ? `- Session managed by NextAuth.js
+- \`getServerSession()\` for server-side session access
+- \`useSession()\` hook for client-side
+- Session includes: \`user.id\`, \`user.email\`, \`user.role\`
+- Protected routes use middleware in \`middleware.ts\`` : ''}
+${auth.includes('Clerk') ? `- Auth managed by Clerk
+- \`auth()\` for server components, \`useAuth()\` for client
+- \`currentUser()\` to get full user object server-side
+- Middleware in \`middleware.ts\` protects all non-public routes
+- Webhooks at \`/api/webhooks/clerk\` sync users to DB` : ''}
+${auth.includes('Supabase') ? `- Auth managed by Supabase
+- \`createServerClient()\` for server-side auth
+- \`createBrowserClient()\` for client-side auth
+- Always verify session server-side — never trust client claims` : ''}
+${auth.includes('JWT') ? `- JWT tokens stored in httpOnly cookies
+- Verify token in middleware for protected routes
+- Access token expires in 15min, refresh token in 7 days
+- Never store JWTs in localStorage` : ''}
+
+## Rules
+- ❌ Never expose user passwords or tokens in responses
+- ❌ Never trust user-supplied IDs without verifying against session
+- ✅ Always check auth on the server, not just the client
+- ✅ Use middleware for route protection, not per-page checks
+
+## Roles & Permissions
+- Roles stored in \`user.role\` (e.g. \`admin\`, \`user\`, \`viewer\`)
+- Check permissions server-side before any sensitive operation
+- Use typed enums for roles — never hardcode string comparisons
+
+## Files
+- Auth config: \`src/lib/auth.ts\` or \`auth.config.ts\`
+- Middleware: \`middleware.ts\` (root level)
+- Auth API routes: \`app/api/auth/\` or \`pages/api/auth/\`
+`;
+}
+function paymentsDoc(stack) {
+    const pay = stack.payments || 'Stripe';
+    return `# Payments Context
+
+## Stack
+**Provider:** ${pay}
+
+## Architecture
+${pay.includes('Stripe') ? `- Stripe handles all payment processing — we never store card data
+- Webhooks at \`/api/webhooks/stripe\` update subscription state
+- Customer ID stored in DB: \`users.stripeCustomerId\`
+- Subscription status: \`active\`, \`trialing\`, \`canceled\`, \`past_due\`
+
+## Key Flows
+**Checkout:** User → \`/api/checkout\` → Stripe Checkout Session → redirect → webhook confirms
+**Portal:** User → \`/api/billing/portal\` → Stripe Customer Portal → webhook on change
+**Webhook:** Stripe → \`/api/webhooks/stripe\` → verify signature → update DB` : ''}
+${pay.includes('Lemon') ? `- Lemon Squeezy handles all payment processing
+- Webhooks at \`/api/webhooks/lemonsqueezy\`
+- Subscription status synced to DB on every webhook event` : ''}
+
+## Rules
+- ❌ Never process payments client-side
+- ❌ Never trust subscription status from the client — always check DB
+- ✅ Always verify webhook signatures before processing
+- ✅ Idempotency: check if webhook event was already processed
+
+## Subscription Gates
+- Check \`user.subscriptionStatus === 'active'\` before gating features
+- Handle \`trialing\`, \`past_due\` states gracefully
+- Free tier limits enforced server-side
+
+## Files
+- Stripe client: \`src/lib/stripe.ts\`
+- Webhook handler: \`app/api/webhooks/stripe/route.ts\`
+- Checkout handler: \`app/api/checkout/route.ts\`
+`;
+}
+function apiDoc(stack) {
+    return `# API Design Context
+
+## Pattern
+${stack.framework === 'Next.js' ? `- Route Handlers in \`app/api/\` for REST endpoints
+- Server Actions in \`app/actions/\` for form mutations
+- Use Server Actions over API routes for form submissions` : '- RESTful endpoints, grouped by resource'}
+
+## Request / Response Shape
+\`\`\`typescript
+// Success
+{ data: T, error: null }
+
+// Error
+{ data: null, error: { message: string, code: string } }
+\`\`\`
+
+## Rules
+- ✅ Always validate request bodies with Zod (or equivalent)
+- ✅ Return consistent error shapes
+- ✅ Include HTTP status codes that match the outcome
+- ❌ Never return raw DB errors to the client
+- ❌ Never expose internal IDs in public-facing APIs
+
+## Auth on API Routes
+- Check auth at the top of every protected handler
+- Return 401 for unauthenticated, 403 for unauthorized
+\`\`\`typescript
+const session = await getServerSession();
+if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+\`\`\`
+
+## Validation
+- Use Zod schemas defined in \`src/lib/validations/\`
+- Validate both incoming and outgoing data
+- Strip unknown fields before passing to DB
+
+## Rate Limiting
+- Apply rate limiting to all public endpoints
+- Use IP-based limiting for unauthenticated routes
+`;
+}
+function frontendDoc(stack) {
+    return `# Frontend Patterns Context
+
+## Component Architecture
+${stack.framework === 'Next.js' ? `- Default to Server Components — use \`'use client'\` only when needed
+- Client components needed for: hooks, event listeners, browser APIs, animations
+- Keep client components small — push state down, data up` : '- Functional components only, no class components'}
+
+## File Conventions
+\`\`\`
+components/
+  ui/           # Generic, reusable (Button, Input, Modal)
+  [feature]/    # Feature-specific (UserProfile, PaymentForm)
+app/ or pages/  # Route components only — minimal logic here
+hooks/          # Custom React hooks
+lib/            # Utilities, helpers, configs
+types/          # TypeScript interfaces and types
+\`\`\`
+
+## Styling
+${stack.styling === 'Tailwind CSS' ? `- Tailwind CSS for all styling — no inline styles, no CSS modules
+- Use \`cn()\` utility (clsx + tailwind-merge) for conditional classes
+- Responsive: mobile-first, \`sm:\`, \`md:\`, \`lg:\` breakpoints
+- Dark mode: use \`dark:\` variants, not manual class toggling` : `- Follow the existing styling pattern in the codebase`}
+
+## State Management
+${stack.extras.includes('Zustand') ? '- Global state in Zustand stores — \`src/stores/\`' : ''}
+${stack.extras.includes('React Query') ? '- Server state via React Query — never duplicate in local state' : ''}
+- Local UI state: useState/useReducer
+- URL state: searchParams for filters/pagination
+- Avoid prop drilling beyond 2 levels — use context or stores
+
+## Rules
+- ❌ Never fetch data directly in client components — use Server Components or React Query
+- ❌ Never hardcode colors or spacing — use Tailwind tokens
+- ✅ All interactive elements must have accessible labels
+- ✅ Loading and error states required for all async operations
+`;
+}
+function errorHandlingDoc(stack) {
+    return `# Error Handling Context
+
+## Philosophy
+- Errors are expected — handle them gracefully, log them faithfully
+- User-facing errors: friendly messages, no stack traces
+- Server logs: full context (userId, operation, input shape, stack trace)
+
+## Layers
+
+### Server (API Routes / Server Actions)
+\`\`\`typescript
+try {
+  const result = await someOperation();
+  return { data: result, error: null };
+} catch (error) {
+  console.error('[OPERATION_NAME]', { error, userId, input });
+  return { data: null, error: { message: 'Something went wrong', code: 'INTERNAL_ERROR' } };
+}
+\`\`\`
+
+### Client (React Components)
+\`\`\`typescript
+// Async operations
+const [error, setError] = useState<string | null>(null);
+// Handle errors in catch, display with error toast or inline message
+
+// Form submissions
+if (!result.success) {
+  toast.error(result.error.message);
+  return;
+}
+\`\`\`
+
+## Error Codes
+Define typed error codes in \`src/lib/errors.ts\`:
+- \`UNAUTHORIZED\` — user not logged in
+- \`FORBIDDEN\` — logged in but not allowed
+- \`NOT_FOUND\` — resource doesn't exist
+- \`VALIDATION_ERROR\` — invalid input
+- \`INTERNAL_ERROR\` — unexpected server error
+
+## What NOT to Do
+- ❌ Empty catch blocks
+- ❌ \`console.log\` instead of \`console.error\` for errors
+- ❌ Returning raw error.message from database errors to the client
+- ❌ Using generic "Something went wrong" for validation errors — be specific
+`;
+}
+function testingDoc(stack) {
+    const testLib = stack.testing || 'Vitest';
+    return `# Testing Context
+
+## Stack
+**Framework:** ${testLib}
+
+## What to Test
+- ✅ Business logic / utility functions — unit tests
+- ✅ API route handlers — integration tests with mocked DB
+- ✅ Critical user flows — E2E tests (checkout, auth, core feature)
+- ❌ Don't test implementation details — test behavior
+
+## File Conventions
+\`\`\`
+src/
+  lib/
+    utils.ts
+    utils.test.ts    # Co-located unit tests
+  components/
+    Button.tsx
+    Button.test.tsx  # Component tests
+tests/
+  e2e/               # End-to-end tests
+\`\`\`
+
+## Test Patterns
+\`\`\`typescript
+// Unit test example
+describe('formatPrice', () => {
+  it('formats cents to dollars', () => {
+    expect(formatPrice(1999)).toBe('$19.99');
+  });
+  it('handles zero', () => {
+    expect(formatPrice(0)).toBe('$0.00');
+  });
+});
+\`\`\`
+
+## Mocking
+- Mock external services (Stripe, email, DB) in tests
+- Use \`vi.mock()\` (Vitest) or \`jest.mock()\` for module mocks
+- Don't mock internal utilities — test them directly
+
+## CI
+- Tests run on every PR
+- No merging with failing tests
+- Coverage threshold: 70% for critical paths
+`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Deployment doc — Railway-specific
+// ─────────────────────────────────────────────────────────────────────────────
+function deploymentDoc(stack) {
+    return `# Deployment Context
+
+## Platform: Railway
+
+### Overview
+- All services deployed to Railway (web app + PostgreSQL + Redis if needed)
+- Deployments trigger automatically on push to \`main\`
+- Each PR can get an ephemeral preview environment if configured
+- Environment variables set in Railway dashboard — never hardcode
+
+### Services Layout
+\`\`\`
+Railway Project
+  ├── web          ← Next.js app (or API)
+  ├── postgres     ← Railway-managed PostgreSQL
+  └── worker       ← Background jobs (if needed)
+\`\`\`
+
+### Environment Variables
+Always required in Railway dashboard:
+\`\`\`
+DATABASE_URL          # Provided by Railway PostgreSQL plugin
+NODE_ENV              # production
+NEXTAUTH_URL          # https://your-domain.com (or Railway URL)
+\`\`\`
+
+Access in code:
+\`\`\`typescript
+// Always use process.env — never import.meta.env in Node context
+const db = process.env.DATABASE_URL;
+\`\`\`
+
+### Database: PostgreSQL on Railway
+- Connection string format: \`postgresql://user:pass@host:port/dbname\`
+- Railway provides \`DATABASE_URL\` automatically when PostgreSQL is added
+- Use connection pooling for production (PgBouncer or Prisma's \`?pgbouncer=true\`)
+- SSL required: append \`?sslmode=require\` if not using Prisma
+
+\`\`\`typescript
+// Prisma — railway-safe config in schema.prisma
+datasource db {
+  provider  = "postgresql"
+  url       = env("DATABASE_URL")
+  directUrl = env("DIRECT_URL") // for migrations only
+}
+\`\`\`
+
+\`\`\`typescript
+// Drizzle — railway-safe config
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  ssl: { rejectUnauthorized: false }, // required on Railway
+});
+export const db = drizzle(pool);
+\`\`\`
+
+### Migrations on Railway
+- Run migrations as part of the deploy command, not a separate step
+- Set Railway start command to: \`npm run db:migrate && npm run start\`
+- Or use \`railway run prisma migrate deploy\` in CI
+
+### Cron Jobs on Railway
+Railway supports cron jobs as separate services:
+
+\`\`\`
+# In Railway: add a Cron service
+# Schedule format: standard cron (minute hour day month weekday)
+0 9 * * 1-5    # 9am weekdays
+0 0 * * *      # midnight daily
+*/15 * * * *   # every 15 minutes
+\`\`\`
+
+Cron job patterns:
+\`\`\`typescript
+// app/api/cron/[job]/route.ts
+export async function GET(req: Request) {
+  // Verify it's coming from Railway / internal
+  const secret = req.headers.get('x-cron-secret');
+  if (secret !== process.env.CRON_SECRET) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  // Always make cron handlers idempotent
+  // Check if job already ran for this period before doing work
+  try {
+    await runJob();
+    return Response.json({ success: true });
+  } catch (error) {
+    console.error('[CRON ERROR]', error);
+    return Response.json({ error: 'Job failed' }, { status: 500 });
+  }
+}
+\`\`\`
+
+### Cloudflare in Front of Railway
+- Railway app sits behind Cloudflare (DNS proxy enabled)
+- Cloudflare handles: SSL termination, DDoS protection, caching static assets
+- Set Railway custom domain → Cloudflare DNS → Railway
+
+Cache rules (set in Cloudflare dashboard):
+- Cache static assets (\`/_next/static/*\`): Cache Everything, Edge TTL 1 month
+- API routes (\`/api/*\`): Bypass Cache
+- Pages: Browser cache only, no edge cache (unless explicitly static)
+
+Headers to set in Railway app:
+\`\`\`typescript
+// next.config.js
+headers: [
+  {
+    source: '/_next/static/:path*',
+    headers: [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }],
+  },
+]
+\`\`\`
+
+### Health Check
+Railway pings \`/api/health\` — always implement it:
+\`\`\`typescript
+// app/api/health/route.ts
+export async function GET() {
+  return Response.json({ status: 'ok', ts: Date.now() });
+}
+\`\`\`
+
+### Deploy Checklist
+- [ ] All env vars set in Railway dashboard
+- [ ] \`DATABASE_URL\` connected to Railway PostgreSQL service
+- [ ] Migrations run as part of start command
+- [ ] Health check endpoint live at \`/api/health\`
+- [ ] Custom domain added + Cloudflare DNS configured
+- [ ] Stripe webhook URL updated to production domain
+- [ ] \`CRON_SECRET\` set if using cron jobs
+`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Email doc — Resend-specific
+// ─────────────────────────────────────────────────────────────────────────────
+function emailDoc(stack) {
+    return `# Email Context
+
+## Provider: Resend
+
+### Setup
+\`\`\`typescript
+// src/lib/email.ts
+import { Resend } from 'resend';
+
+export const resend = new Resend(process.env.RESEND_API_KEY);
+\`\`\`
+
+Required env vars:
+\`\`\`
+RESEND_API_KEY=re_xxxxxxxxxxxx
+EMAIL_FROM=noreply@yourdomain.com   # must be verified in Resend
+\`\`\`
+
+### Sending Emails
+\`\`\`typescript
+// Always send from a server action or API route — never client-side
+import { resend } from '@/lib/email';
+
+const { data, error } = await resend.emails.send({
+  from: process.env.EMAIL_FROM!,
+  to: user.email,
+  subject: 'Welcome to the app',
+  react: <WelcomeEmail name={user.name} />,  // or html: '...'
+});
+
+if (error) {
+  console.error('[EMAIL_SEND_ERROR]', error);
+  // Don't throw — email failure shouldn't block the user flow
+  // Log and continue, or queue for retry
+}
+\`\`\`
+
+### Email Templates
+Store React email components in \`src/emails/\`:
+\`\`\`
+src/
+  emails/
+    welcome.tsx          # Welcome / onboarding
+    magic-link.tsx       # Auth magic link
+    payment-receipt.tsx  # Post-purchase
+    subscription.tsx     # Subscription changes
+    password-reset.tsx   # Password reset
+\`\`\`
+
+Template pattern:
+\`\`\`typescript
+// src/emails/welcome.tsx
+import { Html, Head, Body, Container, Text, Button } from '@react-email/components';
+
+interface WelcomeEmailProps {
+  name: string;
+  loginUrl: string;
+}
+
+export function WelcomeEmail({ name, loginUrl }: WelcomeEmailProps) {
+  return (
+    <Html>
+      <Head />
+      <Body>
+        <Container>
+          <Text>Hi {name},</Text>
+          <Button href={loginUrl}>Get started</Button>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+\`\`\`
+
+### Rules
+- ❌ Never send emails from client components
+- ❌ Never hardcode \`from\` addresses — always use env var
+- ❌ Never block user flows on email failure — log and continue
+- ✅ Always verify the \`from\` domain in Resend dashboard
+- ✅ Log email send failures with context (userId, type, error)
+- ✅ Use React Email for HTML emails — never raw HTML strings
+- ✅ Test with Resend's test mode before going live
+
+### Transactional Email Triggers
+| Event | Template | Timing |
+|-------|----------|--------|
+| User signs up | welcome.tsx | Immediate |
+| Magic link / OTP | magic-link.tsx | Immediate |
+| Payment successful | payment-receipt.tsx | On Stripe webhook |
+| Subscription canceled | subscription.tsx | On Stripe webhook |
+| Password reset | password-reset.tsx | On request |
+
+### DNS Setup (Cloudflare)
+Add Resend's DNS records in Cloudflare:
+- SPF TXT record on root domain
+- DKIM CNAME records (Resend provides these)
+- Set proxy status to **DNS only** (grey cloud) for mail records — not proxied
+`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Analytics doc — GA4 + Google Search Console
+// ─────────────────────────────────────────────────────────────────────────────
+function analyticsDoc(stack) {
+    return `# Analytics Context
+
+## Stack
+- **Google Analytics 4 (GA4)** — user behaviour, conversions, funnels
+- **Google Search Console** — SEO performance, indexing, search queries
+
+---
+
+## Google Analytics 4
+
+### Setup
+\`\`\`
+GA_MEASUREMENT_ID=G-XXXXXXXXXX   # in .env
+\`\`\`
+
+\`\`\`typescript
+// src/lib/analytics.ts
+export const GA_ID = process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID!;
+
+// Page view
+export function pageview(url: string) {
+  if (typeof window === 'undefined' || !GA_ID) return;
+  window.gtag('config', GA_ID, { page_path: url });
+}
+
+// Custom event
+export function trackEvent(
+  action: string,
+  category: string,
+  label?: string,
+  value?: number
+) {
+  if (typeof window === 'undefined' || !GA_ID) return;
+  window.gtag('event', action, {
+    event_category: category,
+    event_label: label,
+    value,
+  });
+}
+\`\`\`
+
+### Next.js Integration
+\`\`\`typescript
+// app/layout.tsx — add GA script
+import Script from 'next/script';
+
+<Script
+  src={\`https://www.googletagmanager.com/gtag/js?id=\${GA_ID}\`}
+  strategy="afterInteractive"
+/>
+<Script id="ga-init" strategy="afterInteractive">
+  {\`
+    window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+    gtag('config', '\${GA_ID}', { page_path: window.location.pathname });
+  \`}
+</Script>
+\`\`\`
+
+### Key Events to Track
+\`\`\`typescript
+// Conversion events — track these
+trackEvent('sign_up', 'auth', method);             // User registers
+trackEvent('login', 'auth', method);               // User logs in
+trackEvent('begin_checkout', 'ecommerce', plan);   // Hits checkout
+trackEvent('purchase', 'ecommerce', plan, amount); // Payment complete
+trackEvent('cancel_subscription', 'billing');       // Cancels plan
+
+// Engagement events
+trackEvent('feature_used', 'engagement', featureName);
+trackEvent('share', 'engagement', contentType);
+\`\`\`
+
+### Cloudflare + GA4
+- Cloudflare can block GA4 if Rocket Loader is enabled — disable it or defer GA scripts
+- Use \`strategy="afterInteractive"\` in Next.js to avoid blocking render
+
+### Rules
+- ❌ Never track PII (emails, names) in GA4 events
+- ❌ Never fire events server-side — GA4 is client-only (use GA4 Measurement Protocol for server events)
+- ✅ Always check \`typeof window !== 'undefined'\` before calling gtag
+- ✅ Respect user consent — don't load GA until cookie consent given (if required by region)
+
+---
+
+## Google Search Console
+
+### Setup
+1. Add property in Search Console: \`https://yourdomain.com\`
+2. Verify via Cloudflare DNS TXT record (easiest method)
+3. Submit sitemap: \`https://yourdomain.com/sitemap.xml\`
+
+### Sitemap in Next.js
+\`\`\`typescript
+// app/sitemap.ts
+import { MetadataRoute } from 'next';
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  return [
+    { url: 'https://yourdomain.com', lastModified: new Date(), changeFrequency: 'weekly', priority: 1 },
+    { url: 'https://yourdomain.com/pricing', lastModified: new Date(), changeFrequency: 'monthly', priority: 0.8 },
+    // Add dynamic pages here
+  ];
+}
+\`\`\`
+
+### Robots.txt
+\`\`\`typescript
+// app/robots.ts
+export default function robots() {
+  return {
+    rules: { userAgent: '*', allow: '/', disallow: ['/api/', '/dashboard/'] },
+    sitemap: 'https://yourdomain.com/sitemap.xml',
+  };
+}
+\`\`\`
+
+### What to Monitor Weekly
+- **Coverage** — indexing errors, excluded pages
+- **Performance** — clicks, impressions, CTR, average position
+- **Core Web Vitals** — LCP, FID, CLS scores
+- **Search queries** — what terms bring people in
+`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Cloudflare doc
+// ─────────────────────────────────────────────────────────────────────────────
+function cloudflareDoc(stack) {
+    return `# Cloudflare Context
+
+## Role in This Stack
+Cloudflare sits in front of Railway:
+\`\`\`
+User → Cloudflare (DNS + CDN + DDoS) → Railway (app) → PostgreSQL
+\`\`\`
+
+## DNS Setup
+- Domain managed in Cloudflare DNS
+- Railway custom domain → CNAME pointing to Railway-provided URL
+- Proxy status: **Proxied** (orange cloud) for the main app
+- Proxy status: **DNS only** (grey cloud) for: mail records (Resend), Railway health checks
+
+## SSL/TLS
+- Mode: **Full (strict)** — Cloudflare ↔ Railway both use SSL
+- Always Use HTTPS: **On**
+- Min TLS Version: **TLS 1.2**
+- Railway: enable "Generate Certificate" in Railway domain settings
+
+## Caching Rules
+Set in Cloudflare **Cache Rules** (not Page Rules — those are legacy):
+
+| Pattern | Cache Behaviour |
+|---------|----------------|
+| \`/_next/static/*\` | Cache Everything, Edge TTL: 1 month |
+| \`/images/*\` | Cache Everything, Edge TTL: 1 week |
+| \`/api/*\` | Bypass Cache |
+| \`/dashboard*\` | Bypass Cache |
+| Everything else | Standard (Cloudflare decides) |
+
+## Security Rules
+Firewall → Custom Rules:
+
+\`\`\`
+# Block suspicious bots (example rule in Cloudflare expression syntax)
+(cf.client.bot) and not (cf.verified_bot_category in {"Search Engine Crawlers"})
+→ Action: Challenge
+
+# Rate limit login attempts
+(http.request.uri.path eq "/api/auth/signin" and http.request.method eq "POST")
+→ Rate limit: 10 req/min per IP → Action: Block
+\`\`\`
+
+## Workers (if needed)
+Use Cloudflare Workers for:
+- Edge redirects (faster than Next.js middleware for simple redirects)
+- A/B testing at the edge
+- Geo-based routing
+
+Avoid Workers for:
+- Anything needing DB access (use Railway API instead)
+- Complex business logic (keep in Next.js)
+
+## Headers to Set in Next.js (Railway)
+These complement Cloudflare's protections:
+\`\`\`typescript
+// next.config.js
+const securityHeaders = [
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+];
+\`\`\`
+
+## Purge Cache After Deploy
+After Railway deploys:
+\`\`\`bash
+# Purge Cloudflare cache via API
+curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \\
+  -H "Authorization: Bearer CF_API_TOKEN" \\
+  -H "Content-Type: application/json" \\
+  --data '{"purge_everything":true}'
+\`\`\`
+Or add this to Railway deploy hooks.
+
+## Env Vars Needed
+\`\`\`
+CLOUDFLARE_ZONE_ID=xxxx       # For cache purge scripts
+CLOUDFLARE_API_TOKEN=xxxx     # Scoped to Cache Purge permission only
+\`\`\`
+
+## Rules
+- ❌ Never put real-time API responses behind Cloudflare cache
+- ❌ Never proxy mail DNS records through Cloudflare (breaks Resend DKIM)
+- ✅ Always use Full (strict) SSL mode — never Flexible
+- ✅ Purge cache after significant deploys
+- ✅ Use Cloudflare Analytics as a secondary source (privacy-friendly, no cookies)
+`;
+}
+// ---------------------------------------------------------------------------
+// Constants & Lookup Functions
+// ---------------------------------------------------------------------------
+const ALL_DOMAIN_DOCS = [
+    { filename: 'database.md', label: 'DB patterns, queries, schema conventions', key: 'database' },
+    { filename: 'auth.md', label: 'Auth patterns, session access, route protection', key: 'auth' },
+    { filename: 'payments.md', label: 'Payment flows, webhooks, subscription gates', key: 'payments' },
+    { filename: 'api.md', label: 'API design, validation, error shapes', key: 'api' },
+    { filename: 'frontend.md', label: 'Component patterns, styling, state management', key: 'frontend' },
+    { filename: 'errors.md', label: 'Error handling patterns, logging, error codes', key: 'errors' },
+    { filename: 'testing.md', label: 'Testing strategy, patterns, what to test', key: 'testing' },
+    { filename: 'deployment.md', label: 'Railway deploy, crons, PostgreSQL, Cloudflare', key: 'deployment' },
+    { filename: 'email.md', label: 'Resend setup, templates, triggers', key: 'email' },
+    { filename: 'analytics.md', label: 'GA4 events, Search Console, sitemap', key: 'analytics' },
+    { filename: 'cloudflare.md', label: 'DNS, caching rules, security, SSL', key: 'cloudflare' },
+];
+exports.ALL_DOMAIN_DOCS = ALL_DOMAIN_DOCS;
+const SKILL_FILES = [
+    { filename: 'skills/frontend.md', label: 'Frontend Engineer persona' },
+    { filename: 'skills/backend.md', label: 'Backend Engineer persona' },
+    { filename: 'skills/devops.md', label: 'DevOps / Infrastructure persona' },
+    { filename: 'skills/reviewer.md', label: 'Code Reviewer persona' },
+];
+exports.SKILL_FILES = SKILL_FILES;
+const EXTRA_FILES = [
+    { filename: 'security.md', label: 'OWASP + STRIDE threat model for this stack' },
+    { filename: 'HANDOVER.md', label: 'Session handover template (resume sessions cheaply)' },
+    { filename: 'MISTAKES.md', label: 'Living mistake log (never repeat the same error)' },
+    { filename: 'TOKEN-RULES.md', label: 'Token-saving rules for Claude' },
+];
+exports.EXTRA_FILES = EXTRA_FILES;
+function getDomainFiles(stack, answers) {
+    const selected = (answers.domains || []).map((d) => d.toLowerCase());
+    const alwaysDocs = answers.alwaysDocs || [];
+    const files = [];
+    for (const doc of ALL_DOMAIN_DOCS) {
+        const shouldInclude = alwaysDocs.includes(doc.key) ||
+            selected.some((d) => d.includes(doc.key)) ||
+            (doc.key === 'database' && !!stack.database) ||
+            (doc.key === 'auth' && !!stack.auth) ||
+            (doc.key === 'payments' && !!stack.payments);
+        if (shouldInclude)
+            files.push(doc);
+    }
+    if (files.length === 0) {
+        return ALL_DOMAIN_DOCS.filter(d => ['api', 'frontend', 'deployment'].includes(d.key));
+    }
+    return files;
+}
+function generateDomainDoc(filename, stack) {
+    switch (filename) {
+        case 'database.md': return databaseDoc(stack);
+        case 'auth.md': return authDoc(stack);
+        case 'payments.md': return paymentsDoc(stack);
+        case 'api.md': return apiDoc(stack);
+        case 'frontend.md': return frontendDoc(stack);
+        case 'errors.md': return errorHandlingDoc(stack);
+        case 'testing.md': return testingDoc(stack);
+        case 'deployment.md': return deploymentDoc(stack);
+        case 'email.md': return emailDoc(stack);
+        case 'analytics.md': return analyticsDoc(stack);
+        case 'cloudflare.md': return cloudflareDoc(stack);
+        default: return `# ${filename}\n\nAdd your context here.\n`;
+    }
+}
+function generatePromptFile(filename, stack) {
+    switch (filename) {
+        case 'PROMPTS.md': return promptsIndex(stack);
+        case 'prompts/auth.md': return authPrompts(stack);
+        case 'prompts/database.md': return databasePrompts(stack);
+        case 'prompts/payments.md': return paymentsPrompts(stack);
+        case 'prompts/ui.md': return uiPrompts(stack);
+        case 'prompts/api.md': return apiPrompts(stack);
+        case 'prompts/deployment.md': return deploymentPrompts(stack);
+        case 'prompts/email.md': return emailPrompts(stack);
+        case 'prompts/analytics.md': return analyticsPrompts(stack);
+        case 'prompts/security.md': return securityPrompts(stack);
+        default: return `# ${filename}\n\nAdd prompt patterns here.\n`;
+    }
+}
+function getPromptFiles(stack, answers) {
+    const files = [{ filename: 'PROMPTS.md', label: 'Pattern library index' }];
+    const domains = answers.domains || [];
+    if (stack.auth || domains.includes('auth'))
+        files.push({ filename: 'prompts/auth.md', label: 'Auth Build/Verify/Debug patterns' });
+    if (stack.database || domains.includes('database'))
+        files.push({ filename: 'prompts/database.md', label: 'Database Build/Verify/Debug patterns' });
+    if (stack.payments || domains.includes('payments'))
+        files.push({ filename: 'prompts/payments.md', label: 'Payments Build/Verify/Debug patterns' });
+    files.push({ filename: 'prompts/ui.md', label: 'UI / component patterns' });
+    files.push({ filename: 'prompts/api.md', label: 'API route patterns' });
+    if (domains.includes('deployment') || answers.alwaysDocs?.includes('deployment'))
+        files.push({ filename: 'prompts/deployment.md', label: 'Deployment / cron patterns' });
+    if (domains.includes('email') || answers.alwaysDocs?.includes('email'))
+        files.push({ filename: 'prompts/email.md', label: 'Email send patterns' });
+    if (domains.includes('analytics') || answers.alwaysDocs?.includes('analytics'))
+        files.push({ filename: 'prompts/analytics.md', label: 'Analytics event patterns' });
+    files.push({ filename: 'prompts/security.md', label: 'Security / OWASP patterns' });
+    return files;
+}
+function generateSkillFile(filename) {
+    switch (filename) {
+        case 'skills/frontend.md': return frontendSkill();
+        case 'skills/backend.md': return backendSkill();
+        case 'skills/devops.md': return devopsSkill();
+        case 'skills/reviewer.md': return reviewerSkill();
+        default: return '';
+    }
+}
+function generateExtraFile(filename, stack) {
+    switch (filename) {
+        case 'security.md': return securityDoc(stack);
+        case 'HANDOVER.md': return handoverTemplate();
+        case 'MISTAKES.md': return mistakesTemplate();
+        case 'TOKEN-RULES.md': return tokenRulesDoc();
+        default: return '';
+    }
+}
+// ---------------------------------------------------------------------------
+// File Writing Helpers
+// ---------------------------------------------------------------------------
+function writeFileSync(filePath, content) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+}
+function checkExisting(cwd) {
+    const existing = [];
+    if (fs.existsSync(path.join(cwd, 'CLAUDE.md')))
+        existing.push('CLAUDE.md');
+    if (fs.existsSync(path.join(cwd, 'ai-docs')))
+        existing.push('ai-docs/');
+    return existing;
+}
+// ---------------------------------------------------------------------------
+// Main Generation Function
+// ---------------------------------------------------------------------------
+function generateContextFiles(projectDir, stack, options, answers = {}) {
+    const { force = false, dryRun = false } = options;
+    (0, logger_1.log)('GENERATOR', 'start', 'Generating context files', { projectDir, dryRun });
+    // Check for existing files
+    const existing = checkExisting(projectDir);
+    if (existing.length > 0 && !force) {
+        (0, logger_1.logWarn)('GENERATOR', 'existing', 'Existing files found, use --force to overwrite', { existing });
+        return;
+    }
+    // Determine which files to generate
+    const domainFiles = getDomainFiles(stack, answers);
+    const promptFiles = getPromptFiles(stack, answers);
+    if (dryRun) {
+        (0, logger_1.log)('GENERATOR', 'dry-run', 'Dry run - would generate:');
+        console.log('Layer 1: CLAUDE.md');
+        domainFiles.forEach((f) => console.log('Layer 2: ai-docs/' + f.filename));
+        promptFiles.forEach((f) => console.log('Layer 3: ai-docs/' + f.filename));
+        SKILL_FILES.forEach((f) => console.log('Skills:  ai-docs/' + f.filename));
+        EXTRA_FILES.forEach((f) => console.log('Extras:  ai-docs/' + f.filename));
+        return;
+    }
+    // Layer 1 - CLAUDE.md
+    (0, logger_1.log)('GENERATOR', 'write', 'Writing Layer 1 - CLAUDE.md');
+    const claudeMdContent = claudeMd(stack, answers);
+    writeFileSync(path.join(projectDir, 'CLAUDE.md'), claudeMdContent);
+    (0, logger_1.log)('GENERATOR', 'write', 'CLAUDE.md', { tokens: Math.round(claudeMdContent.length / 4) });
+    // Layer 2 - Domain Docs
+    (0, logger_1.log)('GENERATOR', 'write', 'Writing Layer 2 - Domain Docs');
+    for (const f of domainFiles) {
+        const content = generateDomainDoc(f.filename, stack);
+        writeFileSync(path.join(projectDir, 'ai-docs', f.filename), content);
+        (0, logger_1.log)('GENERATOR', 'write', f.filename, { label: f.label, tokens: Math.round(content.length / 4) });
+    }
+    // Layer 3 - Pattern Library
+    (0, logger_1.log)('GENERATOR', 'write', 'Writing Layer 3 - Pattern Library');
+    for (const f of promptFiles) {
+        const content = generatePromptFile(f.filename, stack);
+        writeFileSync(path.join(projectDir, 'ai-docs', f.filename), content);
+        (0, logger_1.log)('GENERATOR', 'write', f.filename, { label: f.label, tokens: Math.round(content.length / 4) });
+    }
+    // Skills
+    (0, logger_1.log)('GENERATOR', 'write', 'Writing Skills');
+    for (const f of SKILL_FILES) {
+        const content = generateSkillFile(f.filename);
+        writeFileSync(path.join(projectDir, 'ai-docs', f.filename), content);
+        (0, logger_1.log)('GENERATOR', 'write', f.filename, { label: f.label });
+    }
+    // Extras
+    (0, logger_1.log)('GENERATOR', 'write', 'Writing Extras');
+    for (const f of EXTRA_FILES) {
+        const content = generateExtraFile(f.filename, stack);
+        writeFileSync(path.join(projectDir, 'ai-docs', f.filename), content);
+        (0, logger_1.log)('GENERATOR', 'write', f.filename, { label: f.label });
+    }
+    (0, logger_1.log)('GENERATOR', 'done', 'All context files generated successfully');
+}
+//# sourceMappingURL=generator.js.map