nextjs-hackathon-stack 0.1.40 → 0.1.41

package/template/.claude/agents/test-qa.md

@@ -0,0 +1,85 @@
+---
+name: test-qa
+description: Testing specialist. Use when writing tests, enforcing TDD workflow, fixing coverage gaps, or debugging test failures. Always write tests BEFORE implementation. Triggers: writing tests, TDD workflow, coverage gaps, test failures, mock setup.
+---
+
+# Test & QA Agent
+
+## First Step — Load Context via MCP Memory
+
+1. Read `package.json` to get the project name (`<project-name>`)
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:patterns"]` and `query: "test mock supabase"` — canonical test references and mock setup (`makeChain`, `makeSupabaseMock`)
+3. **Fallback**: if the memory service is unavailable or returns no results, read `.cursor/memory/architecture-snapshot.md` directly
+
+Import `makeChain` and `makeSupabaseMock` from `@/shared/test-utils/supabase-mock` — never recreate the mock chain from scratch.
+
+## TDD Workflow
+
+1. **RED** — write failing test that describes the desired behavior
+2. **GREEN** — write minimum code to make test pass
+3. **REFACTOR** — clean up while keeping tests green
+4. **VERIFY** — run `pnpm test:coverage` and confirm 100%
+
+## Verification Gates (mandatory — show output, do not just claim)
+
+Each phase requires pasting the actual terminal output before proceeding:
+
+| Gate | Command | Expected output |
+|------|---------|-----------------|
+| After RED | `pnpm test:unit` | All new tests **FAIL** (red) |
+| After GREEN | `pnpm test:unit` | All tests **PASS** (green) |
+| After VERIFY | `pnpm test:coverage` | ≥95% statements/functions/lines, ≥90% branches |
+
+**Never say "tests pass" or "tests fail" without showing the actual output.**
+**Do NOT write any implementation code until the RED gate output confirms failures.**
+
+## Key Rules (auto-loaded by file context)
+- Testing standards, AAA pattern, coverage: `testing.mdc`
+- TDD iron rules: `coding-standards.mdc`
+
+## Coverage Requirement
+```
+branches: 90%
+functions: 95%
+lines: 95%
+statements: 95%
+```
+
+Use `/* v8 ignore next */` for genuinely unreachable defensive branches only.
+
+After every change:
+1. Run `pnpm test:coverage`
+2. If below thresholds, add missing tests
+3. Never mark work complete without meeting thresholds
+
+## Supabase Mock Pattern
+
+Always use the shared helpers — never inline mock chain construction:
+
+```typescript
+import { makeChain, makeSupabaseMock } from "@/shared/test-utils/supabase-mock";
+
+// Unauthenticated
+const { mockClient } = makeSupabaseMock({ user: null });
+
+// Authenticated + DB success
+const { mockClient, mockFrom } = makeSupabaseMock({ user: { id: "user-1" } });
+mockFrom.mockReturnValue(makeChain({ data: [...], error: null }));
+
+// DB error
+mockFrom.mockReturnValue(makeChain({ error: { message: "db error" } }));
+```
+
+## Test Plan Compliance
+
+When the Technical Lead provides a test plan, follow it:
+- Use the specified test files, `describe` block names, and mock setup
+- Flag missing edge cases to the TL **before** adding unplanned tests — do not expand scope unilaterally
+- If the plan is ambiguous or incomplete, ask for clarification rather than guessing
+
+For the full Server Action test template, see `build-feature` skill references (`references/server-action-test-template.md`).
+
+## Guardrails
+- Never write implementation without a failing test first
+- Never mock internal project code — only external deps
+- Verify all edge cases: empty states, errors, loading states

package/template/.claude/rules/architecture.mdc

