create-loadout 1.0.2 → 1.0.4

package/dist/claude-md.js

@@ -99,10 +99,10 @@ export async function generateClaudeMd(projectPath, config) {
     const hasPostHog = config.integrations.includes('posthog');
     const hasSentry = config.integrations.includes('sentry');
     const hasClerk = config.integrations.includes('clerk');
-    let content = `# ${config.name}
-
-## Tech Stack
-
+    let content = `# ${config.name}
+
+## Tech Stack
+
 `;
     for (const section of sections) {
         content += `### ${section.name}\n`;
@@ -111,368 +111,539 @@ export async function generateClaudeMd(projectPath, config) {
         }
         content += '\n';
     }
-    content += `## Development Commands
-
-\`\`\`bash
-npm run dev       # Start development server
-npm run build     # Build for production
-npm run start     # Start production server
-npm run lint      # Run ESLint
-\`\`\`
+    content += `## Development Commands
+
+\`\`\`bash
+npm run dev       # Start development server
+npm run build     # Build for production
+npm run start     # Start production server
+npm run lint      # Run ESLint
+\`\`\`
 `;
     if (hasDb) {
-        content += `
-### Database Commands
-
-\`\`\`bash
-npm run db:generate  # Generate migrations from schema changes
-npm run db:migrate   # Apply migrations to database
-npm run db:studio    # Open Drizzle Studio to browse data
-\`\`\`
+        content += `
+### Database Commands
+
+\`\`\`bash
+npm run db:generate  # Generate migrations from schema changes
+npm run db:migrate   # Apply migrations to database
+npm run db:studio    # Open Drizzle Studio to browse data
+\`\`\`
 `;
     }
     if (config.integrations.includes('inngest')) {
-        content += `
-### Background Jobs
-
-\`\`\`bash
-npm run inngest:dev  # Start Inngest dev server for local testing
-\`\`\`
+        content += `
+### Background Jobs
+
+\`\`\`bash
+npm run inngest:dev  # Start Inngest dev server for local testing
+\`\`\`
 `;
     }
