@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/docs/plans/2026-02-23-nextjs-standards-impl.md

@@ -0,0 +1,1846 @@
+# Next.js Standards Package Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a comprehensive Next.js standards package to morph-spec-framework covering standards files, a rule file, a validator, templates, and an enhanced agent for the stack: Next.js App Router + shadcn/ui + TanStack Query + react-hook-form/Zod + EasyPanel/Docker.
+
+**Architecture:** 8 standards files in `framework/standards/frontend/nextjs/`, 1 Claude Code rule file in `framework/rules/`, 1 validator module in `src/lib/validators/nextjs/`, 6 Handlebars templates in `framework/templates/frontend/nextjs/`, an updated `nextjs-expert` agent, and a regenerated STANDARDS.json. All content is opinionated for the locked stack — no generic fallbacks.
+
+**Tech Stack:** Node.js/ESM, Handlebars v2.0, Markdown, existing validator pattern from `src/lib/validators/blazor/blazor-validator.js`
+
+---
+
+## Locked Conventions (reference throughout)
+
+- **Files:** kebab-case (`user-card.tsx`)
+- **Exports:** PascalCase components (`UserCard`), camelCase hooks (`useCreateUser`)
+- **Hooks:** file `use-{action}.ts`, export `use{Action}()`
+- **Schemas:** `{feature}.schemas.ts` with `z.infer<>` for types
+- **Folders:** feature-based with `features/{name}/components|hooks|types/`
+- **Shared components:** `components/ui/` (shadcn, never edit) → `components/` (composed, no business logic) → `features/*/components/` (feature-scoped)
+- **Data:** Server Components for initial fetch, TanStack Query for mutations/client state
+- **Forms:** react-hook-form + Zod + shadcn `<Form>`
+- **Deployment:** EasyPanel → Docker multi-stage
+
+---
+
+### Task 1: Create 8 standards files
+
+**Files:**
+- Create: `framework/standards/frontend/nextjs/app-router.md`
+- Create: `framework/standards/frontend/nextjs/project-structure.md`
+- Create: `framework/standards/frontend/nextjs/naming-conventions.md`
+- Create: `framework/standards/frontend/nextjs/components.md`
+- Create: `framework/standards/frontend/nextjs/data-fetching.md`
+- Create: `framework/standards/frontend/nextjs/forms.md`
+- Create: `framework/standards/frontend/nextjs/state-management.md`
+- Create: `framework/standards/frontend/nextjs/testing.md`
+
+**Note:** No tests for content files. Write directly.
+
+**Step 1: Create `framework/standards/frontend/nextjs/app-router.md`**
+
+```markdown
+# Next.js App Router Standard
+
+> **Scope:** frontend/nextjs/app-router
+> **Layer:** 2 (on keyword)
+> **Keywords:** next.js, app router, server component, client component, page, layout, route
+> **Load When:** editing files in `app/` or `features/` directories
+
+Next.js App Router with TypeScript strict mode. Server Components by default, Client Components only when interactivity is required.
+
+## Core Rules
+
+- ALWAYS default to Server Components — add `'use client'` only when needed
+- ALWAYS keep `app/` directory for routing only — no business logic in page files
+- NEVER put data fetching in Client Components when a Server Component can do it
+- NEVER use `useEffect` to fetch data — use Server Components or TanStack Query
+- ALWAYS co-locate loading/error UI: `loading.tsx`, `error.tsx` next to `page.tsx`
+- ALWAYS use TypeScript — no `.js` or `.jsx` files in the project
+
+## Server vs Client Components
+
+| Use Server Component | Use Client Component |
+|---------------------|---------------------|
+| Fetching from .NET API on load | onClick, onChange, form submit |
+| Rendering static or user-specific data | useState, useEffect, useRef |
+| Accessing backend environment variables | Browser APIs (localStorage, geolocation) |
+| SEO-critical content | TanStack Query hooks |
+| No interactivity needed | shadcn/ui interactive components |
+
+## Decision Tree
+
+```
+Does this component need user interaction (click, input, hover state)?
+  YES → 'use client'
+  NO  → Does it fetch data?
+          YES → Server Component (fetch directly)
+          NO  → Server Component (static)
+```
+
+## App Directory Structure
+
+```
+src/app/
+├── (auth)/
+│   ├── login/
+│   │   └── page.tsx           # Server Component — renders login form
+│   └── register/
+│       └── page.tsx
+├── (dashboard)/
+│   ├── layout.tsx             # Shared layout for dashboard routes
+│   ├── page.tsx               # Dashboard home
+│   └── users/
+│       ├── page.tsx           # User list (Server Component)
+│       ├── [id]/
+│       │   └── page.tsx       # User detail
+│       ├── loading.tsx        # Suspense fallback
+│       └── error.tsx          # Error boundary
+└── layout.tsx                 # Root layout — providers, fonts, metadata
+```
+
+## File Conventions
+
+| File | Purpose | Type |
+|------|---------|------|
+| `page.tsx` | Route segment UI | Server Component (default) |
+| `layout.tsx` | Shared UI wrapper | Server Component |
+| `loading.tsx` | Suspense fallback | Server Component |
+| `error.tsx` | Error boundary | **Must be Client Component** |
+| `not-found.tsx` | 404 page | Server Component |
+| `route.ts` | API route (avoid — use .NET API) | — |
+
+## Server Component Data Fetch Pattern
+
+```tsx
+// app/(dashboard)/users/page.tsx
+import { UserList } from '@/features/users/components/user-list';
+
+async function getUsers(): Promise<User[]> {
+  const res = await fetch(`${process.env.API_URL}/api/users`, {
+    headers: { Authorization: `Bearer ${await getServerToken()}` },
+    next: { revalidate: 60 }, // ISR: revalidate every 60s
+  });
+  if (!res.ok) throw new Error('Failed to fetch users');
+  return res.json();
+}
+
+export default async function UsersPage() {
+  const users = await getUsers();
+  return <UserList initialUsers={users} />;
+}
+```
+
+## Root Layout — Required Providers
+
+```tsx
+// app/layout.tsx
+import { QueryProvider } from '@/lib/query-client';
+import { Toaster } from '@/components/ui/sonner';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="pt-BR">
+      <body>
+        <QueryProvider>
+          {children}
+          <Toaster />
+        </QueryProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `'use client'` on every component | Only add when needed | Kills SSR benefits, bloats JS bundle |
+| `useEffect(() => fetch(...), [])` | Server Component fetch or TanStack Query | Two renders, no caching, no SSR |
+| Business logic in `page.tsx` | Move to `features/` | pages are routes, not controllers |
+| `fetch` without error handling | Always check `res.ok` | Silent failures in production |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 2: Create `framework/standards/frontend/nextjs/project-structure.md`**
+
+```markdown
+# Next.js Project Structure Standard
+
+> **Scope:** frontend/nextjs/project-structure
+> **Layer:** 2 (on keyword)
+> **Keywords:** project structure, folder structure, feature folder, src layout
+> **Load When:** creating new files or features
+
+Feature-based architecture with a shared core. Features are self-contained; shared code is explicit.
+
+## Core Rules
+
+- ALWAYS use feature-based folders: `features/{feature-name}/`
+- ALWAYS keep `app/` for routing only — import from `features/`, not the other way
+- NEVER import from one feature into another — extract to `components/` or `lib/` if shared
+- ALWAYS use `src/` directory (configured in `tsconfig.json` with `@/` alias)
+- NEVER put business logic in `components/` — it is presentation only
+
+## Canonical Folder Tree
+
+```
+src/
+├── app/                                  # Next.js App Router — routes only
+│   ├── layout.tsx                        # Root layout + providers
+│   ├── page.tsx                          # Home page
+│   └── (dashboard)/
+│       ├── layout.tsx
+│       ├── users/
+│       │   ├── page.tsx                  # Renders UserPage from features/users
+│       │   ├── loading.tsx
+│       │   └── error.tsx
+│       └── billing/
+│           └── page.tsx
+│
+├── features/                             # Domain features
+│   └── {feature-name}/
+│       ├── components/                   # Feature-specific UI components
+│       │   ├── user-list.tsx
+│       │   └── user-card.tsx
+│       ├── hooks/                        # TanStack Query hooks for this feature
+│       │   ├── use-users.ts
+│       │   └── use-create-user.ts
+│       ├── types/
+│       │   ├── user.types.ts             # TypeScript types
+│       │   └── user.schemas.ts           # Zod schemas + z.infer<> types
+│       └── index.ts                      # Public API — only export what's needed
+│
+├── components/                           # Shared UI — no business logic
+│   ├── ui/                               # shadcn/ui — never edit directly
+│   │   ├── button.tsx
+│   │   └── card.tsx
+│   ├── data-table.tsx                    # Composed: TanStack Table + shadcn Table
+│   ├── page-header.tsx
+│   └── empty-state.tsx
+│
+├── hooks/                                # Shared utility hooks — no API calls
+│   ├── use-debounce.ts
+│   └── use-media-query.ts
+│
+├── lib/
+│   ├── api-client.ts                     # Typed fetch wrapper for .NET API
+│   └── query-client.tsx                  # TanStack Query client + provider
+│
+├── types/
+│   ├── api.ts                            # Shared API shapes: PaginatedResponse<T>, ApiError
+│   └── env.d.ts                          # Environment variable types
+│
+└── env.mjs                               # Zod-validated env vars — crashes at startup if missing
+```
+
+## Feature Index Pattern
+
+```ts
+// features/users/index.ts — explicit public API
+export { UserList } from './components/user-list';
+export { UserCard } from './components/user-card';
+export { useUsers } from './hooks/use-users';
+export { useCreateUser } from './hooks/use-create-user';
+export type { User, CreateUserInput } from './types/user.types';
+```
+
+Import from the index, not deep paths:
+```ts
+// GOOD
+import { UserList, useUsers } from '@/features/users';
+
+// BAD
+import { UserList } from '@/features/users/components/user-list';
+```
+
+## Feature Boundary Rule
+
+```
+app/ → imports from features/ ✓
+features/users/ → imports from components/ and lib/ ✓
+features/users/ → imports from features/billing/ ✗ (extract shared code instead)
+components/ → imports from components/ui/ ✓
+components/ → imports from features/ ✗
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 3: Create `framework/standards/frontend/nextjs/naming-conventions.md`**
+
+```markdown
+# Next.js Naming Conventions Standard
+
+> **Scope:** frontend/nextjs/naming-conventions
+> **Layer:** 1 (always)
+> **Keywords:** naming, conventions, file names, component names, hooks, typescript
+> **Load When:** creating any new file in a Next.js project
+
+Consistent naming prevents filesystem bugs (Linux case-sensitivity) and keeps the codebase predictable.
+
+## Core Rules
+
+- ALWAYS use kebab-case for file names — never PascalCase or camelCase
+- ALWAYS use PascalCase for React component exports
+- ALWAYS use camelCase starting with `use` for hook exports
+- ALWAYS suffix schema files with `.schemas.ts` and type files with `.types.ts`
+- NEVER mix cases in the same category — no `UserCard.tsx` alongside `user-profile.tsx`
+
+## Complete Reference Table
+
+| Artifact | File Name | Export Name | Example |
+|----------|-----------|-------------|---------|
+| React Component | `user-card.tsx` | `UserCard` | `export function UserCard()` |
+| Client Component | `user-form.tsx` | `UserForm` | `export function UserForm()` (+ `'use client'`) |
+| TanStack Query hook | `use-users.ts` | `useUsers` | `export function useUsers()` |
+| Mutation hook | `use-create-user.ts` | `useCreateUser` | `export function useCreateUser()` |
+| Utility hook | `use-debounce.ts` | `useDebounce` | `export function useDebounce()` |
+| Zod schema file | `user.schemas.ts` | `createUserSchema` | `export const createUserSchema = z.object(...)` |
+| TypeScript types | `user.types.ts` | `User`, `CreateUserInput` | `export type User = z.infer<typeof userSchema>` |
+| API utilities | `users-api.ts` | `fetchUsers` | `export async function fetchUsers()` |
+| Feature index | `index.ts` | (re-exports) | `export { UserCard } from './components/user-card'` |
+| Page file | `page.tsx` | `default` | `export default function UsersPage()` |
+
+## Component Naming Rules
+
+```
+Feature name:    users
+List component:  user-list.tsx        → UserList
+Card component:  user-card.tsx        → UserCard
+Form component:  user-form.tsx        → UserForm
+Dialog:          create-user-dialog.tsx → CreateUserDialog
+Table:           users-table.tsx      → UsersTable
+```
+
+## Hook Naming Rules
+
+```
+GET list:        use-users.ts          → useUsers()
+GET single:      use-user.ts           → useUser(id: string)
+POST:            use-create-user.ts    → useCreateUser()
+PUT/PATCH:       use-update-user.ts    → useUpdateUser()
+DELETE:          use-delete-user.ts    → useDeleteUser()
+```
+
+## Schema and Type Naming Rules
+
+```typescript
+// user.schemas.ts
+export const userSchema = z.object({ id: z.string(), name: z.string() });
+export const createUserSchema = z.object({ name: z.string().min(2), email: z.string().email() });
+export const updateUserSchema = createUserSchema.partial();
+
+// user.types.ts — derive from schemas, don't duplicate
+export type User = z.infer<typeof userSchema>;
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+export type UpdateUserInput = z.infer<typeof updateUserSchema>;
+```
+
+## Zod Schema Conventions
+
+| Operation | Schema Name | Derived Type |
+|-----------|-------------|--------------|
+| Response shape | `userSchema` | `User` |
+| Create request | `createUserSchema` | `CreateUserInput` |
+| Update request | `updateUserSchema` | `UpdateUserInput` |
+| Form values | `userFormSchema` | `UserFormValues` |
+| API params | `getUsersParamsSchema` | `GetUsersParams` |
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `UserCard.tsx` | `user-card.tsx` | Linux servers are case-sensitive |
+| `useUsers.ts` | `use-users.ts` | Inconsistent with Next.js file conventions |
+| `export default function UserCard` | `export function UserCard` | Named exports are more refactor-safe |
+| `type User = { id: string; name: string }` | `type User = z.infer<typeof userSchema>` | Single source of truth |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 4: Create `framework/standards/frontend/nextjs/components.md`**
+
+```markdown
+# Next.js Component Standards
+
+> **Scope:** frontend/nextjs/components
+> **Layer:** 2 (on keyword)
+> **Keywords:** component, shadcn, reusable, shared, ui, three-tier
+> **Load When:** creating or editing React components
+
+Three-tier component hierarchy. `components/ui/` is shadcn primitives (never edit). `components/` is composed shared (no business logic). `features/*/components/` is feature-scoped.
+
+## Core Rules
+
+- NEVER edit files in `components/ui/` — they are regenerated by shadcn CLI
+- NEVER import from `features/` inside `components/` — components know nothing about domain
+- ALWAYS compose shadcn primitives in `components/` instead of editing them
+- ALWAYS add `'use client'` only if the component uses hooks, events, or browser APIs
+- NEVER pass raw API data directly to a component — transform to props first
+
+## Three-Tier Hierarchy
+
+```
+Tier 1: components/ui/         ← shadcn/ui CLI output (DO NOT EDIT)
+           ↓ composed into
+Tier 2: components/            ← shared project components (no business logic)
+           ↓ used by
+Tier 3: features/*/components/ ← feature-scoped (knows about users, billing, etc.)
+```
+
+## Tier 1 — shadcn/ui Primitives
+
+```bash
+# Add shadcn components via CLI — never write them manually
+npx shadcn@latest add button card dialog form input table
+
+# Available at:
+src/components/ui/button.tsx
+src/components/ui/card.tsx
+src/components/ui/dialog.tsx
+```
+
+If you need to change a shadcn component's behavior, wrap it — do not edit the source file.
+
+## Tier 2 — Shared Composed Components
+
+```tsx
+// components/data-table.tsx — composes shadcn Table + TanStack Table
+'use client'; // TanStack Table requires client
+
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table';
+import { type ColumnDef, flexRender, getCoreRowModel, useReactTable } from '@tanstack/react-table';
+
+interface DataTableProps<TData> {
+  columns: ColumnDef<TData>[];
+  data: TData[];
+}
+
+export function DataTable<TData>({ columns, data }: DataTableProps<TData>) {
+  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+  return (
+    <Table>
+      <TableHeader>
+        {table.getHeaderGroups().map((headerGroup) => (
+          <TableRow key={headerGroup.id}>
+            {headerGroup.headers.map((header) => (
+              <TableHead key={header.id}>
+                {flexRender(header.column.columnDef.header, header.getContext())}
+              </TableHead>
+            ))}
+          </TableRow>
+        ))}
+      </TableHeader>
+      <TableBody>
+        {table.getRowModel().rows.map((row) => (
+          <TableRow key={row.id}>
+            {row.getVisibleCells().map((cell) => (
+              <TableCell key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </TableCell>
+            ))}
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+## Tier 3 — Feature Components
+
+```tsx
+// features/users/components/user-list.tsx
+// Uses DataTable (Tier 2) and UserCard (Tier 3)
+'use client';
+
+import { DataTable } from '@/components/data-table';
+import { useUsers } from '@/features/users/hooks/use-users';
+import { type ColumnDef } from '@tanstack/react-table';
+import type { User } from '@/features/users/types/user.types';
+
+const columns: ColumnDef<User>[] = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'email', header: 'Email' },
+];
+
+export function UserList() {
+  const { data: users = [], isLoading } = useUsers();
+  if (isLoading) return <div>Loading...</div>;
+  return <DataTable columns={columns} data={users} />;
+}
+```
+
+## Component Props Conventions
+
+```tsx
+// GOOD — explicit, typed props
+interface UserCardProps {
+  user: User;
+  onEdit?: (id: string) => void;
+  className?: string; // Always allow className for Tailwind override
+}
+
+export function UserCard({ user, onEdit, className }: UserCardProps) {}
+
+// BAD — spreading unknown props, no types
+export function UserCard({ ...props }) {}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| Edit `components/ui/button.tsx` | Wrap it in `components/action-button.tsx` | shadcn CLI overwrites it |
+| `import { useUsers } from '@/features/users'` inside `components/` | Move to a feature component | Breaks tier isolation |
+| `'use client'` on all components | Only on interactive ones | Unnecessary client JS |
+| Pass raw fetch response as prop | Type and validate with Zod first | Runtime type safety |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 5: Create `framework/standards/frontend/nextjs/data-fetching.md`**
+
+```markdown
+# Next.js Data Fetching Standard
+
+> **Scope:** frontend/nextjs/data-fetching
+> **Layer:** 2 (on keyword)
+> **Keywords:** data fetching, tanstack query, react query, server component, fetch, api
+> **Load When:** fetching data from .NET API
+
+Server Components for initial page load. TanStack Query for client mutations and interactive data. Never `useEffect` for fetching.
+
+## Core Rules
+
+- ALWAYS use Server Components for initial data that doesn't require interactivity
+- ALWAYS use TanStack Query (`useQuery`, `useMutation`) for client-side data needs
+- NEVER use `useEffect(() => { fetch(...) }, [])` — this is the old pattern
+- ALWAYS validate API responses with Zod before using them
+- ALWAYS use query key factories for consistent cache invalidation
+
+## TanStack Query Setup
+
+```tsx
+// lib/query-client.tsx
+'use client';
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { useState } from 'react';
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: 60 * 1000, retry: 1 },
+    },
+  }));
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}
+```
+
+## Query Key Factory Pattern
+
+```ts
+// features/users/hooks/query-keys.ts
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+  list: (filters: Record<string, unknown>) => [...userKeys.lists(), filters] as const,
+  details: () => [...userKeys.all, 'detail'] as const,
+  detail: (id: string) => [...userKeys.details(), id] as const,
+};
+```
+
+## useQuery Hook Pattern
+
+```ts
+// features/users/hooks/use-users.ts
+import { useQuery } from '@tanstack/react-query';
+import { userKeys } from './query-keys';
+import { userSchema } from '@/features/users/types/user.schemas';
+import { z } from 'zod';
+
+const usersResponseSchema = z.array(userSchema);
+
+export function useUsers() {
+  return useQuery({
+    queryKey: userKeys.lists(),
+    queryFn: async () => {
+      const res = await fetch('/api/users'); // proxy to .NET API
+      if (!res.ok) throw new Error('Failed to fetch users');
+      return usersResponseSchema.parse(await res.json()); // Zod validation
+    },
+  });
+}
+```
+
+## useMutation Hook Pattern
+
+```ts
+// features/users/hooks/use-create-user.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { userKeys } from './query-keys';
+import { type CreateUserInput } from '@/features/users/types/user.types';
+
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: CreateUserInput) => {
+      const res = await fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(input),
+      });
+      if (!res.ok) throw new Error('Failed to create user');
+      return res.json();
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
+    },
+  });
+}
+```
+
+## Server Component + TanStack Query Handoff
+
+```tsx
+// app/(dashboard)/users/page.tsx — Server Component: initial fetch
+async function getInitialUsers() {
+  const res = await fetch(`${process.env.API_URL}/api/users`, { next: { revalidate: 30 } });
+  return res.json();
+}
+
+export default async function UsersPage() {
+  const initialUsers = await getInitialUsers();
+  return <UserListClient initialData={initialUsers} />;
+}
+
+// features/users/components/user-list-client.tsx — Client Component: mutations
+'use client';
+import { useUsers } from '@/features/users/hooks/use-users';
+
+export function UserListClient({ initialData }: { initialData: User[] }) {
+  const { data: users = initialData } = useUsers(); // initialData hydrates cache
+  // ...mutations, filtering, etc.
+}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `useEffect(() => { fetch(...) }, [])` | `useQuery(...)` | Two renders, no cache, no SSR |
+| No Zod on API response | `schema.parse(await res.json())` | Type safety at runtime |
+| Hardcoded query keys: `['users']` | Key factory: `userKeys.lists()` | Consistent invalidation |
+| `queryClient.invalidateQueries(['users'])` | `queryClient.invalidateQueries({ queryKey: userKeys.lists() })` | Object syntax is required in v5 |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 6: Create `framework/standards/frontend/nextjs/forms.md`**
+
+```markdown
+# Next.js Forms Standard
+
+> **Scope:** frontend/nextjs/forms
+> **Layer:** 2 (on keyword)
+> **Keywords:** form, react-hook-form, zod, validation, input, submit
+> **Load When:** implementing any form in Next.js
+
+react-hook-form + Zod + shadcn Form components. Schema defines both validation rules and TypeScript types.
+
+## Core Rules
+
+- ALWAYS define the Zod schema first — derive the TypeScript type from it
+- ALWAYS use `zodResolver` to connect schema to react-hook-form
+- ALWAYS use shadcn `<Form>`, `<FormField>`, `<FormItem>`, `<FormMessage>` for consistent UI
+- NEVER use `useState` for form field values — react-hook-form handles this
+- ALWAYS use `useMutation` from TanStack Query for form submission
+
+## Complete Form Pattern
+
+```tsx
+// features/users/types/user.schemas.ts
+import { z } from 'zod';
+
+export const createUserSchema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  email: z.string().email('Invalid email address'),
+  role: z.enum(['admin', 'user'], { required_error: 'Role is required' }),
+});
+
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+```
+
+```tsx
+// features/users/components/create-user-form.tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
+import { Input } from '@/components/ui/input';
+import { Button } from '@/components/ui/button';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
+import { useCreateUser } from '@/features/users/hooks/use-create-user';
+import { createUserSchema, type CreateUserInput } from '@/features/users/types/user.schemas';
+
+export function CreateUserForm({ onSuccess }: { onSuccess?: () => void }) {
+  const form = useForm<CreateUserInput>({
+    resolver: zodResolver(createUserSchema),
+    defaultValues: { name: '', email: '', role: 'user' },
+  });
+
+  const { mutate: createUser, isPending } = useCreateUser();
+
+  function onSubmit(values: CreateUserInput) {
+    createUser(values, {
+      onSuccess: () => { form.reset(); onSuccess?.(); },
+      onError: (error) => { form.setError('root', { message: error.message }); },
+    });
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Name</FormLabel>
+              <FormControl><Input placeholder="John Doe" {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl><Input type="email" placeholder="john@example.com" {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="role"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Role</FormLabel>
+              <Select onValueChange={field.onChange} defaultValue={field.value}>
+                <FormControl>
+                  <SelectTrigger><SelectValue placeholder="Select role" /></SelectTrigger>
+                </FormControl>
+                <SelectContent>
+                  <SelectItem value="admin">Admin</SelectItem>
+                  <SelectItem value="user">User</SelectItem>
+                </SelectContent>
+              </Select>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        {form.formState.errors.root && (
+          <p className="text-sm text-destructive">{form.formState.errors.root.message}</p>
+        )}
+        <Button type="submit" disabled={isPending}>
+          {isPending ? 'Creating...' : 'Create User'}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+## Edit Form Pattern (pre-populated)
+
+```tsx
+// Edit forms use the same schema but with defaultValues from existing data
+const form = useForm<UpdateUserInput>({
+  resolver: zodResolver(updateUserSchema), // .partial() version
+  defaultValues: { name: user.name, email: user.email, role: user.role },
+});
+```
+
+## Schema Composition
+
+```ts
+// Reuse schemas — don't duplicate
+export const userSchema = z.object({ id: z.string(), name: z.string(), email: z.string() });
+export const createUserSchema = userSchema.omit({ id: true });
+export const updateUserSchema = createUserSchema.partial();
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `useState` for each field | `useForm` | Unnecessary re-renders on every keystroke |
+| Manual error display | `<FormMessage />` | Consistent UI, auto-connects to field errors |
+| Submit in `useEffect` | `form.handleSubmit(onSubmit)` | Handles validation before calling onSubmit |
+| `fetch` in submit handler | `useMutation` | Loading state, error handling, cache invalidation |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 7: Create `framework/standards/frontend/nextjs/state-management.md`**
+
+```markdown
+# Next.js State Management Standard
+
+> **Scope:** frontend/nextjs/state-management
+> **Layer:** 2 (on keyword)
+> **Keywords:** state, zustand, context, redux, client state, server state
+> **Load When:** deciding how to manage state in Next.js
+
+Server state (API data) lives in TanStack Query. UI state lives in React. No global state library unless genuinely needed.
+
+## Core Rules
+
+- ALWAYS use TanStack Query for anything that comes from the .NET API
+- ALWAYS use `useState` for local UI state (modal open, selected tab, form step)
+- NEVER install Zustand or Redux without first exhausting Server Components + TanStack Query
+- NEVER use React Context for server state — Context does not cache or deduplicate
+- ALWAYS derive state from server data rather than syncing it to local state
+
+## State Decision Tree
+
+```
+Is this data from the .NET API?
+  YES → TanStack Query (useQuery / useMutation)
+
+Is this local UI state (open/closed, selected, current step)?
+  YES → useState in the component that needs it
+
+Does multiple components need this UI state?
+  YES — is it parent-child? → prop drilling (2-3 levels is fine)
+  YES — is it truly global? → React Context (theme, auth user, locale)
+  YES — is it complex with many actions? → Consider Zustand (last resort)
+```
+
+## Server State (TanStack Query)
+
+```ts
+// GOOD — server state in TanStack Query
+const { data: users } = useUsers(); // cached, deduplicated, background-refetched
+
+// BAD — copying server state to useState
+const [users, setUsers] = useState([]);
+useEffect(() => { fetchUsers().then(setUsers); }, []);
+```
+
+## Local UI State (useState)
+
+```tsx
+// GOOD — local UI state in useState
+function UserList() {
+  const [isCreateDialogOpen, setIsCreateDialogOpen] = useState(false);
+  const [selectedUserId, setSelectedUserId] = useState<string | null>(null);
+  // ...
+}
+```
+
+## Shared UI State (React Context)
+
+Use Context only for truly global UI concerns:
+
+```tsx
+// lib/auth-context.tsx — OK for Context (session-level, read-only)
+const AuthContext = createContext<{ user: User | null }>({ user: null });
+
+// NOT OK for Context
+// - List of users (use TanStack Query)
+// - Form values (use react-hook-form)
+// - Modal state only used in one feature (use useState)
+```
+
+## When Zustand Is Justified
+
+Only add Zustand if ALL of these are true:
+1. State is needed in 5+ unrelated components
+2. State has complex update logic (not just toggle/set)
+3. Context causes measurable re-render performance issues
+4. State is not from the server
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `useEffect` + `useState` for API data | TanStack Query | Stale data, no cache, double-render |
+| Global store for user list | `useUsers()` | TanStack Query handles sync/cache |
+| Context for everything | useState + prop drilling first | Context causes all consumers to re-render |
+| Zustand by default | Start with useState | YAGNI — most state is local |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 8: Create `framework/standards/frontend/nextjs/testing.md`**
+
+```markdown
+# Next.js Testing Standard
+
+> **Scope:** frontend/nextjs/testing
+> **Layer:** 2 (on keyword)
+> **Keywords:** testing, jest, vitest, testing-library, msw, component test
+> **Load When:** writing tests for Next.js components or hooks
+
+Jest + React Testing Library for component tests. MSW for API mocking. Co-locate tests with the code they test.
+
+## Core Rules
+
+- ALWAYS co-locate test files: `user-card.test.tsx` next to `user-card.tsx`
+- ALWAYS use `@testing-library/user-event` for interactions — not `fireEvent`
+- ALWAYS mock the API layer with MSW — never mock `fetch` directly
+- NEVER test implementation details — test what the user sees
+- ALWAYS test the happy path + one error path per component
+
+## Test File Co-location
+
+```
+features/users/
+├── components/
+│   ├── user-card.tsx
+│   ├── user-card.test.tsx      ← co-located
+│   ├── user-list.tsx
+│   └── user-list.test.tsx
+├── hooks/
+│   ├── use-users.ts
+│   └── use-users.test.ts       ← co-located
+```
+
+## Component Test Pattern
+
+```tsx
+// features/users/components/user-card.test.tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { UserCard } from './user-card';
+
+const mockUser = { id: '1', name: 'João Silva', email: 'joao@example.com', role: 'user' };
+
+describe('UserCard', () => {
+  it('renders user name and email', () => {
+    render(<UserCard user={mockUser} />);
+    expect(screen.getByText('João Silva')).toBeInTheDocument();
+    expect(screen.getByText('joao@example.com')).toBeInTheDocument();
+  });
+
+  it('calls onEdit with user id when edit button is clicked', async () => {
+    const onEdit = vi.fn();
+    render(<UserCard user={mockUser} onEdit={onEdit} />);
+    await userEvent.click(screen.getByRole('button', { name: /edit/i }));
+    expect(onEdit).toHaveBeenCalledWith('1');
+  });
+});
+```
+
+## Hook Test with MSW
+
+```ts
+// features/users/hooks/use-users.test.ts
+import { renderHook, waitFor } from '@testing-library/react';
+import { QueryClientWrapper } from '@/test/helpers';
+import { http, HttpResponse } from 'msw';
+import { server } from '@/test/msw-server';
+import { useUsers } from './use-users';
+
+describe('useUsers', () => {
+  it('returns users from API', async () => {
+    server.use(
+      http.get('/api/users', () =>
+        HttpResponse.json([{ id: '1', name: 'João', email: 'j@ex.com' }])
+      )
+    );
+    const { result } = renderHook(() => useUsers(), { wrapper: QueryClientWrapper });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data).toHaveLength(1);
+  });
+
+  it('returns error state when API fails', async () => {
+    server.use(http.get('/api/users', () => new HttpResponse(null, { status: 500 })));
+    const { result } = renderHook(() => useUsers(), { wrapper: QueryClientWrapper });
+    await waitFor(() => expect(result.current.isError).toBe(true));
+  });
+});
+```
+
+## Test Helpers Setup
+
+```tsx
+// test/helpers.tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+export function QueryClientWrapper({ children }: { children: React.ReactNode }) {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `fireEvent.click(button)` | `await userEvent.click(button)` | userEvent simulates real browser events |
+| Mock `global.fetch` | Mock with MSW | MSW intercepts at network level, more realistic |
+| `expect(component).toMatchSnapshot()` | `expect(screen.getByText(...))` | Snapshots break on any change |
+| Test file in `__tests__/` folder | Co-locate with source | Easier to find, deleted with the component |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 9: Verify all 8 files exist**
+
+Run:
+```bash
+ls "R:/Polymorphism Tech/repos/morph-spec-framework/framework/standards/frontend/nextjs/"
+```
+Expected: 8 new files + the existing `nextjs-patterns.md` = 9 files total.
+
+**Step 10: Commit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add framework/standards/frontend/nextjs/ && git commit -m "feat(standards): add 8 Next.js standards files — app-router, components, data-fetching, forms, state-management, naming-conventions, project-structure, testing"
+```
+
+---
+
+### Task 2: Create nextjs-standards.md rule file
+
+**Files:**
+- Create: `framework/rules/nextjs-standards.md`
+- Modify: `framework/rules/frontend-standards.md` (add nextjs-standards reference)
+
+**Step 1: Create `framework/rules/nextjs-standards.md`**
+
+```markdown
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.ts"
+  - "!**/*.cs"
+  - "!**/*.csproj"
+---
+
+# Next.js Standards
+
+@.morph/framework/standards/frontend/nextjs/naming-conventions.md
+@.morph/framework/standards/frontend/nextjs/project-structure.md
+@.morph/framework/standards/frontend/nextjs/app-router.md
+@.morph/framework/standards/frontend/nextjs/components.md
+@.morph/framework/standards/frontend/nextjs/data-fetching.md
+@.morph/framework/standards/frontend/nextjs/forms.md
+@.morph/framework/standards/frontend/nextjs/state-management.md
+@.morph/framework/standards/frontend/nextjs/testing.md
+@.morph/framework/standards/frontend/nextjs/nextjs-patterns.md
+```
+
+**Step 2: Read `framework/rules/frontend-standards.md` to check current content**
+
+It currently imports `nextjs-patterns.md`. Since `nextjs-standards.md` is the dedicated rule for `.tsx`/`.ts` files, the `frontend-standards.md` can remove its nextjs reference to avoid duplication (it should remain focused on Blazor + shared CSS). Update it to only cover Blazor/CSS paths.
+
+Read the file first, then remove the nextjs-patterns.md line if present.
+
+**Step 3: Verify**
+
+```bash
+cat "R:/Polymorphism Tech/repos/morph-spec-framework/framework/rules/nextjs-standards.md"
+```
+
+**Step 4: Commit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add framework/rules/nextjs-standards.md framework/rules/frontend-standards.md && git commit -m "feat(rules): add nextjs-standards.md rule file scoped to tsx/ts files"
+```
+
+---
+
+### Task 3: Create next-component-validator (TDD)
+
+**Files:**
+- Create: `src/lib/validators/nextjs/next-component-validator.js`
+- Create: `src/lib/validators/nextjs/index.js`
+- Create: `test/validators/nextjs/next-component-validator.test.js`
+
+**Step 1: Write the failing tests first**
+
+Create `test/validators/nextjs/next-component-validator.test.js`:
+
+```js
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateNextComponent } from '../../../src/lib/validators/nextjs/next-component-validator.js';
+
+describe('validateNextComponent', () => {
+
+  describe('use client directive checks', () => {
+    test('warns when use client is present but no interactivity detected', () => {
+      const content = `'use client';\n\nexport function StaticCard() {\n  return <div>Hello</div>;\n}`;
+      const issues = validateNextComponent(content, 'components/static-card.tsx');
+      const warnings = issues.filter(i => i.type === 'warning' && i.message.includes('use client'));
+      assert.ok(warnings.length > 0, 'Should warn about unnecessary use client');
+    });
+
+    test('no warning when use client has useState', () => {
+      const content = `'use client';\nimport { useState } from 'react';\nexport function Counter() {\n  const [count, setCount] = useState(0);\n  return <button onClick={() => setCount(c => c+1)}>{count}</button>;\n}`;
+      const issues = validateNextComponent(content, 'components/counter.tsx');
+      const useClientWarnings = issues.filter(i => i.message.includes('use client'));
+      assert.equal(useClientWarnings.length, 0, 'useState justifies use client');
+    });
+
+    test('no warning when use client has useEffect', () => {
+      const content = `'use client';\nimport { useEffect } from 'react';\nexport function Tracker() {\n  useEffect(() => {}, []);\n  return <div/>;\n}`;
+      const issues = validateNextComponent(content, 'components/tracker.tsx');
+      const useClientWarnings = issues.filter(i => i.message.includes('use client'));
+      assert.equal(useClientWarnings.length, 0, 'useEffect justifies use client');
+    });
+
+    test('no warning when use client has onClick handler', () => {
+      const content = `'use client';\nexport function Btn() {\n  return <button onClick={() => alert('hi')}>Click</button>;\n}`;
+      const issues = validateNextComponent(content, 'components/btn.tsx');
+      const useClientWarnings = issues.filter(i => i.message.includes('use client'));
+      assert.equal(useClientWarnings.length, 0, 'onClick justifies use client');
+    });
+  });
+
+  describe('missing use client checks', () => {
+    test('errors when useState used without use client', () => {
+      const content = `import { useState } from 'react';\nexport function Counter() {\n  const [c, setC] = useState(0);\n  return <div>{c}</div>;\n}`;
+      const issues = validateNextComponent(content, 'components/counter.tsx');
+      const errors = issues.filter(i => i.type === 'error' && i.message.includes('use client'));
+      assert.ok(errors.length > 0, 'Should error when useState missing use client');
+    });
+
+    test('errors when useEffect used without use client', () => {
+      const content = `import { useEffect } from 'react';\nexport function Effect() {\n  useEffect(() => {}, []);\n  return <div/>;\n}`;
+      const issues = validateNextComponent(content, 'components/effect.tsx');
+      const errors = issues.filter(i => i.type === 'error' && i.message.includes('use client'));
+      assert.ok(errors.length > 0, 'Should error when useEffect missing use client');
+    });
+
+    test('no error for server component with no hooks', () => {
+      const content = `export default async function Page() {\n  return <div>Hello</div>;\n}`;
+      const issues = validateNextComponent(content, 'app/page.tsx');
+      assert.equal(issues.length, 0, 'Clean server component should have no issues');
+    });
+  });
+
+  describe('file naming checks', () => {
+    test('warns on PascalCase component file', () => {
+      const content = `export function UserCard() { return <div/>; }`;
+      const issues = validateNextComponent(content, 'components/UserCard.tsx');
+      const warnings = issues.filter(i => i.message.includes('kebab-case'));
+      assert.ok(warnings.length > 0, 'Should warn on PascalCase file name');
+    });
+
+    test('no warning on kebab-case file', () => {
+      const content = `export function UserCard() { return <div/>; }`;
+      const issues = validateNextComponent(content, 'components/user-card.tsx');
+      const namingWarnings = issues.filter(i => i.message.includes('kebab-case'));
+      assert.equal(namingWarnings.length, 0, 'kebab-case file name is correct');
+    });
+
+    test('no warning on Next.js special files', () => {
+      const content = `export default function Page() { return <div/>; }`;
+      ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx'].forEach(file => {
+        const issues = validateNextComponent(content, `app/${file}`);
+        const namingWarnings = issues.filter(i => i.message.includes('kebab-case'));
+        assert.equal(namingWarnings.length, 0, `${file} should not warn about kebab-case`);
+      });
+    });
+  });
+
+  describe('returns empty array for non-component files', () => {
+    test('no issues for .ts utility files without JSX', () => {
+      const content = `export function formatDate(date: Date) { return date.toISOString(); }`;
+      const issues = validateNextComponent(content, 'lib/utils.ts');
+      assert.equal(issues.length, 0);
+    });
+  });
+
+});
+```
+
+**Step 2: Run tests to confirm they fail**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node --test test/validators/nextjs/next-component-validator.test.js 2>&1 | head -20
+```
+
+Expected: FAIL with "Cannot find module" or similar.
+
+**Step 3: Create `src/lib/validators/nextjs/next-component-validator.js`**
+
+```js
+/**
+ * Next.js Component Validator
+ *
+ * Validates .tsx files for:
+ * 1. Unnecessary 'use client' directives (no interactivity)
+ * 2. Missing 'use client' when React hooks are used
+ * 3. File naming convention (kebab-case)
+ *
+ * @module next-component-validator
+ */
+
+// ============================================
+// CONSTANTS
+// ============================================
+
+/** Hooks/patterns that require 'use client' */
+const CLIENT_HOOKS = ['useState', 'useEffect', 'useRef', 'useReducer', 'useCallback', 'useMemo', 'useContext'];
+
+/** Patterns that indicate interactivity requiring 'use client' */
+const INTERACTIVITY_PATTERNS = [
+  /\bonClick\b/,
+  /\bonChange\b/,
+  /\bonSubmit\b/,
+  /\bonFocus\b/,
+  /\bonBlur\b/,
+  /\bonKeyDown\b/,
+  /\buseState\b/,
+  /\buseEffect\b/,
+  /\buseRef\b/,
+  /\buseReducer\b/,
+  /\buseCallback\b/,
+  /\buseMemo\b/,
+  /\buseContext\b/,
+];
+
+/** Next.js special files exempt from naming checks */
+const NEXTJS_SPECIAL_FILES = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx', 'route.ts', 'middleware.ts'];
+
+// ============================================
+// MAIN VALIDATION FUNCTION
+// ============================================
+
+/**
+ * @typedef {Object} ValidationIssue
+ * @property {'error' | 'warning' | 'info'} type
+ * @property {string} message
+ * @property {string} [suggestion]
+ * @property {string} file
+ * @property {number} [line]
+ */
+
+/**
+ * Validates a Next.js component file.
+ *
+ * @param {string} content - File content
+ * @param {string} filePath - Relative file path
+ * @returns {ValidationIssue[]}
+ */
+export function validateNextComponent(content, filePath) {
+  const issues = [];
+
+  // Only validate .tsx and .ts files
+  if (!filePath.endsWith('.tsx') && !filePath.endsWith('.ts')) {
+    return issues;
+  }
+
+  // Skip non-component utility files (no JSX)
+  const hasJsx = /<[A-Z][a-zA-Z]*|<[a-z]+[\s>]/.test(content);
+  const hasHooks = CLIENT_HOOKS.some(hook => content.includes(hook));
+
+  if (!hasJsx && !hasHooks) {
+    return issues;
+  }
+
+  const hasUseClient = /^['"]use client['"]/.test(content.trimStart());
+
+  // Check 1: use client present but no interactivity
+  if (hasUseClient) {
+    const hasInteractivity = INTERACTIVITY_PATTERNS.some(pattern => pattern.test(content));
+    if (!hasInteractivity) {
+      issues.push({
+        type: 'warning',
+        message: "'use client' directive present but no interactivity detected (no hooks, no event handlers)",
+        suggestion: "Remove 'use client' to make this a Server Component, or add interactive behavior",
+        file: filePath,
+      });
+    }
+  }
+
+  // Check 2: hooks used without use client
+  if (!hasUseClient) {
+    const usedHooks = CLIENT_HOOKS.filter(hook => new RegExp(`\\b${hook}\\b`).test(content));
+    if (usedHooks.length > 0) {
+      issues.push({
+        type: 'error',
+        message: `React hook(s) used (${usedHooks.join(', ')}) without 'use client' directive`,
+        suggestion: "Add 'use client' as the first line of the file",
+        file: filePath,
+        line: 1,
+      });
+    }
+  }
+
+  // Check 3: file naming convention (kebab-case)
+  const fileName = filePath.split('/').pop() ?? '';
+  const isSpecialFile = NEXTJS_SPECIAL_FILES.includes(fileName);
+
+  if (!isSpecialFile && fileName.endsWith('.tsx')) {
+    const baseName = fileName.replace('.tsx', '');
+    const hasUpperCase = /[A-Z]/.test(baseName);
+    if (hasUpperCase) {
+      issues.push({
+        type: 'warning',
+        message: `Component file '${fileName}' should use kebab-case naming`,
+        suggestion: `Rename to '${toKebabCase(baseName)}.tsx'`,
+        file: filePath,
+      });
+    }
+  }
+
+  return issues;
+}
+
+// ============================================
+// HELPERS
+// ============================================
+
+function toKebabCase(str) {
+  return str
+    .replace(/([A-Z])/g, '-$1')
+    .toLowerCase()
+    .replace(/^-/, '');
+}
+```
+
+**Step 4: Create `src/lib/validators/nextjs/index.js`**
+
+```js
+export { validateNextComponent } from './next-component-validator.js';
+```
+
+**Step 5: Run tests — must all pass**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node --test test/validators/nextjs/next-component-validator.test.js 2>&1
+```
+
+Expected: All tests pass, 0 failures.
+
+**Step 6: Run full test suite**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && npm test 2>&1 | tail -10
+```
+
+Expected: Same pass count + new tests passing, 0 failures.
+
+**Step 7: Commit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add src/lib/validators/nextjs/ test/validators/nextjs/ && git commit -m "feat(validators): add next-component-validator — use client, hooks, kebab-case checks"
+```
+
+---
+
+### Task 4: Create 6 Next.js templates
+
+**Files:**
+- Create: `framework/templates/frontend/nextjs/page.tsx.hbs`
+- Create: `framework/templates/frontend/nextjs/client-component.tsx.hbs`
+- Create: `framework/templates/frontend/nextjs/feature-form.tsx.hbs`
+- Create: `framework/templates/frontend/nextjs/env.mjs.hbs`
+- Create: `framework/templates/frontend/nextjs/tsconfig.json.hbs`
+- Create: `framework/templates/frontend/nextjs/Dockerfile.nextjs.hbs`
+
+**Step 1: Create `framework/templates/frontend/nextjs/page.tsx.hbs`**
+
+```handlebars
+// app/(dashboard)/{{kebabCase featureName}}/page.tsx
+// Server Component — fetches initial data, renders feature component
+import { {{pascalCase featureName}}List } from '@/features/{{kebabCase featureName}}';
+
+async function get{{pascalCase featureName}}List() {
+  const res = await fetch(`${process.env.API_URL}/api/{{kebabCase featureName}}`, {
+    next: { revalidate: 30 },
+    headers: { 'Content-Type': 'application/json' },
+  });
+  if (!res.ok) throw new Error('Failed to fetch {{featureName}}');
+  return res.json();
+}
+
+export default async function {{pascalCase featureName}}Page() {
+  const data = await get{{pascalCase featureName}}List();
+  return (
+    <div className="container py-6">
+      <h1 className="text-2xl font-bold mb-6">{{pascalCase featureName}}</h1>
+      <{{pascalCase featureName}}List initialData={data} />
+    </div>
+  );
+}
+```
+
+**Step 2: Create `framework/templates/frontend/nextjs/client-component.tsx.hbs`**
+
+```handlebars
+// features/{{kebabCase featureName}}/components/{{kebabCase featureName}}-list.tsx
+'use client';
+
+import { use{{pascalCase featureName}}s } from '@/features/{{kebabCase featureName}}/hooks/use-{{kebabCase featureName}}s';
+import { DataTable } from '@/components/data-table';
+import type { {{pascalCase featureName}} } from '@/features/{{kebabCase featureName}}/types/{{kebabCase featureName}}.types';
+import type { ColumnDef } from '@tanstack/react-table';
+
+const columns: ColumnDef<{{pascalCase featureName}}>[] = [
+  { accessorKey: 'id', header: 'ID' },
+  { accessorKey: 'name', header: 'Name' },
+];
+
+interface {{pascalCase featureName}}ListProps {
+  initialData?: {{pascalCase featureName}}[];
+}
+
+export function {{pascalCase featureName}}List({ initialData }: {{pascalCase featureName}}ListProps) {
+  const { data = initialData ?? [], isLoading } = use{{pascalCase featureName}}s();
+
+  if (isLoading) {
+    return <div className="flex items-center justify-center h-32">Loading...</div>;
+  }
+
+  return <DataTable columns={columns} data={data} />;
+}
+```
+
+**Step 3: Create `framework/templates/frontend/nextjs/feature-form.tsx.hbs`**
+
+```handlebars
+// features/{{kebabCase featureName}}/components/create-{{kebabCase featureName}}-form.tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
+import { Input } from '@/components/ui/input';
+import { Button } from '@/components/ui/button';
+import { useCreate{{pascalCase featureName}} } from '@/features/{{kebabCase featureName}}/hooks/use-create-{{kebabCase featureName}}';
+import { create{{pascalCase featureName}}Schema, type Create{{pascalCase featureName}}Input } from '@/features/{{kebabCase featureName}}/types/{{kebabCase featureName}}.schemas';
+
+interface Create{{pascalCase featureName}}FormProps {
+  onSuccess?: () => void;
+}
+
+export function Create{{pascalCase featureName}}Form({ onSuccess }: Create{{pascalCase featureName}}FormProps) {
+  const form = useForm<Create{{pascalCase featureName}}Input>({
+    resolver: zodResolver(create{{pascalCase featureName}}Schema),
+    defaultValues: { name: '' },
+  });
+
+  const { mutate: create{{pascalCase featureName}}, isPending } = useCreate{{pascalCase featureName}}();
+
+  function onSubmit(values: Create{{pascalCase featureName}}Input) {
+    create{{pascalCase featureName}}(values, {
+      onSuccess: () => { form.reset(); onSuccess?.(); },
+      onError: (error) => { form.setError('root', { message: error.message }); },
+    });
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Name</FormLabel>
+              <FormControl>
+                <Input placeholder="Enter name" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        {form.formState.errors.root && (
+          <p className="text-sm text-destructive">{form.formState.errors.root.message}</p>
+        )}
+        <Button type="submit" disabled={isPending}>
+          {isPending ? 'Creating...' : 'Create {{pascalCase featureName}}'}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+**Step 4: Create `framework/templates/frontend/nextjs/env.mjs.hbs`**
+
+```handlebars
+// env.mjs — Zod-validated environment variables
+// Crashes at startup if required vars are missing — no silent undefined
+import { z } from 'zod';
+
+const serverSchema = z.object({
+  API_URL: z.string().url('API_URL must be a valid URL'),
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+});
+
+const clientSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url().optional(),
+});
+
+// Validate server-side env (only available on server)
+const serverEnv = serverSchema.safeParse(process.env);
+if (!serverEnv.success) {
+  console.error('❌ Invalid server environment variables:');
+  console.error(serverEnv.error.flatten().fieldErrors);
+  throw new Error('Invalid environment variables');
+}
+
+// Validate client-side env
+const clientEnv = clientSchema.safeParse({
+  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+});
+if (!clientEnv.success) {
+  console.error('❌ Invalid client environment variables:');
+  console.error(clientEnv.error.flatten().fieldErrors);
+  throw new Error('Invalid client environment variables');
+}
+
+export const env = { ...serverEnv.data, ...clientEnv.data };
+```
+
+**Step 5: Create `framework/templates/frontend/nextjs/tsconfig.json.hbs`**
+
+```handlebars
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+```
+
+**Step 6: Create `framework/templates/frontend/nextjs/Dockerfile.nextjs.hbs`**
+
+```handlebars
+# Multi-stage Next.js production build for EasyPanel
+# Stage 1: Dependencies
+FROM node:20-alpine AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm ci --only=production && npm cache clean --force
+
+# Stage 2: Build
+FROM node:20-alpine AS builder
+WORKDIR /app
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# Build args for NEXT_PUBLIC_ variables (must be available at build time)
+ARG NEXT_PUBLIC_APP_URL
+ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
+
+RUN npm run build
+
+# Stage 3: Production runner
+FROM node:20-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]
+```
+
+**Step 7: Verify all 6 template files exist**
+
+```bash
+ls "R:/Polymorphism Tech/repos/morph-spec-framework/framework/templates/frontend/nextjs/"
+```
+
+Expected: 6 files.
+
+**Step 8: Commit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add framework/templates/frontend/nextjs/ && git commit -m "feat(templates): add 6 Next.js templates — page, client-component, feature-form, env.mjs, tsconfig, Dockerfile"
+```
+
+---
+
+### Task 5: Update nextjs-expert agent
+
+**Files:**
+- Modify: `framework/agents/frontend/nextjs-expert.md`
+- Modify: `framework/agents.json`
+
+**Step 1: Read the current `framework/agents/frontend/nextjs-expert.md`**
+
+Read the file fully to understand current content.
+
+**Step 2: Rewrite `framework/agents/frontend/nextjs-expert.md`**
+
+Replace the full content with:
+
+```markdown
+---
+name: nextjs-expert
+description: Next.js specialist for App Router, shadcn/ui, TanStack Query, react-hook-form/Zod, and EasyPanel deployment. Use when building Next.js pages or components, implementing forms, setting up data fetching from a .NET API, or configuring TypeScript/Docker for Next.js.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Next.js Expert
+
+Specialist for the locked stack: **Next.js App Router + shadcn/ui + TanStack Query + react-hook-form/Zod + EasyPanel/Docker**.
+
+## Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | Next.js App Router (TypeScript strict) |
+| UI Components | shadcn/ui — `npx shadcn@latest add` |
+| Styling | Tailwind CSS |
+| Server state | TanStack Query v5 |
+| Forms | react-hook-form + Zod + zodResolver |
+| Deployment | Docker multi-stage → EasyPanel (VPS) |
+
+## Critical Standards (Read FIRST)
+
+| Standard | What |
+|----------|------|
+| `frontend/nextjs/naming-conventions.md` | **kebab-case files, PascalCase exports, use- hooks** |
+| `frontend/nextjs/project-structure.md` | **Feature-based folders, component tiers** |
+| `frontend/nextjs/app-router.md` | **Server vs Client components decision tree** |
+| `frontend/nextjs/components.md` | **Three-tier hierarchy, never edit components/ui/** |
+| `frontend/nextjs/data-fetching.md` | **TanStack Query patterns, query key factories** |
+| `frontend/nextjs/forms.md` | **react-hook-form + Zod + shadcn Form** |
+| `frontend/nextjs/state-management.md` | **No Zustand by default** |
+| `frontend/nextjs/testing.md` | **Jest + Testing Library + MSW** |
+
+## Quick Checklist
+
+- [ ] File names are kebab-case (`user-card.tsx` not `UserCard.tsx`)
+- [ ] `'use client'` only on components with hooks or event handlers
+- [ ] No `useEffect` for data fetching — use Server Components or TanStack Query
+- [ ] Zod schema defined before TypeScript type (`type X = z.infer<typeof xSchema>`)
+- [ ] Query keys use factory pattern (`userKeys.lists()` not `['users']`)
+- [ ] Forms use `zodResolver` + shadcn `<Form>` + `<FormMessage>`
+- [ ] `components/ui/` files never edited directly
+- [ ] New features go in `features/{name}/components|hooks|types/`
+
+## Naming Conventions (Non-Negotiable)
+
+```
+Component file:   user-card.tsx           → export function UserCard()
+Hook file:        use-create-user.ts      → export function useCreateUser()
+Schema file:      user.schemas.ts         → export const createUserSchema = z.object(...)
+Type file:        user.types.ts           → export type User = z.infer<typeof userSchema>
+Feature folder:   features/user-mgmt/
+```
+
+## Component Tier Rules
+
+```
+components/ui/        ← shadcn primitives. NEVER edit.
+components/           ← Composed shared components. No API calls. No feature imports.
+features/*/components ← Feature-scoped. May use components/ but not other features/.
+```
+
+## Data Fetching Patterns
+
+```tsx
+// Server Component (initial load)
+export default async function Page() {
+  const data = await fetch(`${process.env.API_URL}/api/users`).then(r => r.json());
+  return <UserList initialData={data} />;
+}
+
+// Client Component (mutations/interactive)
+'use client';
+const { data } = useUsers();           // TanStack Query
+const { mutate } = useCreateUser();    // useMutation
+```
+
+## Form Pattern
+
+```tsx
+// Schema first, type derived
+const schema = z.object({ name: z.string().min(2) });
+type Input = z.infer<typeof schema>;
+
+// Form wired to schema
+const form = useForm<Input>({ resolver: zodResolver(schema) });
+```
+
+## EasyPanel Deployment
+
+- Use `framework/templates/frontend/nextjs/Dockerfile.nextjs.hbs` as base
+- Requires `output: 'standalone'` in `next.config.js`
+- `NEXT_PUBLIC_*` vars must be available at **build time** (Docker build args)
+- Server-only vars (API_URL, secrets) go in EasyPanel environment at **runtime**
+
+## Project Structure
+
+```
+src/
+├── app/                    # Routes only
+├── features/{name}/
+│   ├── components/         # Feature UI
+│   ├── hooks/              # TanStack Query hooks
+│   └── types/              # Zod schemas + inferred types
+├── components/
+│   ├── ui/                 # shadcn — do not edit
+│   └── {shared}.tsx        # Composed shared components
+├── hooks/                  # Utility hooks (no API calls)
+├── lib/
+│   ├── api-client.ts
+│   └── query-client.tsx
+└── env.mjs                 # Zod env validation
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 3: Update `framework/agents.json` — nextjs-expert standards array**
+
+Find the `nextjs-expert` entry and update its `standards` array to include all 8 new standards files:
+
+```json
+"standards": [
+  "core/coding.md",
+  "core/architecture.md",
+  "frontend/nextjs/naming-conventions.md",
+  "frontend/nextjs/project-structure.md",
+  "frontend/nextjs/app-router.md",
+  "frontend/nextjs/components.md",
+  "frontend/nextjs/data-fetching.md",
+  "frontend/nextjs/forms.md",
+  "frontend/nextjs/state-management.md",
+  "frontend/nextjs/testing.md",
+  "frontend/nextjs/nextjs-patterns.md"
+]
+```
+
+Also update `nextjs-expert.keywords` to include the new stack terms:
+```json
+"keywords": ["next.js", "nextjs", "react", "tsx", "shadcn", "tailwind", "tanstack", "react-query", "zod", "react-hook-form", "app router", "server component", "client component"]
+```
+
+**Step 4: Validate JSON**
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync('framework/agents.json','utf8')); console.log('OK')"
+```
+
+**Step 5: Commit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add framework/agents/frontend/nextjs-expert.md framework/agents.json && git commit -m "feat(agents): enhance nextjs-expert with full stack standards, naming rules, EasyPanel deployment"
+```
+
+---
+
+### Task 6: Regenerate STANDARDS.json and final verification
+
+**Files:**
+- Modify: `framework/standards/STANDARDS.json` (regenerated)
+
+**Step 1: Run the standards registry generator**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node scripts/generate-standards-registry.js
+```
+
+**Step 2: Verify new entries appear in STANDARDS.json**
+
+```bash
+node -e "
+const s = JSON.parse(require('fs').readFileSync('framework/standards/STANDARDS.json','utf8'));
+const nextjs = s.standards.filter(x => x.path.includes('nextjs'));
+console.log('Next.js standards in registry:', nextjs.length, '(expected 9)');
+nextjs.forEach(x => console.log(' -', x.id));
+"
+```
+
+Expected: 9 Next.js standards entries (8 new + 1 existing nextjs-patterns).
+
+**Step 3: Run full test suite**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && npm test 2>&1 | tail -10
+```
+
+Expected: All previously passing tests still pass, new validator tests pass, 0 failures.
+
+**Step 4: Commit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add framework/standards/STANDARDS.json && git commit -m "feat(standards): regenerate STANDARDS.json — 9 Next.js entries added (82 total)"
+```
+
+**Step 5: Final audit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node -e "
+const s = JSON.parse(require('fs').readFileSync('framework/standards/STANDARDS.json','utf8'));
+console.log('Total standards:', s.standards.length);
+const byCategory = {};
+s.standards.forEach(x => { byCategory[x.category] = (byCategory[x.category] || 0) + 1; });
+Object.entries(byCategory).sort((a,b) => b[1]-a[1]).forEach(([k,v]) => console.log(' ', k + ':', v));
+"
+```