@@ -0,0 +1,48 @@
+---
+description: Feature-based architecture rules. Applies to all source files.
+alwaysApply: false
+globs: ["src/**"]
+---
+
+# Architecture Rules
+
+## Feature-Based Structure
+```
+features/
+└── <feature-name>/
+    ├── components/     # React components
+    ├── actions/        # Server Actions (*.action.ts)
+    ├── queries/        # Read queries — *.queries.ts (repository layer)
+    ├── hooks/          # React hooks (use-*.ts)
+    ├── api/            # Route handlers (route.ts)
+    ├── lib/            # Feature-specific utilities, schemas, and types
+    └── __tests__/      # Colocated tests
+```
+
+## Dependency Direction
+```
+features/* → shared/*   ✅
+shared/* → features/*   ❌ (circular dependency)
+features/a → features/b ❌ (cross-feature import)
+```
+
+If two features share logic, move it to `shared/`.
+
+## Layer Rules
+- `app/` — routing, layouts, RSC data fetching
+- `features/` — feature business logic, UI, actions
+- `shared/lib/` — infrastructure (supabase, ai, db)
+- `shared/components/` — design system components
+
+## Error Boundaries
+- Place at route level (`app/(protected)/layout.tsx`)
+- Never let unhandled errors propagate to root
+
+## Server Actions
+- File naming: `name.action.ts`
+- Always `"use server"` at top of file
+- Validate input with Zod before any business logic
+- Return typed result objects, use `redirect()` for navigation
+- Actions that mutate data must return `ActionResult` from `@/shared/lib/action-result` — never return `void`
+- The calling component is responsible for showing `toast.success()` / `toast.error()` based on the result
+- NEVER import or call client-only APIs inside server actions (`toast` from sonner, React hooks, `window`, `document`). Server actions run on the server where these APIs do not exist and will throw at runtime.

package/template/.claude/rules/coding-standards.mdc

@@ -0,0 +1,120 @@
+---
+description: Code quality standards. Applies to TypeScript/TSX source files.
+alwaysApply: false
+globs: ["src/**/*.ts", "src/**/*.tsx"]
+---
+
+# Coding Standards
+
+## Absolute Rules
+- **Zero `any`** — use `unknown` + type guards or proper generics. `@typescript-eslint/no-explicit-any: error`
+- **Zero comments in production code** — code must be self-documenting through naming. Test AAA labels (`// Arrange`, `// Act`, `// Assert`) are required in tests.
+- **Zero magic numbers/strings** — use typed constants
+- **No `console.log`** in production code — `no-console: "error"`
+- **No `!` non-null assertions** — use proper null checks
+- **No `eslint-disable` inline comments** — fix the code instead. If a rule conflict is truly unavoidable (e.g. third-party API with no non-deprecated alternative), add a file-level override in `eslint.config.ts` with a `// TODO` comment explaining why.
+
+## AI Agent Lint Pre-Flight
+
+Before writing any code, internalize these rules. The project runs `eslint --max-warnings 0` — any violation blocks commits. These are the patterns that most commonly trip AI code generation:
+
+- **`no-console: "error"`** — never use `console.*` in production code. Use proper error handling (`throw`) or `ActionResult` error returns.
+- **`strict-boolean-expressions`** — never write `if (value)` for non-boolean types. Use explicit checks:
+  - `string`: `if (str !== "")`
+  - `number`: `if (n !== 0)`
+  - `T | null | undefined`: `if (value !== null && value !== undefined)`
+  - `T[]`: `if (array.length > 0)`
+  - JSX: `{condition !== null && condition !== undefined && <Component />}`
+- **`naming-convention`** — `camelCase` for variables/functions, `PascalCase` for types/interfaces/React components, `UPPER_CASE` allowed for constants. Never use `snake_case` except in `property` selectors (DB columns, JSON keys).
+- **`no-floating-promises`** — always `await` or prefix with `void` for fire-and-forget.
+- **`restrict-template-expressions`** — never interpolate non-string/number values directly: `` `${someObject}` `` → `` `${someObject.toString()}` ``.
+- **`no-unnecessary-condition`** — never check conditions that the type system proves always truthy/falsy.
+- **`no-unsafe-*`** — never pass `any`-typed values to typed parameters. Narrow with Zod or type guards first.
+
+> **Rule of thumb**: If unsure whether a pattern is valid, read `eslint.config.ts` before writing.
+
+## TDD
+
+Follow the RED → GREEN → REFACTOR cycle. See `testing.mdc` for the full rules and iron rules. Summary: never write implementation without a prior failing test.
+
+## SOLID Principles
+- **S**ingle Responsibility: one reason to change per module
+- **O**pen/Closed: extend behavior without modifying existing code
+- **L**iskov Substitution: subtypes must be substitutable for base types
+- **I**nterface Segregation: prefer small, focused interfaces
+- **D**ependency Inversion: depend on abstractions, not concretions
+
+## KISS & DRY
+- Simplest solution that works — no over-engineering
+- Three similar lines is better than a premature abstraction
+- Extract abstraction only when you have 3+ real use cases
+
+## Size Limits
+- Functions: max 20 lines
+- Files: max 200 lines
+- If exceeded, split by responsibility
+
+## Error Handling
+- Use `Result` types for expected failures
+- Never swallow errors silently
+- Always handle Promise rejections
+
+## Types
+- Prefer `interface` for object shapes (enforced by ESLint `consistent-type-definitions`). Use `type` for unions, intersections, and utility types.
+- Use `satisfies` for type-checked literals
+- Use `as const` for immutable literals
+- **Never use `as` type assertions for data from external sources** (DB, API, user input). Use Zod `.parse()` or `.safeParse()` to validate and type runtime data. `as const` is acceptable for literals.
+
+```typescript
+// ✅
+const schema = z.array(supportItemSchema);
+const items = schema.parse(data);
+
+// ❌
+const items = data as SupportListItem[];
+```
+
+## Language Rules
+
+- **Code-level text must be in English**: test `it()` descriptions, `describe()` block names, variable names, code comments, developer-facing `Error` constructor messages (never shown to users), `console` output
+- **User-facing text stays in the target language**: UI labels, placeholders, toast messages, form validation messages shown on screen, `ActionResult` error/success strings that end up displayed in the UI
+
+```typescript
+// ✅ Code-level: English
+it("returns error when candidate is not found", async () => { ... });
+throw new Error("Unexpected DB response shape"); // developer-facing, never shown in UI
+
+// ✅ User-facing: target language (Spanish)
+return { success: false, error: "Candidato no encontrado" }; // shown in toast
+toast.error("No se pudo guardar el cambio");
+
+// ❌ Wrong: code-level in wrong language
+it("retorna error si el candidato no existe", async () => { ... });
+```
+
+## Coverage Exclusions (configure upfront, not reactively)
+
+Before writing tests, add exclusions to `vitest.config.ts` for:
+- Drizzle schema definition files (`src/shared/db/*.schema.ts`)
+- Pure type files (files with only `type`/`interface` exports, no runtime logic)
+- Third-party UI wrapper components that rely on portals or browser APIs not supported in jsdom (e.g., `sonner.tsx`, toast providers)
+
+Configure these exclusions **before writing tests** to avoid reactive coverage fixes mid-implementation.
+
+```typescript
+// vitest.config.ts
+coverage: {
+  exclude: [
+    "src/shared/db/*.schema.ts",
+    "src/shared/components/ui/sonner.tsx",
+    // add other portal/type-only files here
+  ],
+}
+```
+
+## Pre-commit Quality Gates
+Every commit must pass two sequential gates:
+1. **lint-staged** — runs `eslint --max-warnings 0` on staged `.ts/.tsx` files. Any lint warning or error blocks the commit immediately (before the slower test suite runs).
+2. **Full test suite** — runs `vitest run --coverage` with 95% statement/function/line and 90% branch coverage required.
+
+Code that fails either gate cannot be committed.

