@polymorphism-tech/morph-spec 4.8.1 → 4.8.4

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

@@ -1,1848 +0,0 @@
-# Next.js Standards Package Implementation Plan
-
-**Status:** COMPLETE
-
-> **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));
-"
-```