-    content += `
-## Architecture
-
-### Directory Structure
-
-\`\`\`
-├── app/                    # Next.js App Router pages and API routes
-├── components/             # React components (including shadcn/ui)
+    content += `
+## Architecture
+
+### Directory Structure
+
+\`\`\`
+├── app/                    # Next.js App Router pages and API routes
+├── components/             # React components (including shadcn/ui)
 `;
     if (config.integrations.includes('resend') || config.integrations.includes('postmark')) {
-        content += `│   └── emails/             # Email templates
+        content += `│   └── emails/             # Email templates
 `;
     }
     if (hasPostHog || hasSentry) {
-        content += `├── instrumentation-client.ts  # Client-side init
+        content += `├── instrumentation-client.ts  # Client-side init
 `;
     }
     if (hasSentry) {
-        content += `├── instrumentation.ts         # Server-side Sentry registration
+        content += `├── instrumentation.ts         # Server-side Sentry registration
 `;
     }
     if (hasDb) {
-        content += `├── actions/                # Server actions (form submissions)
-│   └── *.actions.ts
-├── services/               # Business logic orchestration
-│   └── *.service.ts
-├── dao/                    # Data access objects (database queries)
-│   └── *.dao.ts
-├── mappers/                # Data transformation
-│   └── *.mapper.ts
-├── models/                 # Type definitions
-│   ├── *.dto.ts            # Database types (InferSelectModel)
-│   ├── *.view.ts           # View models for UI
-│   ├── *.schema.ts         # Zod validation + ServiceRequest/Result
-│   ├── *.state.ts          # Action state objects
-│   └── *ServiceError.enum.ts  # Service error enums
+        content += `├── actions/                # Server actions (form submissions)
+│   └── *.actions.ts
+├── services/               # Business logic orchestration
+│   └── *.service.ts
+├── dao/                    # Data access objects (database queries)
+│   └── *.dao.ts
+├── mappers/                # Data transformation
+│   └── *.mapper.ts
+├── models/                 # Type definitions
+│   ├── *.dto.ts            # Database types (InferSelectModel)
+│   ├── *.view.ts           # View models for UI
+│   ├── *.schema.ts         # Zod validation + ServiceRequest/Result
+│   ├── *.state.ts          # Action state objects
+│   └── *ServiceError.enum.ts  # Service error enums
 `;
     }
     else {
-        content += `├── services/               # Business logic services
-│   └── *.service.ts
+        content += `├── services/               # Business logic services
+│   └── *.service.ts
 `;
     }
-    content += `├── lib/
-│   ├── config.ts           # Centralized environment variables
-│   ├── stores/             # Zustand stores for client state
-│   │   └── *.store.ts
+    content += `├── lib/
+│   ├── config.ts           # Centralized environment variables
+│   ├── stores/             # Zustand stores for client state
+│   │   └── *.store.ts
 `;
     if (hasDb) {
-        content += `│   └── db/                 # Database client and schema
+        content += `│   └── db/                 # Database client and schema
 `;
     }
-    content += `└── public/                 # Static assets
-\`\`\`
+    content += `└── public/                 # Static assets
+\`\`\`
 `;
     if (hasDb) {
-        content += `
-### Layered Architecture
-
-The application follows a strict 4-layer architecture:
-
-\`\`\`
-UI Components (app/, components/)
-    ↓
-Server Actions (actions/*.actions.ts)
-    ↓
-Services (services/*.service.ts)
-    ↓
-DAOs (dao/*.dao.ts)
-    ↓
-Database (Drizzle ORM)
-\`\`\`
-
-**Layer responsibilities:**
-
-- **Actions** - Handle form submissions, validate with Zod, check auth, call services, revalidate cache
-- **Services** - Orchestrate business logic, coordinate multiple DAOs
-- **DAOs** - Encapsulate all database queries using Drizzle ORM
-- **Mappers** - Transform between DTOs, service requests, and view models
-
-### Model File Naming Conventions
-
-Files in \`models/\` follow strict naming:
-
-| Pattern | Purpose | Example |
-|---------|---------|---------|
-| \`*.dto.ts\` | Database types from Drizzle | \`UserDto\`, \`UserInsertDto\` |
-| \`*.view.ts\` | View models for UI | \`UserView\` |
-| \`*.schema.ts\` | Zod schemas + service types | \`UserCreateFormSchema\`, \`UserCreateServiceRequest\` |
-| \`*.state.ts\` | Action state objects | \`UserCreateState\` |
-| \`*ServiceError.enum.ts\` | Service error enums | \`UserServiceError\` |
-
-### Action File Organization
-
-One action file per domain entity: \`actions/{entity}.action.ts\`. Do NOT split by operation type.
-
-\`\`\`
-actions/
-  project.action.ts   # createProject, updateProject, deleteProject, searchProjects
-  task.action.ts      # createTask, updateTask, deleteTask, searchTasks
-  comment.action.ts   # createComment, deleteComment
-  settings.action.ts  # updateSettings
-\`\`\`
-
-Do NOT create separate files like \`project.create.action.ts\` or \`task.search.action.ts\`.
-
-### Server Action Pattern
-
-\`\`\`typescript
-'use server';
-
-export async function createEntity(
-  state: EntityCreateState,
-  formData: FormData
-): Promise<EntityCreateState> {
-  const user = await currentUser();
-  if (!user) {
-    return { success: false, error: 'Not authenticated', data: null };
-  }
-
-  const rawData = Object.fromEntries(formData);
-  const validated = EntityCreateSchema.safeParse(rawData);
-
-  if (!validated.success) {
-    return { success: false, error: z.prettifyError(validated.error), data: null };
-  }
-
-  try {
-    const result = await entityService.createEntity(validated.data);
-    revalidatePath('/entities');
-    return { success: true, error: null, data: result };
-  } catch (error) {
-    return { success: false, error: 'Failed to create entity', data: null };
-  }
-}
-\`\`\`
-
-### DAO Pattern
-
-\`\`\`typescript
-export class EntityDAO {
-  async create(dto: EntityInsertDto): Promise<EntityDto | undefined> {
-    const [created] = await db.insert(entities).values(dto).returning();
-    return created;
-  }
-
-  async getById(id: string): Promise<EntityDto | undefined> {
-    return await db.query.entities.findFirst({
-      where: eq(entities.id, id),
-    });
-  }
-}
-
-export const entityDAO = new EntityDAO();
-\`\`\`
-
-### Service Error Enums
-
-Each service class has a corresponding error enum in \`models/{serviceName}ServiceError.enum.ts\`. Services throw errors using enum values, actions catch and translate to user-friendly messages.
-
-\`\`\`typescript
-// models/performanceServiceError.enum.ts
-export enum PerformanceServiceError {
-  NotFound = "PERFORMANCE_NOT_FOUND",
-  NotOwned = "PERFORMANCE_NOT_OWNED",
-  DuplicateTime = "PERFORMANCE_DUPLICATE_TIME",
-}
-
-// services/performance.service.ts
-import { PerformanceServiceError } from "@/models/performanceServiceError.enum";
-
-if (conflict) {
-  throw new Error(PerformanceServiceError.DuplicateTime);
-}
-
-// actions/performance.action.ts
-import { PerformanceServiceError } from "@/models/performanceServiceError.enum";
-
-catch (error) {
-  if (error instanceof Error) {
-    switch (error.message) {
-      case PerformanceServiceError.DuplicateTime:
-        return { success: false, error: 'A performance already exists at this time', data: null };
-      case PerformanceServiceError.NotFound:
-        return { success: false, error: 'Performance not found', data: null };
-      case PerformanceServiceError.NotOwned:
-        return { success: false, error: 'You do not have permission to modify this performance', data: null };
-    }
-  }
-  return { success: false, error: 'Failed to update performance', data: null };
-}
-\`\`\`
+        content += `
+### Layered Architecture
+
+The application follows a strict 4-layer architecture:
+
+\`\`\`
+UI Components (app/, components/)
+    ↓
+Server Actions (actions/*.actions.ts)
+    ↓
+Services (services/*.service.ts)
+    ↓
+DAOs (dao/*.dao.ts)
+    ↓
+Database (Drizzle ORM)
+\`\`\`
+
+**Layer responsibilities:**
+
+- **Actions** - Handle form submissions, validate with Zod, check auth, call services, revalidate cache
+- **Services** - Orchestrate business logic, coordinate multiple DAOs
+- **DAOs** - Encapsulate all database queries using Drizzle ORM
+- **Mappers** - Transform between DTOs, service requests, and view models
+
+### Model File Naming Conventions
+
+Files in \`models/\` follow strict naming:
+
+| Pattern | Purpose | Example |
+|---------|---------|---------|
+| \`*.dto.ts\` | Database types from Drizzle | \`UserDto\`, \`UserInsertDto\` |
+| \`*.view.ts\` | View models for UI | \`UserView\` |
+| \`*.schema.ts\` | Zod schemas + service types | \`UserCreateFormSchema\`, \`UserCreateServiceRequest\` |
+| \`*.state.ts\` | Action state objects | \`UserCreateState\` |
+| \`*ServiceError.enum.ts\` | Service error enums | \`UserServiceError\` |
+
+### Action File Organization
+
+One action file per domain entity: \`actions/{entity}.action.ts\`. Do NOT split by operation type.
+
+\`\`\`
+actions/
+  project.action.ts   # createProject, updateProject, deleteProject, searchProjects
+  task.action.ts      # createTask, updateTask, deleteTask, searchTasks
+  comment.action.ts   # createComment, deleteComment
+  settings.action.ts  # updateSettings
+\`\`\`
+
+Do NOT create separate files like \`project.create.action.ts\` or \`task.search.action.ts\`.
+
+### Server Action Pattern
+
+\`\`\`typescript
+'use server';
+
+export async function createEntity(
+  state: EntityCreateState,
+  formData: FormData
+): Promise<EntityCreateState> {
+  const user = await currentUser();
+  if (!user) {
+    return { success: false, error: 'Not authenticated', data: null };
+  }
+
+  const rawData = Object.fromEntries(formData);
+  const validated = EntityCreateSchema.safeParse(rawData);
+
+  if (!validated.success) {
+    return { success: false, error: z.prettifyError(validated.error), data: null };
+  }
+
+  try {
+    const result = await entityService.createEntity(validated.data);
+    revalidatePath('/entities');
+    return { success: true, error: null, data: result };
+  } catch (error) {
+    return { success: false, error: 'Failed to create entity', data: null };
+  }
+}
+\`\`\`
+
+### DAO Pattern
+
+\`\`\`typescript
+export class EntityDAO {
+  async create(dto: EntityInsertDto): Promise<EntityDto | undefined> {
+    const [created] = await db.insert(entities).values(dto).returning();
+    return created;
+  }
+
+  async getById(id: string): Promise<EntityDto | undefined> {
+    return await db.query.entities.findFirst({
+      where: eq(entities.id, id),
+    });
+  }
+}
+
+export const entityDAO = new EntityDAO();
+\`\`\`
+
+### Service Error Enums
+
+Each service class has a corresponding error enum in \`models/{serviceName}ServiceError.enum.ts\`. Services throw errors using enum values, actions catch and translate to user-friendly messages.
+
+\`\`\`typescript
+// models/performanceServiceError.enum.ts
+export enum PerformanceServiceError {
+  NotFound = "PERFORMANCE_NOT_FOUND",
+  NotOwned = "PERFORMANCE_NOT_OWNED",
+  DuplicateTime = "PERFORMANCE_DUPLICATE_TIME",
+}
+
+// services/performance.service.ts
+import { PerformanceServiceError } from "@/models/performanceServiceError.enum";
+
+if (conflict) {
+  throw new Error(PerformanceServiceError.DuplicateTime);
+}
+
+// actions/performance.action.ts
+import { PerformanceServiceError } from "@/models/performanceServiceError.enum";
+
+catch (error) {
+  if (error instanceof Error) {
+    switch (error.message) {
+      case PerformanceServiceError.DuplicateTime:
+        return { success: false, error: 'A performance already exists at this time', data: null };
+      case PerformanceServiceError.NotFound:
+        return { success: false, error: 'Performance not found', data: null };
+      case PerformanceServiceError.NotOwned:
+        return { success: false, error: 'You do not have permission to modify this performance', data: null };
+    }
+  }
+  return { success: false, error: 'Failed to update performance', data: null };
+}
+\`\`\`
+
+### No Rogue Types
+
+Types must come from Zod schemas (\`z.infer<typeof Schema>\`) or \`models/\` files. Do NOT define interfaces in component or action files.
+
+\`\`\`typescript
+// ❌ Wrong - interface defined in component
+interface TodoItem {
+  id: string;
+  title: string;
+}
+
+// ✅ Correct - import from schema or models
+import { type TodoCreatePayload } from "@/models/todoCreate.schema";
+\`\`\`
+
+### Service Request/Result Patterns
+
+**ServiceRequest** - Derive from form schema payload, extend with context:
+
+\`\`\`typescript
+// ✅ Correct - derive from schema, extend with additional fields
+export type TodoCreateServiceRequest = TodoCreateFormPayload & { userId: string };
+
+// ✅ Correct - direct assignment when no additions needed
+export type TodoUpdateServiceRequest = TodoUpdateFormPayload;
+
+// ❌ Wrong - manually retyping all fields
+export type TodoCreateServiceRequest = {
+  title: string;
+  description?: string;
+  userId: string;
+};
+\`\`\`
+
+**ServiceResult** - Only for compound returns (2+ fields). Do NOT wrap single values:
+
+\`\`\`typescript
+// ❌ Wrong - overkill wrapper for single value
+export type TodoCreateServiceResult = { todoId: string };
+
+// ✅ Correct - return directly
+async createTodo(request): Promise<string> {
+  return created.id;
+}
+
+// ✅ Correct - compound data warrants a type
+export type SearchServiceResult = {
+  items: ItemDto[];
+  totalCount: number;
+};
+\`\`\`
+
+**Simple gets** - No ServiceRequest/ServiceResult. Let the signature be the contract:
+
+\`\`\`typescript
+findById(id: string): Promise<TodoDto | null>
+findByUserId(userId: string): Promise<TodoDto[]>
+\`\`\`
+
+### Action Success/Error Handling
+
+Do NOT use \`useEffect\` to react to \`useActionState\` results. Wrap the action in a \`useCallback\` that handles side effects inline.
+
+\`\`\`typescript
+// ❌ Wrong - useEffect watching action state
+useEffect(() => {
+  if (createState.success) {
+    toast.success("Created");
+    setDialogOpen(false);
+  }
+}, [createState]);
+
+// ✅ Correct - wrapper handles side effects inline
+const handleCreateAction = useCallback(async (prevState: State, formData: FormData) => {
+  const result = await createThing(prevState, formData);
+  if (result.success) {
+    toast.success("Created");
+    setDialogOpen(false);
+  }
+  if (result.error) {
+    toast.error(result.error);
+  }
+  return result;
+}, []);
+
+const [createState, createFormAction, isCreatePending] = useActionState(
+  handleCreateAction,
+  initialState
+);
+\`\`\`
+
+### Error Logging in Actions
+
+Use format \`actions/{filename}/{functionName}:\` for console.error calls:
+
+\`\`\`typescript
+console.error("actions/todo.actions.ts/createTodo:", error);
+\`\`\`
 `;
     }
-    content += `
-## Client State Management (Zustand)
-
-For complex multi-step forms or flows, use Zustand stores.
-
-**Store location**: \`lib/stores/*.store.ts\`
-
-### Store Pattern
-
-\`\`\`typescript
-import { createStore, useStore } from 'zustand';
-
-interface FormState {
-  title: string;
-  description: string;
-  setTitle: (title: string) => void;
-  setDescription: (description: string) => void;
-  reset: () => void;
-}
-
-const initialState = {
-  title: '',
-  description: '',
-};
-
-export const formStore = createStore<FormState>()((set) => ({
-  ...initialState,
-  setTitle: (title) => set({ title }),
-  setDescription: (description) => set({ description }),
-  reset: () => set(initialState),
-}));
-
-export const useFormStore = <T>(selector: (state: FormState) => T): T => {
-  return useStore(formStore, selector);
-};
-\`\`\`
-
-### Usage in Components
-
-\`\`\`tsx
-'use client';
-
-import { Input } from '@/components/ui/input';
-import { Label } from '@/components/ui/label';
-
-function TitleStep() {
-  const title = useFormStore((state) => state.title);
-  const setTitle = useFormStore((state) => state.setTitle);
-
-  return (
-    <div className="space-y-2">
-      <Label htmlFor="title">Title</Label>
-      <Input
-        id="title"
-        value={title}
-        onChange={(e) => setTitle(e.target.value)}
-        placeholder="Enter a title"
-      />
-    </div>
-  );
-}
-\`\`\`
-
-## Code Style
-
-### No Comments
-
-Do not add comments to the codebase. Code should be self-documenting through:
-- Clear, descriptive variable and function names
-- Proper TypeScript types
-- Logical code structure
-- Small, focused functions
-
-### Closure Variable Naming
-
-Always use verbose singular names in closures (\`.map()\`, \`.filter()\`, etc.):
-
-\`\`\`typescript
-// ✅ Correct
-users.map((user) => user.email)
-items.filter((item) => item.isActive)
-
-// ❌ Wrong
-users.map((u) => u.email)
-items.filter((i) => i.isActive)
-\`\`\`
-
-## Utility Functions
-
-Import from \`@/lib/utils\`:
-
-\`\`\`typescript
-import { cn, formatDate, formatRelative, debounce } from '@/lib/utils';
-
-// Class name merging (shadcn/ui)
-cn('text-sm', isActive && 'text-blue-500')
-
-// Date formatting with Luxon
-formatDate(new Date())                    // "Jan 15, 2024"
-formatDate('2024-01-15', 'yyyy-MM-dd')   // "2024-01-15"
-formatRelative(new Date())                // "2 hours ago"
-
-// Debounce function calls
-const debouncedSearch = debounce((query: string) => {
-  // search logic
-}, 300);
-\`\`\`
-
-## Environment Variables
-
-Copy \`.env.example\` to \`.env.local\` and fill in your API keys.
-
-**Important:** Import environment variables from \`@/lib/config\`:
-
-\`\`\`typescript
-// ✅ Good
-import { STRIPE_SECRET_KEY } from '@/lib/config';
-
-// ❌ Avoid
-const key = process.env.STRIPE_SECRET_KEY;
-\`\`\`
+    content += `
+## Client State Management (Zustand)
+
+For complex multi-step forms or flows, use Zustand stores.
+
+**Store location**: \`lib/stores/*.store.ts\`
+
+### Store Pattern
+
+\`\`\`typescript
+import { createStore, useStore } from 'zustand';
+
+interface FormState {
+  title: string;
+  description: string;
+  setTitle: (title: string) => void;
+  setDescription: (description: string) => void;
+  reset: () => void;
+}
+
+const initialState = {
+  title: '',
+  description: '',
+};
+
+export const formStore = createStore<FormState>()((set) => ({
+  ...initialState,
+  setTitle: (title) => set({ title }),
+  setDescription: (description) => set({ description }),
+  reset: () => set(initialState),
+}));
+
+export const useFormStore = <T>(selector: (state: FormState) => T): T => {
+  return useStore(formStore, selector);
+};
+\`\`\`
+
+### Usage in Components
+
+\`\`\`tsx
+'use client';
+
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+
+function TitleStep() {
+  const title = useFormStore((state) => state.title);
+  const setTitle = useFormStore((state) => state.setTitle);
+
+  return (
+    <div className="space-y-2">
+      <Label htmlFor="title">Title</Label>
+      <Input
+        id="title"
+        value={title}
+        onChange={(e) => setTitle(e.target.value)}
+        placeholder="Enter a title"
+      />
+    </div>
+  );
+}
+\`\`\`
+
+## Code Style
+
+### No Comments
+
+Do not add comments to the codebase. Code should be self-documenting through:
+- Clear, descriptive variable and function names
+- Proper TypeScript types
+- Logical code structure
+- Small, focused functions
+
+### Closure Variable Naming
+
+Always use verbose singular names in closures (\`.map()\`, \`.filter()\`, etc.):
+
+\`\`\`typescript
+// ✅ Correct
+users.map((user) => user.email)
+items.filter((item) => item.isActive)
+
+// ❌ Wrong
+users.map((u) => u.email)
+items.filter((i) => i.isActive)
+\`\`\`
+
+### Server vs Client Components
+
+Page files (\`page.tsx\`) must be server components - do NOT add \`"use client"\` to pages. Extract interactive parts into separate client component files.
+
+\`\`\`
+app/settings/
+  page.tsx                      # Server component (NO "use client")
+  components/
+    settings-form.tsx           # Client component ("use client")
+app/dashboard/components/       # Shared components for sibling pages
+\`\`\`
+
+### No Module-Scope Mutable State
+
+Do NOT use \`let\` variables at module scope. Modules are cached and state leaks between SSR requests.
+
+\`\`\`typescript
+// ❌ Wrong - module-scope mutable state
+let nextId = 1;
+
+// ✅ Correct - generate inline
+crypto.randomUUID();
+\`\`\`
+
+### User-Friendly Errors
+
+All error messages shown to users must be actionable and understandable. Do NOT expose technical errors. Log technical details to \`console.error()\`, show friendly messages to users.
+
+\`\`\`typescript
+// ❌ Wrong - technical error
+return { error: "User ID is missing from request" };
+
+// ✅ Correct - user-friendly
+return { error: "Something went wrong. Please try again." };
+\`\`\`
+
+### Date Manipulation with Luxon
+
+Use Luxon for all date manipulation. Do NOT manually construct ISO date strings.
+
+\`\`\`typescript
+// ❌ Wrong - manual string construction
+const dateFrom = \`\${year}-\${String(month).padStart(2, "0")}-01\`;
+
+// ✅ Correct - use Luxon
+import { DateTime } from "luxon";
+const startOfMonth = DateTime.local(year, month, 1);
+const dateFrom = startOfMonth.toISODate()!;
+const dateTo = startOfMonth.plus({ months: 1 }).toISODate()!;
+\`\`\`
+
+### Zod Patterns
+
+Use \`z.iso.date()\` for ISO date strings (NOT the deprecated \`z.string().date()\`).
+
+Use \`z.enum(TheEnum)\` for enum validation (NOT \`z.nativeEnum\` or \`Object.values\`).
+
+For JSON array fields in form schemas, use \`z.preprocess\`:
+
+\`\`\`typescript
+// ✅ Correct - preprocess handles JSON, Zod validates the array
+export const MyFormSchema = z.object({
+  items: z.preprocess(
+    (val) => (typeof val === "string" ? JSON.parse(val) : val),
+    ItemSchema.array()
+  ),
+});
+
+// ❌ Wrong - transform with manual error handling
+items: z.string().transform((val, ctx) => { ... ctx.addIssue(...) })
+\`\`\`
+
+## Utility Functions
+
+Import from \`@/lib/utils\`:
+
+\`\`\`typescript
+import { cn, formatDate, formatRelative, debounce } from '@/lib/utils';
+
+// Class name merging (shadcn/ui)
+cn('text-sm', isActive && 'text-blue-500')
+
+// Date formatting with Luxon
+formatDate(new Date())                    // "Jan 15, 2024"
+formatDate('2024-01-15', 'yyyy-MM-dd')   // "2024-01-15"
+formatRelative(new Date())                // "2 hours ago"
+
+// Debounce function calls
+const debouncedSearch = debounce((query: string) => {
+  // search logic
+}, 300);
+\`\`\`
+
+## Environment Variables
+
+Copy \`.env.example\` to \`.env\` and fill in your API keys.
+
+**Important:** Import environment variables from \`@/lib/config\`:
+
+\`\`\`typescript
+// ✅ Good
+import { STRIPE_SECRET_KEY } from '@/lib/config';
+
+// ❌ Avoid
+const key = process.env.STRIPE_SECRET_KEY;
+\`\`\`
 `;
     if (hasClerk) {
-        content += `
-## Authentication
-
-**Provider:** Clerk
-
-- Route protection via \`proxy.ts\` (Next.js 16+)
-- Use \`currentUser()\` in Server Components and Actions for auth checks
-- Client-side: Use Clerk hooks (\`useUser()\`, \`useAuth()\`, \`<SignedIn>\`, \`<SignedOut>\`)
-
-\`\`\`typescript
-// Server-side auth check
-const user = await currentUser();
-if (!user) {
-  return redirect('/');
-}
-\`\`\`
+        content += `
+## Authentication
+
+**Provider:** Clerk
+
+- Route protection via \`proxy.ts\` (Next.js 16+)
+- Use \`currentUser()\` in Server Components and Actions for auth checks
+- Client-side: Use Clerk hooks (\`useUser()\`, \`useAuth()\`, \`<SignedIn>\`, \`<SignedOut>\`)
+
+\`\`\`typescript
+// Server-side auth check
+const user = await currentUser();
+if (!user) {
+  return redirect('/');
+}
+\`\`\`
 `;
     }
     await fs.writeFile(path.join(projectPath, 'CLAUDE.md'), content);