package/template/.claude/rules/components.mdc

@@ -0,0 +1,49 @@
+---
+description: shadcn/ui and Tailwind v4 component standards.
+globs: ["src/**/components/**"]
+alwaysApply: false
+---
+
+# Component Standards
+
+## shadcn/ui
+- Use shadcn/ui components from `@/shared/components/ui/`
+- Never build custom UI primitives when shadcn has one
+- Extend with `className` prop via `cn()` utility
+- New York style, CSS variables for theming
+
+## shadcn/ui (MCP + CLI)
+- **MCP tools** (preferred): `shadcn_search`, `shadcn_docs`, `shadcn_install`, `shadcn_diff`
+- Before writing component code, use `shadcn_docs <component>` to get up-to-date API and usage patterns
+- Use `shadcn_search <query>` to discover available components
+- Install components with `shadcn_install` or `shadcn add <component>` — never copy-paste component source manually
+- Use `shadcn_diff <component>` to check for upstream changes to already-installed components
+- The shadcn skill (`pnpm dlx skills add shadcn/ui`) is installed during scaffolding — provides project context automatically
+
+## Tailwind v4
+- CSS-native config via `@theme {}` in CSS
+- No `tailwind.config.js` — all config in `tailwind.css`
+- No inline styles, no CSS modules
+- Use Tailwind utility classes only
+
+## Design Tokens (Required)
+- Always use semantic token classes (`bg-primary`, `text-destructive`, `text-muted-foreground`, `border-border`, etc.)
+- Never use raw Tailwind palette colors (`bg-blue-500`, `text-gray-700`, `text-red-500`, etc.)
+- All colors must reference CSS variables defined in `@theme {}` in `tailwind.css`
+- Available semantic colors: primary, secondary, accent, destructive, success, warning, info, muted, background, foreground, border, input, ring
+- If a needed color does not exist as a token, add it to `@theme {}` in `tailwind.css` first
+
+## Accessibility (Required)
+- Semantic HTML elements (`<button>`, `<nav>`, `<main>`, etc.)
+- ARIA labels for interactive elements without visible text
+- Keyboard navigation support
+- Color contrast ratios (WCAG AA minimum)
+- `role="alert"` for error messages
+
+## Server vs Client Components
+- Default to Server Components (no `"use client"`)
+- Add `"use client"` only when you need:
+  - Event handlers (`onClick`, `onChange`, etc.)
+  - Hooks (`useState`, `useEffect`, etc.)
+  - Browser APIs
+- Keep Client Components small — push them to leaf nodes

package/template/.claude/rules/data-fetching.mdc

@@ -0,0 +1,115 @@
+---
+description: TanStack Query vs RSC data fetching boundaries. Applied when working on components, pages, queries, hooks, or actions.
+globs: ["src/**/components/**", "src/**/queries/**", "src/**/hooks/**", "src/**/actions/**", "src/app/**"]
+alwaysApply: false
+---
+
+# Data Fetching Rules (Risk 1: TanStack Query + RSC Boundary)
+
+## Hard Boundary
+
+| Use Case | Where |
+|---|---|
+| Initial page data | RSC `async` Server Component |
+| Background refresh / polling | TanStack Query |
+| User-triggered client reads | TanStack Query |
+| All mutations | Server Actions ONLY |
+
+**Never use TanStack Query mutations. Never use `useMutation`.**
+
+## WRONG ❌
+```typescript
+// ❌ Fetching initial data in a Client Component with TanStack Query
+"use client";
+export function UserProfile({ userId }: { userId: string }) {
+  const { data } = useQuery({
+    queryKey: ["user", userId],
+    queryFn: () => fetchUser(userId), // Initial data should come from RSC
+  });
+  return <div>{data?.name}</div>;
+}
+
+// ❌ Mutation with TanStack Query
+const mutation = useMutation({
+  mutationFn: (data) => updateUser(data), // Use Server Action instead
+});
+```
+
+## CORRECT ✅
+```typescript
+// ✅ Initial data from RSC via feature's queries/ module
+import { getUserById } from "@/features/users/queries/users.queries";
+
+export default async function UserPage({ params }: { params: { id: string } }) {
+  const supabase = await createClient();
+  const { data: user } = await getUserById(supabase, params.id); // via repository
+  return <UserProfile initialUser={user} />;
+}
+
+// ✅ TanStack Query for background refresh only
+// queryFn must call a function from the feature's queries/ module — never inline supabase.from() here
+"use client";
+export function UserProfile({ initialUser }: { initialUser: User }) {
+  const { data: user } = useQuery({
+    queryKey: ["user", initialUser.id],
+    queryFn: () => fetchUser(initialUser.id), // fetchUser lives in features/users/queries/
+    initialData: initialUser, // Seeded from RSC
+    staleTime: 5 * 60 * 1000,
+  });
+  return <div>{user.name}</div>;
+}
+
+// ✅ Mutation via Server Action
+async function updateUserAction(formData: FormData) {
+  "use server";
+  await db.update(users).set({ name: formData.get("name") });
+  revalidatePath("/profile");
+}
+```
+
+## Error Handling
+
+TanStack Query errors must be handled via the `error` property — never swallow them silently.
+
+- **Data queries** (background reads): show an inline error state in the component
+- **User-triggered actions**: show a toast via `sonner` (see `forms.mdc` Pattern A)
+
+```typescript
+"use client";
+export function UserProfile({ initialUser }: { initialUser: User }) {
+  const { data: user, error } = useQuery({
+    queryKey: ["user", initialUser.id],
+    queryFn: () => fetchUser(initialUser.id),
+    initialData: initialUser,
+  });
+
+  if (error) return <p role="alert">Failed to load user data.</p>;
+  return <div>{user.name}</div>;
+}
+```
+
+## Cache Invalidation After Server Actions
+
+After a Server Action mutates data, invalidate the relevant TanStack Query cache so the UI reflects the new state.
+
+```typescript
+// In the calling component (Client Component)
+import { useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+
+const queryClient = useQueryClient();
+
+startTransition(async () => {
+  const result = await updateUserAction(formData);
+  if (result.status === "success") {
+    // Invalidate cache so background queries re-fetch with fresh data
+    await queryClient.invalidateQueries({ queryKey: ["user", userId] });
+    toast.success(result.message);
+  } else {
+    toast.error(result.message);
+  }
+});
+```
+
+> **Note on optimistic updates**: Full optimistic updates use `onMutate` + rollback on failure (`onError`). Do not implement this pattern until you have a concrete use case — `invalidateQueries` is simpler and sufficient for most scenarios.
+

package/template/.claude/rules/forms.mdc

@@ -0,0 +1,100 @@
+---
+description: React Hook Form + Server Actions pattern. Client-side validation via zodResolver + server-side revalidation in the action.
+globs: ["src/**/*form*", "src/**/*.action.ts"]
+alwaysApply: false
+---
+
+# Forms Pattern (Risk 4: RHF + Server Actions)
+
+## The One Pattern
+
+```
+Client: RHF + zodResolver → client validation (UX)
+     ↓ valid
+Server Action → zod validate again (security) → business logic
+```
+
+Zod validates TWICE:
+1. Client-side: immediate UX feedback via RHF
+2. Server-side: never trust the client
+
+## Template
+```typescript
+// form.tsx (client)
+"use client";
+const schema = z.object({ email: z.string().email() });
+type FormValues = z.infer<typeof schema>;
+
+export function MyForm() {
+  const [state, formAction, isPending] = useActionState(myAction, { status: "idle" });
+  const { register, handleSubmit, formState: { errors } } = useForm<FormValues>({
+    resolver: zodResolver(schema),
+  });
+
+  const onSubmit = handleSubmit((data) => {
+    const fd = new FormData();
+    Object.entries(data).forEach(([k, v]) => fd.set(k, String(v)));
+    formAction(fd);
+  });
+
+  return (
+    <form onSubmit={onSubmit}>
+      {state.status === "error" && <p role="alert">{state.message}</p>}
+      <input {...register("email")} />
+      {errors.email && <p>{errors.email.message}</p>}
+      <button disabled={isPending}>Submit</button>
+    </form>
+  );
+}
+
+// action.ts (server)
+"use server";
+const schema = z.object({ email: z.string().email() });
+
+export async function myAction(_prev: State, formData: FormData): Promise<State> {
+  const parsed = schema.safeParse({ email: formData.get("email") });
+  if (!parsed.success) return { status: "error", message: parsed.error.issues[0]?.message ?? "Invalid" };
+  // business logic...
+  redirect("/success");
+}
+```
+
+## Shared Schema
+
+Share the Zod schema between client and server from a single source (e.g., `lib/schemas.ts` or the Drizzle-generated schema via `drizzle-zod`) to avoid drift. The template above defines `schema` twice as an illustration — in production, import it from a shared module.
+
+## Toast Feedback
+
+> **⚠️ Toast calls belong in client components ONLY.** Never import `sonner` or call `toast()` inside a `"use server"` file. The server action returns `ActionResult`; the component reads the result and shows the toast.
+
+Every action that affects the database MUST show a toast to the user. No mutation should complete silently.
+
+- Use `toast.success(message)` for successful operations
+- Use `toast.error(message)` for failed operations
+- Import `toast` from `sonner`
+- Server actions that mutate data must return `ActionResult` from `@/shared/lib/action-result` (not `void`)
+- Exception: if the action redirects to another page on success, no success toast is needed (the user sees the new page)
+
+### Pattern A — Direct action call (button onClick, non-`useActionState` forms)
+```typescript
+import { toast } from "sonner";
+import type { ActionResult } from "@/shared/lib/action-result";
+
+startTransition(async () => {
+  const result = await myAction(id);
+  if (result.status === "success") toast.success(result.message);
+  else toast.error(result.message);
+});
+```
+
+### Pattern B — `useActionState` forms
+```typescript
+import { useEffect } from "react";
+import { toast } from "sonner";
+
+const [state, formAction] = useActionState(myAction, { status: "idle" });
+
+useEffect(() => {
+  if (state.status === "error") toast.error(state.message);
+}, [state]);
+```

package/template/.claude/rules/general.mdc

@@ -0,0 +1,54 @@
+---
+description: Stack overview and project conventions. Always loaded — defines the technology stack, project structure, and naming conventions for this project.
+alwaysApply: true
+---
+
+# Stack Overview
+
+## Technology Stack
+- **Framework**: Next.js 16.2 (App Router)
+- **Database**: Supabase (PostgreSQL) with Drizzle ORM for schema/migrations
+- **Auth**: Supabase Auth via `@supabase/ssr`
+- **ORM**: Drizzle + `drizzle-zod` (schema + migrations ONLY — no runtime queries)
+- **DB Runtime Queries**: `supabase-js` client (RLS active)
+- **Client State**: TanStack Query v5
+- **Validation**: Zod (auto-generated via `drizzle-zod`)
+- **Forms**: React Hook Form + Zod resolver
+- **UI**: shadcn/ui + Tailwind CSS v4 (shadcn skill installed for AI context)
+- **AI**: Vercel AI SDK + Google Gemini 2.0 Flash via AI Gateway
+- **Testing**: Vitest + React Testing Library + Playwright
+
+## Project Structure
+```
+src/
+├── app/               # Next.js App Router pages
+├── features/          # Feature modules (auth, chat)
+│   └── <feature>/
+│       ├── components/
+│       ├── actions/
+│       ├── queries/
+│       ├── hooks/
+│       ├── api/
+│       ├── lib/
+│       └── __tests__/
+├── shared/            # Shared across features
+│   ├── components/ui/ # shadcn/ui components
+│   ├── lib/           # supabase, ai, utilities
+│   └── db/            # Drizzle schema + migrations
+└── e2e/               # Playwright tests
+```
+
+## Naming Conventions
+- Files: `kebab-case.ts`
+- Components: `PascalCase`
+- Hooks: `useCamelCase`
+- Server Actions: `kebab-case.action.ts`
+- API Routes: `route.ts` (in feature `api/` folder)
+- Tests: `*.test.ts` or `*.test.tsx`
+- E2e: `*.spec.ts`
+
+## Import Ordering
+1. Node built-ins
+2. External packages
+3. Internal (`@/`)
+4. Relative (`./`, `../`)

package/template/.claude/rules/migrations.mdc

@@ -0,0 +1,11 @@
+---
+description: Migration files are auto-generated by Drizzle CLI. NEVER create, edit, or delete them directly.
+globs: ["src/shared/db/migrations/**"]
+alwaysApply: false
+---
+
+# Migration Files — Generated Artifacts
+
+Files in `src/shared/db/migrations/` are **auto-generated**. See `supabase.mdc` for the full migration workflow and CLI commands.
+
+**Never create, edit, or delete migration files by hand.**

package/template/.claude/rules/nextjs.mdc

@@ -0,0 +1,71 @@
+---
+description: Next.js 16.2 App Router patterns.
+globs: ["src/app/**"]
+alwaysApply: false
+---
+
+# Next.js 16.2 Rules
+
+## App Router Conventions
+- `page.tsx` — public route page component
+- `layout.tsx` — shared layout (wraps child pages)
+- `loading.tsx` — Suspense boundary UI
+- `error.tsx` — Error boundary UI
+- `route.ts` — API route handler
+- `proxy.ts` — Request proxy (project root, Node.js runtime). Intercepts and rewrites requests before they reach route handlers (e.g., session validation, redirects).
+
+## Route Groups
+- `(auth)` — unauthenticated routes
+- `(protected)` — authenticated routes with RSC auth check
+
+## Data Fetching in RSC
+```typescript
+// ✅ Async Server Component — fetch directly
+export default async function Page() {
+  const data = await fetchData(); // No useState, no useEffect
+  return <ClientComponent initialData={data} />;
+}
+```
+
+## Route Handler Patterns
+```typescript
+// app/api/*/route.ts
+export async function POST(request: Request) {
+  const body = await request.json() as unknown;
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) return Response.json({ error: "Invalid input" }, { status: 400 });
+  // ...
+}
+```
+
+## Metadata
+```typescript
+export const metadata: Metadata = {
+  title: "Page Title",
+  description: "Page description",
+};
+```
+
+## Browser Log Forwarding
+
+Next.js 16.2 can forward browser logs to the terminal. Configure in `next.config.ts`:
+
+```typescript
+const nextConfig: NextConfig = {
+  logging: {
+    browserToTerminal: 'error', // 'error' (default) | 'warn' | true (all) | false (disabled)
+  },
+};
+```
+
+- `'error'` — forwards browser errors only (default)
+- `'warn'` — forwards errors and warnings
+- `true` — forwards all console output
+- `false` — disabled
+
+## Dev Server Lock File
+
+Next.js 16.2 writes `.next/dev/lock` when `next dev` starts. The file contains the PID, port, and URL of the running dev server.
+
+- Agents and scripts must check `.next/dev/lock` before starting `next dev` or `next build` to avoid duplicate processes.
+- If the lock file exists and the PID is still alive, attach to the existing server instead of starting a new one.