Merge branch 'feature/redo-undo' of https://git.hanasys.jp/qcast3/qcast-front into feature/roofline-edit2

[작업내용] :
- e17af8f4 가 색칠된 외벽선을 selectable:false 로 잠가, 지붕형상 저장 후 일반 상태에서 외벽선 클릭 선택이 막히던 회귀 수정
- useRoofShapeSetting(자동) / useRoofShapePassivitySetting(수동) 저장 시 외벽선 selectable:true 로 복원
- 드래그는 lockMovement(useCanvas 전역), 보조선 클릭 가로채기는 z-order(18abbeb9)로 이미 별도 차단되어 부작용 없음

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.agents/skills/next-best-practices/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: next-best-practices
+description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
+user-invocable: false
+---
+
+# Next.js Best Practices
+
+Apply these rules when writing or reviewing Next.js code.
+
+## File Conventions
+
+See [file-conventions.md](./file-conventions.md) for:
+- Project structure and special files
+- Route segments (dynamic, catch-all, groups)
+- Parallel and intercepting routes
+- Middleware rename in v16 (middleware → proxy)
+
+## RSC Boundaries
+
+Detect invalid React Server Component patterns.
+
+See [rsc-boundaries.md](./rsc-boundaries.md) for:
+- Async client component detection (invalid)
+- Non-serializable props detection
+- Server Action exceptions
+
+## Async Patterns
+
+Next.js 15+ async API changes.
+
+See [async-patterns.md](./async-patterns.md) for:
+- Async `params` and `searchParams`
+- Async `cookies()` and `headers()`
+- Migration codemod
+
+## Runtime Selection
+
+See [runtime-selection.md](./runtime-selection.md) for:
+- Default to Node.js runtime
+- When Edge runtime is appropriate
+
+## Directives
+
+See [directives.md](./directives.md) for:
+- `'use client'`, `'use server'` (React)
+- `'use cache'` (Next.js)
+
+## Functions
+
+See [functions.md](./functions.md) for:
+- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
+- Server functions: `cookies`, `headers`, `draftMode`, `after`
+- Generate functions: `generateStaticParams`, `generateMetadata`
+
+## Error Handling
+
+See [error-handling.md](./error-handling.md) for:
+- `error.tsx`, `global-error.tsx`, `not-found.tsx`
+- `redirect`, `permanentRedirect`, `notFound`
+- `forbidden`, `unauthorized` (auth errors)
+- `unstable_rethrow` for catch blocks
+
+## Data Patterns
+
+See [data-patterns.md](./data-patterns.md) for:
+- Server Components vs Server Actions vs Route Handlers
+- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
+- Client component data fetching
+
+## Route Handlers
+
+See [route-handlers.md](./route-handlers.md) for:
+- `route.ts` basics
+- GET handler conflicts with `page.tsx`
+- Environment behavior (no React DOM)
+- When to use vs Server Actions
+
+## Metadata & OG Images
+
+See [metadata.md](./metadata.md) for:
+- Static and dynamic metadata
+- `generateMetadata` function
+- OG image generation with `next/og`
+- File-based metadata conventions
+
+## Image Optimization
+
+See [image.md](./image.md) for:
+- Always use `next/image` over `<img>`
+- Remote images configuration
+- Responsive `sizes` attribute
+- Blur placeholders
+- Priority loading for LCP
+
+## Font Optimization
+
+See [font.md](./font.md) for:
+- `next/font` setup
+- Google Fonts, local fonts
+- Tailwind CSS integration
+- Preloading subsets
+
+## Bundling
+
+See [bundling.md](./bundling.md) for:
+- Server-incompatible packages
+- CSS imports (not link tags)
+- Polyfills (already included)
+- ESM/CommonJS issues
+- Bundle analysis
+
+## Scripts
+
+See [scripts.md](./scripts.md) for:
+- `next/script` vs native script tags
+- Inline scripts need `id`
+- Loading strategies
+- Google Analytics with `@next/third-parties`
+
+## Hydration Errors
+
+See [hydration-error.md](./hydration-error.md) for:
+- Common causes (browser APIs, dates, invalid HTML)
+- Debugging with error overlay
+- Fixes for each cause
+
+## Suspense Boundaries
+
+See [suspense-boundaries.md](./suspense-boundaries.md) for:
+- CSR bailout with `useSearchParams` and `usePathname`
+- Which hooks require Suspense boundaries
+
+## Parallel & Intercepting Routes
+
+See [parallel-routes.md](./parallel-routes.md) for:
+- Modal patterns with `@slot` and `(.)` interceptors
+- `default.tsx` for fallbacks
+- Closing modals correctly with `router.back()`
+
+## Self-Hosting
+
+See [self-hosting.md](./self-hosting.md) for:
+- `output: 'standalone'` for Docker
+- Cache handlers for multi-instance ISR
+- What works vs needs extra setup
+
+## Debug Tricks
+
+See [debug-tricks.md](./debug-tricks.md) for:
+- MCP endpoint for AI-assisted debugging
+- Rebuild specific routes with `--debug-build-paths`
+

.agents/skills/next-best-practices/async-patterns.md

@@ -0,0 +1,87 @@
+# Async Patterns
+
+In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
+
+## Async Params and SearchParams
+
+Always type them as `Promise<...>` and await them.
+
+### Pages and Layouts
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export default async function Page({ params }: Props) {
+  const { slug } = await params
+}
+```
+
+### Route Handlers
+
+```tsx
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params
+}
+```
+
+### SearchParams
+
+```tsx
+type Props = {
+  params: Promise<{ slug: string }>
+  searchParams: Promise<{ query?: string }>
+}
+
+export default async function Page({ params, searchParams }: Props) {
+  const { slug } = await params
+  const { query } = await searchParams
+}
+```
+
+### Synchronous Components
+
+Use `React.use()` for non-async components:
+
+```tsx
+import { use } from 'react'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export default function Page({ params }: Props) {
+  const { slug } = use(params)
+}
+```
+
+### generateMetadata
+
+```tsx
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params
+  return { title: slug }
+}
+```
+
+## Async Cookies and Headers
+
+```tsx
+import { cookies, headers } from 'next/headers'
+
+export default async function Page() {
+  const cookieStore = await cookies()
+  const headersList = await headers()
+
+  const theme = cookieStore.get('theme')
+  const userAgent = headersList.get('user-agent')
+}
+```
+
+## Migration Codemod
+
+```bash
+npx @next/codemod@latest next-async-request-api .
+```

.agents/skills/next-best-practices/bundling.md

@@ -0,0 +1,180 @@
+# Bundling
+
+Fix common bundling issues with third-party packages.
+
+## Server-Incompatible Packages
+
+Some packages use browser APIs (`window`, `document`, `localStorage`) and fail in Server Components.
+
+### Error Signs
+
+```
+ReferenceError: window is not defined
+ReferenceError: document is not defined
+ReferenceError: localStorage is not defined
+Module not found: Can't resolve 'fs'
+```
+
+### Solution 1: Mark as Client-Only
+
+If the package is only needed on client:
+
+```tsx
+// Bad: Fails - package uses window
+import SomeChart from 'some-chart-library'
+
+export default function Page() {
+  return <SomeChart />
+}
+
+// Good: Use dynamic import with ssr: false
+import dynamic from 'next/dynamic'
+
+const SomeChart = dynamic(() => import('some-chart-library'), {
+  ssr: false,
+})
+
+export default function Page() {
+  return <SomeChart />
+}
+```
+
+### Solution 2: Externalize from Server Bundle
+
+For packages that should run on server but have bundling issues:
+
+```js
+// next.config.js
+module.exports = {
+  serverExternalPackages: ['problematic-package'],
+}
+```
+
+Use this for:
+- Packages with native bindings (sharp, bcrypt)
+- Packages that don't bundle well (some ORMs)
+- Packages with circular dependencies
+
+### Solution 3: Client Component Wrapper
+
+Wrap the entire usage in a client component:
+
+```tsx
+// components/ChartWrapper.tsx
+'use client'
+
+import { Chart } from 'chart-library'
+
+export function ChartWrapper(props) {
+  return <Chart {...props} />
+}
+
+// app/page.tsx (server component)
+import { ChartWrapper } from '@/components/ChartWrapper'
+
+export default function Page() {
+  return <ChartWrapper data={data} />
+}
+```
+
+## CSS Imports
+
+Import CSS files instead of using `<link>` tags. Next.js handles bundling and optimization.
+
+```tsx
+// Bad: Manual link tag
+<link rel="stylesheet" href="/styles.css" />
+
+// Good: Import CSS
+import './styles.css'
+
+// Good: CSS Modules
+import styles from './Button.module.css'
+```
+
+## Polyfills
+
+Next.js includes common polyfills automatically. Don't load redundant ones from polyfill.io or similar CDNs.
+
+Already included: `Array.from`, `Object.assign`, `Promise`, `fetch`, `Map`, `Set`, `Symbol`, `URLSearchParams`, and 50+ others.
+
+```tsx
+// Bad: Redundant polyfills
+<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Array.from" />
+
+// Good: Next.js includes these automatically
+```
+
+## ESM/CommonJS Issues
+
+### Error Signs
+
+```
+SyntaxError: Cannot use import statement outside a module
+Error: require() of ES Module
+Module not found: ESM packages need to be imported
+```
+
+### Solution: Transpile Package
+
+```js
+// next.config.js
+module.exports = {
+  transpilePackages: ['some-esm-package', 'another-package'],
+}
+```
+
+## Common Problematic Packages
+
+| Package | Issue | Solution |
+|---------|-------|----------|
+| `sharp` | Native bindings | `serverExternalPackages: ['sharp']` |
+| `bcrypt` | Native bindings | `serverExternalPackages: ['bcrypt']` or use `bcryptjs` |
+| `canvas` | Native bindings | `serverExternalPackages: ['canvas']` |
+| `recharts` | Uses window | `dynamic(() => import('recharts'), { ssr: false })` |
+| `react-quill` | Uses document | `dynamic(() => import('react-quill'), { ssr: false })` |
+| `mapbox-gl` | Uses window | `dynamic(() => import('mapbox-gl'), { ssr: false })` |
+| `monaco-editor` | Uses window | `dynamic(() => import('@monaco-editor/react'), { ssr: false })` |
+| `lottie-web` | Uses document | `dynamic(() => import('lottie-react'), { ssr: false })` |
+
+## Bundle Analysis
+
+Analyze bundle size with the built-in analyzer (Next.js 16.1+):
+
+```bash
+next experimental-analyze
+```
+
+This opens an interactive UI to:
+- Filter by route, environment (client/server), and type
+- Inspect module sizes and import chains
+- View treemap visualization
+
+Save output for comparison:
+
+```bash
+next experimental-analyze --output
+# Output saved to .next/diagnostics/analyze
+```
+
+Reference: https://nextjs.org/docs/app/guides/package-bundling
+
+## Migrating from Webpack to Turbopack
+
+Turbopack is the default bundler in Next.js 15+. If you have custom webpack config, migrate to Turbopack-compatible alternatives:
+
+```js
+// next.config.js
+module.exports = {
+  // Good: Works with Turbopack
+  serverExternalPackages: ['package'],
+  transpilePackages: ['package'],
+
+  // Bad: Webpack-only - migrate away from this
+  webpack: (config) => {
+    // custom webpack config
+  },
+}
+```
+
+Reference: https://nextjs.org/docs/app/building-your-application/upgrading/from-webpack-to-turbopack

.agents/skills/next-best-practices/data-patterns.md

@@ -0,0 +1,297 @@
+# Data Patterns
+
+Choose the right data fetching pattern for each use case.
+
+## Decision Tree
+
+```
+Need to fetch data?
+├── From a Server Component?
+│   └── Use: Fetch directly (no API needed)
+│
+├── From a Client Component?
+│   ├── Is it a mutation (POST/PUT/DELETE)?
+│   │   └── Use: Server Action
+│   └── Is it a read (GET)?
+│       └── Use: Route Handler OR pass from Server Component
+│
+├── Need external API access (webhooks, third parties)?
+│   └── Use: Route Handler
+│
+└── Need REST API for mobile app / external clients?
+    └── Use: Route Handler
+```
+
+## Pattern 1: Server Components (Preferred for Reads)
+
+Fetch data directly in Server Components - no API layer needed.
+
+```tsx
+// app/users/page.tsx
+async function UsersPage() {
+  // Direct database access - no API round-trip
+  const users = await db.user.findMany();
+
+  // Or fetch from external API
+  const posts = await fetch('https://api.example.com/posts').then(r => r.json());
+
+  return (
+    <ul>
+      {users.map(user => <li key={user.id}>{user.name}</li>)}
+    </ul>
+  );
+}
+```
+
+**Benefits**:
+- No API to maintain
+- No client-server waterfall
+- Secrets stay on server
+- Direct database access
+
+## Pattern 2: Server Actions (Preferred for Mutations)
+
+Server Actions are the recommended way to handle mutations.
+
+```tsx
+// app/actions.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string;
+
+  await db.post.create({ data: { title } });
+
+  revalidatePath('/posts');
+}
+
+export async function deletePost(id: string) {
+  await db.post.delete({ where: { id } });
+
+  revalidateTag('posts');
+}
+```
+
+```tsx
+// app/posts/new/page.tsx
+import { createPost } from '@/app/actions';
+
+export default function NewPost() {
+  return (
+    <form action={createPost}>
+      <input name="title" required />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+**Benefits**:
+- End-to-end type safety
+- Progressive enhancement (works without JS)
+- Automatic request handling
+- Integrated with React transitions
+
+**Constraints**:
+- POST only (no GET caching semantics)
+- Internal use only (no external access)
+- Cannot return non-serializable data
+
+## Pattern 3: Route Handlers (APIs)
+
+Use Route Handlers when you need a REST API.
+
+```tsx
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+// GET is cacheable
+export async function GET(request: NextRequest) {
+  const posts = await db.post.findMany();
+  return NextResponse.json(posts);
+}
+
+// POST for mutations
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const post = await db.post.create({ data: body });
+  return NextResponse.json(post, { status: 201 });
+}
+```
+
+**When to use**:
+- External API access (mobile apps, third parties)
+- Webhooks from external services
+- GET endpoints that need HTTP caching
+- OpenAPI/Swagger documentation needed
+
+**When NOT to use**:
+- Internal data fetching (use Server Components)
+- Mutations from your UI (use Server Actions)
+
+## Avoiding Data Waterfalls
+
+### Problem: Sequential Fetches
+
+```tsx
+// Bad: Sequential waterfalls
+async function Dashboard() {
+  const user = await getUser();        // Wait...
+  const posts = await getPosts();      // Then wait...
+  const comments = await getComments(); // Then wait...
+
+  return <div>...</div>;
+}
+```
+
+### Solution 1: Parallel Fetching with Promise.all
+
+```tsx
+// Good: Parallel fetching
+async function Dashboard() {
+  const [user, posts, comments] = await Promise.all([
+    getUser(),
+    getPosts(),
+    getComments(),
+  ]);
+
+  return <div>...</div>;
+}
+```
+
+### Solution 2: Streaming with Suspense
+
+```tsx
+// Good: Show content progressively
+import { Suspense } from 'react';
+
+async function Dashboard() {
+  return (
+    <div>
+      <Suspense fallback={<UserSkeleton />}>
+        <UserSection />
+      </Suspense>
+      <Suspense fallback={<PostsSkeleton />}>
+        <PostsSection />
+      </Suspense>
+    </div>
+  );
+}
+
+async function UserSection() {
+  const user = await getUser(); // Fetches independently
+  return <div>{user.name}</div>;
+}
+
+async function PostsSection() {
+  const posts = await getPosts(); // Fetches independently
+  return <PostList posts={posts} />;
+}
+```
+
+### Solution 3: Preload Pattern
+
+```tsx
+// lib/data.ts
+import { cache } from 'react';
+
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } });
+});
+
+export const preloadUser = (id: string) => {
+  void getUser(id); // Fire and forget
+};
+```
+
+```tsx
+// app/user/[id]/page.tsx
+import { getUser, preloadUser } from '@/lib/data';
+
+export default async function UserPage({ params }) {
+  const { id } = await params;
+
+  // Start fetching early
+  preloadUser(id);
+
+  // Do other work...
+
+  // Data likely ready by now
+  const user = await getUser(id);
+  return <div>{user.name}</div>;
+}
+```
+
+## Client Component Data Fetching
+
+When Client Components need data:
+
+### Option 1: Pass from Server Component (Preferred)
+
+```tsx
+// Server Component
+async function Page() {
+  const data = await fetchData();
+  return <ClientComponent initialData={data} />;
+}
+
+// Client Component
+'use client';
+function ClientComponent({ initialData }) {
+  const [data, setData] = useState(initialData);
+  // ...
+}
+```
+
+### Option 2: Fetch on Mount (When Necessary)
+
+```tsx
+'use client';
+import { useEffect, useState } from 'react';
+
+function ClientComponent() {
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    fetch('/api/data')
+      .then(r => r.json())
+      .then(setData);
+  }, []);
+
+  if (!data) return <Loading />;
+  return <div>{data.value}</div>;
+}
+```
+
+### Option 3: Server Action for Reads (Works But Not Ideal)
+
+Server Actions can be called from Client Components for reads, but this is not their intended purpose:
+
+```tsx
+'use client';
+import { getData } from './actions';
+import { useEffect, useState } from 'react';
+
+function ClientComponent() {
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    getData().then(setData);
+  }, []);
+
+  return <div>{data?.value}</div>;
+}
+```
+
+**Note**: Server Actions always use POST, so no HTTP caching. Prefer Route Handlers for cacheable reads.
+
+## Quick Reference
+
+| Pattern | Use Case | HTTP Method | Caching |
+|---------|----------|-------------|---------|
+| Server Component fetch | Internal reads | Any | Full Next.js caching |
+| Server Action | Mutations, form submissions | POST only | No |
+| Route Handler | External APIs, webhooks | Any | GET can be cached |
+| Client fetch to API | Client-side reads | Any | HTTP cache headers |

.agents/skills/next-best-practices/debug-tricks.md

@@ -0,0 +1,105 @@
+# Debug Tricks
+
+Tricks to speed up debugging Next.js applications.
+
+## MCP Endpoint (Dev Server)
+
+Next.js exposes a `/_next/mcp` endpoint in development for AI-assisted debugging via MCP (Model Context Protocol).
+
+- **Next.js 16+**: Enabled by default, use `next-devtools-mcp`
+- **Next.js < 16**: Requires `experimental.mcpServer: true` in next.config.js
+
+Reference: https://nextjs.org/docs/app/guides/mcp
+
+**Important**: Find the actual port of the running Next.js dev server (check terminal output or `package.json` scripts). Don't assume port 3000.
+
+### Request Format
+
+The endpoint uses JSON-RPC 2.0 over HTTP POST:
+
+```bash
+curl -X POST http://localhost:<port>/_next/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "tools/call",
+    "params": {
+      "name": "<tool-name>",
+      "arguments": {}
+    }
+  }'
+```
+
+### Available Tools
+
+#### `get_errors`
+Get current errors from dev server (build errors, runtime errors with source-mapped stacks):
+```json
+{ "name": "get_errors", "arguments": {} }
+```
+
+#### `get_routes`
+Discover all routes by scanning filesystem:
+```json
+{ "name": "get_routes", "arguments": {} }
+// Optional: { "name": "get_routes", "arguments": { "routerType": "app" } }
+```
+Returns: `{ "appRouter": ["/", "/api/users/[id]", ...], "pagesRouter": [...] }`
+
+#### `get_project_metadata`
+Get project path and dev server URL:
+```json
+{ "name": "get_project_metadata", "arguments": {} }
+```
+Returns: `{ "projectPath": "/path/to/project", "devServerUrl": "http://localhost:3000" }`
+
+#### `get_page_metadata`
+Get runtime metadata about current page render (requires active browser session):
+```json
+{ "name": "get_page_metadata", "arguments": {} }
+```
+Returns segment trie data showing layouts, boundaries, and page components.
+
+#### `get_logs`
+Get path to Next.js development log file:
+```json
+{ "name": "get_logs", "arguments": {} }
+```
+Returns path to `<distDir>/logs/next-development.log`
+
+#### `get_server_action_by_id`
+Locate a Server Action by ID:
+```json
+{ "name": "get_server_action_by_id", "arguments": { "actionId": "<action-id>" } }
+```
+
+### Example: Get Errors
+
+```bash
+curl -X POST http://localhost:<port>/_next/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":"1","method":"tools/call","params":{"name":"get_errors","arguments":{}}}'
+```
+
+## Rebuild Specific Routes (Next.js 16+)
+
+Use `--debug-build-paths` to rebuild only specific routes instead of the entire app:
+
+```bash
+# Rebuild a specific route
+next build --debug-build-paths "/dashboard"
+
+# Rebuild routes matching a glob
+next build --debug-build-paths "/api/*"
+
+# Dynamic routes
+next build --debug-build-paths "/blog/[slug]"
+```
+
+Use this to:
+- Quickly verify a build fix without full rebuild
+- Debug static generation issues for specific pages
+- Iterate faster on build errors

.agents/skills/next-best-practices/directives.md

@@ -0,0 +1,73 @@
+# Directives
+
+## React Directives
+
+These are React directives, not Next.js specific.
+
+### `'use client'`
+
+Marks a component as a Client Component. Required for:
+- React hooks (`useState`, `useEffect`, etc.)
+- Event handlers (`onClick`, `onChange`)
+- Browser APIs (`window`, `localStorage`)
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+```
+
+Reference: https://react.dev/reference/rsc/use-client
+
+### `'use server'`
+
+Marks a function as a Server Action. Can be passed to Client Components.
+
+```tsx
+'use server'
+
+export async function submitForm(formData: FormData) {
+  // Runs on server
+}
+```
+
+Or inline within a Server Component:
+
+```tsx
+export default function Page() {
+  async function submit() {
+    'use server'
+    // Runs on server
+  }
+  return <form action={submit}>...</form>
+}
+```
+
+Reference: https://react.dev/reference/rsc/use-server
+
+---
+
+## Next.js Directive
+
+### `'use cache'`
+
+Marks a function or component for caching. Part of Next.js Cache Components.
+
+```tsx
+'use cache'
+
+export async function getCachedData() {
+  return await fetchData()
+}
+```
+
+Requires `cacheComponents: true` in `next.config.ts`.
+
+For detailed usage including cache profiles, `cacheLife()`, `cacheTag()`, and `updateTag()`, see the `next-cache-components` skill.
+
+Reference: https://nextjs.org/docs/app/api-reference/directives/use-cache

.agents/skills/next-best-practices/error-handling.md

@@ -0,0 +1,227 @@
+# Error Handling
+
+Handle errors gracefully in Next.js applications.
+
+Reference: https://nextjs.org/docs/app/getting-started/error-handling
+
+## Error Boundaries
+
+### `error.tsx`
+
+Catches errors in a route segment and its children:
+
+```tsx
+'use client'
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={() => reset()}>Try again</button>
+    </div>
+  )
+}
+```
+
+**Important:** `error.tsx` must be a Client Component.
+
+### `global-error.tsx`
+
+Catches errors in root layout:
+
+```tsx
+'use client'
+
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  return (
+    <html>
+      <body>
+        <h2>Something went wrong!</h2>
+        <button onClick={() => reset()}>Try again</button>
+      </body>
+    </html>
+  )
+}
+```
+
+**Important:** Must include `<html>` and `<body>` tags.
+
+## Server Actions: Navigation API Gotcha
+
+**Do NOT wrap navigation APIs in try-catch.** They throw special errors that Next.js handles internally.
+
+Reference: https://nextjs.org/docs/app/api-reference/functions/redirect#behavior
+
+```tsx
+'use server'
+
+import { redirect } from 'next/navigation'
+import { notFound } from 'next/navigation'
+
+// Bad: try-catch catches the navigation "error"
+async function createPost(formData: FormData) {
+  try {
+    const post = await db.post.create({ ... })
+    redirect(`/posts/${post.id}`)  // This throws!
+  } catch (error) {
+    // redirect() throw is caught here - navigation fails!
+    return { error: 'Failed to create post' }
+  }
+}
+
+// Good: Call navigation APIs outside try-catch
+async function createPost(formData: FormData) {
+  let post
+  try {
+    post = await db.post.create({ ... })
+  } catch (error) {
+    return { error: 'Failed to create post' }
+  }
+  redirect(`/posts/${post.id}`)  // Outside try-catch
+}
+
+// Good: Re-throw navigation errors
+async function createPost(formData: FormData) {
+  try {
+    const post = await db.post.create({ ... })
+    redirect(`/posts/${post.id}`)
+  } catch (error) {
+    if (error instanceof Error && error.message === 'NEXT_REDIRECT') {
+      throw error  // Re-throw navigation errors
+    }
+    return { error: 'Failed to create post' }
+  }
+}
+```
+
+Same applies to:
+- `redirect()` - 307 temporary redirect
+- `permanentRedirect()` - 308 permanent redirect
+- `notFound()` - 404 not found
+- `forbidden()` - 403 forbidden
+- `unauthorized()` - 401 unauthorized
+
+Use `unstable_rethrow()` to re-throw these errors in catch blocks:
+
+```tsx
+import { unstable_rethrow } from 'next/navigation'
+
+async function action() {
+  try {
+    // ...
+    redirect('/success')
+  } catch (error) {
+    unstable_rethrow(error) // Re-throws Next.js internal errors
+    return { error: 'Something went wrong' }
+  }
+}
+```
+
+## Redirects
+
+```tsx
+import { redirect, permanentRedirect } from 'next/navigation'
+
+// 307 Temporary - use for most cases
+redirect('/new-path')
+
+// 308 Permanent - use for URL migrations (cached by browsers)
+permanentRedirect('/new-url')
+```
+
+## Auth Errors
+
+Trigger auth-related error pages:
+
+```tsx
+import { forbidden, unauthorized } from 'next/navigation'
+
+async function Page() {
+  const session = await getSession()
+
+  if (!session) {
+    unauthorized() // Renders unauthorized.tsx (401)
+  }
+
+  if (!session.hasAccess) {
+    forbidden() // Renders forbidden.tsx (403)
+  }
+
+  return <Dashboard />
+}
+```
+
+Create corresponding error pages:
+
+```tsx
+// app/forbidden.tsx
+export default function Forbidden() {
+  return <div>You don't have access to this resource</div>
+}
+
+// app/unauthorized.tsx
+export default function Unauthorized() {
+  return <div>Please log in to continue</div>
+}
+```
+
+## Not Found
+
+### `not-found.tsx`
+
+Custom 404 page for a route segment:
+
+```tsx
+export default function NotFound() {
+  return (
+    <div>
+      <h2>Not Found</h2>
+      <p>Could not find the requested resource</p>
+    </div>
+  )
+}
+```
+
+### Triggering Not Found
+
+```tsx
+import { notFound } from 'next/navigation'
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const post = await getPost(id)
+
+  if (!post) {
+    notFound()  // Renders closest not-found.tsx
+  }
+
+  return <div>{post.title}</div>
+}
+```
+
+## Error Hierarchy
+
+Errors bubble up to the nearest error boundary:
+
+```
+app/
+├── error.tsx           # Catches errors from all children
+├── blog/
+│   ├── error.tsx       # Catches errors in /blog/*
+│   └── [slug]/
+│       ├── error.tsx   # Catches errors in /blog/[slug]
+│       └── page.tsx
+└── layout.tsx          # Errors here go to global-error.tsx
+```

.agents/skills/next-best-practices/file-conventions.md

@@ -0,0 +1,140 @@
+# File Conventions
+
+Next.js App Router uses file-based routing with special file conventions.
+
+## Project Structure
+
+Reference: https://nextjs.org/docs/app/getting-started/project-structure
+
+```
+app/
+├── layout.tsx          # Root layout (required)
+├── page.tsx            # Home page (/)
+├── loading.tsx         # Loading UI
+├── error.tsx           # Error UI
+├── not-found.tsx       # 404 UI
+├── global-error.tsx    # Global error UI
+├── route.ts            # API endpoint
+├── template.tsx        # Re-rendered layout
+├── default.tsx         # Parallel route fallback
+├── blog/
+│   ├── page.tsx        # /blog
+│   └── [slug]/
+│       └── page.tsx    # /blog/:slug
+└── (group)/            # Route group (no URL impact)
+    └── page.tsx
+```
+
+## Special Files
+
+| File | Purpose |
+|------|---------|
+| `page.tsx` | UI for a route segment |
+| `layout.tsx` | Shared UI for segment and children |
+| `loading.tsx` | Loading UI (Suspense boundary) |
+| `error.tsx` | Error UI (Error boundary) |
+| `not-found.tsx` | 404 UI |
+| `route.ts` | API endpoint |
+| `template.tsx` | Like layout but re-renders on navigation |
+| `default.tsx` | Fallback for parallel routes |
+
+## Route Segments
+
+```
+app/
+├── blog/               # Static segment: /blog
+├── [slug]/             # Dynamic segment: /:slug
+├── [...slug]/          # Catch-all: /a/b/c
+├── [[...slug]]/        # Optional catch-all: / or /a/b/c
+└── (marketing)/        # Route group (ignored in URL)
+```
+
+## Parallel Routes
+
+```
+app/
+├── @analytics/
+│   └── page.tsx
+├── @sidebar/
+│   └── page.tsx
+└── layout.tsx          # Receives { analytics, sidebar } as props
+```
+
+## Intercepting Routes
+
+```
+app/
+├── feed/
+│   └── page.tsx
+├── @modal/
+│   └── (.)photo/[id]/  # Intercepts /photo/[id] from /feed
+│       └── page.tsx
+└── photo/[id]/
+    └── page.tsx
+```
+
+Conventions:
+- `(.)` - same level
+- `(..)` - one level up
+- `(..)(..)` - two levels up
+- `(...)` - from root
+
+## Private Folders
+
+```
+app/
+├── _components/        # Private folder (not a route)
+│   └── Button.tsx
+└── page.tsx
+```
+
+Prefix with `_` to exclude from routing.
+
+## Middleware / Proxy
+
+### Next.js 14-15: `middleware.ts`
+
+```ts
+// middleware.ts (root of project)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function middleware(request: NextRequest) {
+  // Auth, redirects, rewrites, etc.
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+### Next.js 16+: `proxy.ts`
+
+Renamed for clarity - same capabilities, different names:
+
+```ts
+// proxy.ts (root of project)
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+
+export function proxy(request: NextRequest) {
+  // Same logic as middleware
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+| Version | File | Export | Config |
+|---------|------|--------|--------|
+| v14-15 | `middleware.ts` | `middleware()` | `config` |
+| v16+ | `proxy.ts` | `proxy()` | `config` |
+
+**Migration**: Run `npx @next/codemod@latest upgrade` to auto-rename.
+
+## File Conventions Reference
+
+Reference: https://nextjs.org/docs/app/api-reference/file-conventions

.agents/skills/next-best-practices/font.md

@@ -0,0 +1,245 @@
+# Font Optimization
+
+Use `next/font` for automatic font optimization with zero layout shift.
+
+## Google Fonts
+
+```tsx
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+
+const inter = Inter({ subsets: ['latin'] })
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={inter.className}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+## Multiple Fonts
+
+```tsx
+import { Inter, Roboto_Mono } from 'next/font/google'
+
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-inter',
+})
+
+const robotoMono = Roboto_Mono({
+  subsets: ['latin'],
+  variable: '--font-roboto-mono',
+})
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${robotoMono.variable}`}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+Use in CSS:
+```css
+body {
+  font-family: var(--font-inter);
+}
+
+code {
+  font-family: var(--font-roboto-mono);
+}
+```
+
+## Font Weights and Styles
+
+```tsx
+// Single weight
+const inter = Inter({
+  subsets: ['latin'],
+  weight: '400',
+})
+
+// Multiple weights
+const inter = Inter({
+  subsets: ['latin'],
+  weight: ['400', '500', '700'],
+})
+
+// Variable font (recommended) - includes all weights
+const inter = Inter({
+  subsets: ['latin'],
+  // No weight needed - variable fonts support all weights
+})
+
+// With italic
+const inter = Inter({
+  subsets: ['latin'],
+  style: ['normal', 'italic'],
+})
+```
+
+## Local Fonts
+
+```tsx
+import localFont from 'next/font/local'
+
+const myFont = localFont({
+  src: './fonts/MyFont.woff2',
+})
+
+// Multiple files for different weights
+const myFont = localFont({
+  src: [
+    {
+      path: './fonts/MyFont-Regular.woff2',
+      weight: '400',
+      style: 'normal',
+    },
+    {
+      path: './fonts/MyFont-Bold.woff2',
+      weight: '700',
+      style: 'normal',
+    },
+  ],
+})
+
+// Variable font
+const myFont = localFont({
+  src: './fonts/MyFont-Variable.woff2',
+  variable: '--font-my-font',
+})
+```
+
+## Tailwind CSS Integration
+
+```tsx
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-inter',
+})
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className={inter.variable}>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+```js
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['var(--font-inter)'],
+      },
+    },
+  },
+}
+```
+
+## Preloading Subsets
+
+Only load needed character subsets:
+
+```tsx
+// Latin only (most common)
+const inter = Inter({ subsets: ['latin'] })
+
+// Multiple subsets
+const inter = Inter({ subsets: ['latin', 'latin-ext', 'cyrillic'] })
+```
+
+## Display Strategy
+
+Control font loading behavior:
+
+```tsx
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap', // Default - shows fallback, swaps when loaded
+})
+
+// Options:
+// 'auto' - browser decides
+// 'block' - short block period, then swap
+// 'swap' - immediate fallback, swap when ready (recommended)
+// 'fallback' - short block, short swap, then fallback
+// 'optional' - short block, no swap (use if font is optional)
+```
+
+## Don't Use Manual Font Links
+
+Always use `next/font` instead of `<link>` tags for Google Fonts.
+
+```tsx
+// Bad: Manual link tag (blocks rendering, no optimization)
+<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
+
+// Bad: Missing display and preconnect
+<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
+
+// Good: Use next/font (self-hosted, zero layout shift)
+import { Inter } from 'next/font/google'
+
+const inter = Inter({ subsets: ['latin'] })
+```
+
+## Common Mistakes
+
+```tsx
+// Bad: Importing font in every component
+// components/Button.tsx
+import { Inter } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'] }) // Creates new instance each time!
+
+// Good: Import once in layout, use CSS variable
+// app/layout.tsx
+const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+
+// Bad: Using @import in CSS (blocks rendering)
+/* globals.css */
+@import url('https://fonts.googleapis.com/css2?family=Inter');
+
+// Good: Use next/font (self-hosted, no network request)
+import { Inter } from 'next/font/google'
+
+// Bad: Loading all weights when only using a few
+const inter = Inter({ subsets: ['latin'] }) // Loads all weights
+
+// Good: Specify only needed weights (for non-variable fonts)
+const inter = Inter({ subsets: ['latin'], weight: ['400', '700'] })
+
+// Bad: Missing subset - loads all characters
+const inter = Inter({})
+
+// Good: Always specify subset
+const inter = Inter({ subsets: ['latin'] })
+```
+
+## Font in Specific Components
+
+```tsx
+// For component-specific fonts, export from a shared file
+// lib/fonts.ts
+import { Inter, Playfair_Display } from 'next/font/google'
+
+export const inter = Inter({ subsets: ['latin'], variable: '--font-inter' })
+export const playfair = Playfair_Display({ subsets: ['latin'], variable: '--font-playfair' })
+
+// components/Heading.tsx
+import { playfair } from '@/lib/fonts'
+
+export function Heading({ children }) {
+  return <h1 className={playfair.className}>{children}</h1>
+}
+```

.agents/skills/next-best-practices/functions.md

@@ -0,0 +1,108 @@
+# Functions
+
+Next.js function APIs.
+
+Reference: https://nextjs.org/docs/app/api-reference/functions
+
+## Navigation Hooks (Client)
+
+| Hook | Purpose | Reference |
+|------|---------|-----------|
+| `useRouter` | Programmatic navigation (`push`, `replace`, `back`, `refresh`) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-router) |
+| `usePathname` | Get current pathname | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-pathname) |
+| `useSearchParams` | Read URL search parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-search-params) |
+| `useParams` | Access dynamic route parameters | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-params) |
+| `useSelectedLayoutSegment` | Active child segment (one level) | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segment) |
+| `useSelectedLayoutSegments` | All active segments below layout | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-selected-layout-segments) |
+| `useLinkStatus` | Check link prefetch status | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-link-status) |
+| `useReportWebVitals` | Report Core Web Vitals metrics | [Docs](https://nextjs.org/docs/app/api-reference/functions/use-report-web-vitals) |
+
+## Server Functions
+
+| Function | Purpose | Reference |
+|----------|---------|-----------|
+| `cookies` | Read/write cookies | [Docs](https://nextjs.org/docs/app/api-reference/functions/cookies) |
+| `headers` | Read request headers | [Docs](https://nextjs.org/docs/app/api-reference/functions/headers) |
+| `draftMode` | Enable preview of unpublished CMS content | [Docs](https://nextjs.org/docs/app/api-reference/functions/draft-mode) |
+| `after` | Run code after response finishes streaming | [Docs](https://nextjs.org/docs/app/api-reference/functions/after) |
+| `connection` | Wait for connection before dynamic rendering | [Docs](https://nextjs.org/docs/app/api-reference/functions/connection) |
+| `userAgent` | Parse User-Agent header | [Docs](https://nextjs.org/docs/app/api-reference/functions/userAgent) |
+
+## Generate Functions
+
+| Function | Purpose | Reference |
+|----------|---------|-----------|
+| `generateStaticParams` | Pre-render dynamic routes at build time | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) |
+| `generateMetadata` | Dynamic metadata | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-metadata) |
+| `generateViewport` | Dynamic viewport config | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-viewport) |
+| `generateSitemaps` | Multiple sitemaps for large sites | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-sitemaps) |
+| `generateImageMetadata` | Multiple OG images per route | [Docs](https://nextjs.org/docs/app/api-reference/functions/generate-image-metadata) |
+
+## Request/Response
+
+| Function | Purpose | Reference |
+|----------|---------|-----------|
+| `NextRequest` | Extended Request with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-request) |
+| `NextResponse` | Extended Response with helpers | [Docs](https://nextjs.org/docs/app/api-reference/functions/next-response) |
+| `ImageResponse` | Generate OG images | [Docs](https://nextjs.org/docs/app/api-reference/functions/image-response) |
+
+## Common Examples
+
+### Navigation
+
+Use `next/link` for internal navigation instead of `<a>` tags.
+
+```tsx
+// Bad: Plain anchor tag
+<a href="/about">About</a>
+
+// Good: Next.js Link
+import Link from 'next/link'
+
+<Link href="/about">About</Link>
+```
+
+Active link styling:
+
+```tsx
+'use client'
+
+import Link from 'next/link'
+import { usePathname } from 'next/navigation'
+
+export function NavLink({ href, children }) {
+  const pathname = usePathname()
+
+  return (
+    <Link href={href} className={pathname === href ? 'active' : ''}>
+      {children}
+    </Link>
+  )
+}
+```
+
+### Static Generation
+
+```tsx
+// app/blog/[slug]/page.tsx
+export async function generateStaticParams() {
+  const posts = await getPosts()
+  return posts.map((post) => ({ slug: post.slug }))
+}
+```
+
+### After Response
+
+```tsx
+import { after } from 'next/server'
+
+export async function POST(request: Request) {
+  const data = await processRequest(request)
+
+  after(async () => {
+    await logAnalytics(data)
+  })
+
+  return Response.json({ success: true })
+}
+```

.agents/skills/next-best-practices/hydration-error.md

@@ -0,0 +1,91 @@
+# Hydration Errors
+
+Diagnose and fix React hydration mismatch errors.
+
+## Error Signs
+
+- "Hydration failed because the initial UI does not match"
+- "Text content does not match server-rendered HTML"
+
+## Debugging
+
+In development, click the hydration error to see the server/client diff.
+
+## Common Causes and Fixes
+
+### Browser-only APIs
+
+```tsx
+// Bad: Causes mismatch - window doesn't exist on server
+<div>{window.innerWidth}</div>
+
+// Good: Use client component with mounted check
+'use client'
+import { useState, useEffect } from 'react'
+
+export function ClientOnly({ children }: { children: React.ReactNode }) {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => setMounted(true), [])
+  return mounted ? children : null
+}
+```
+
+### Date/Time Rendering
+
+Server and client may be in different timezones:
+
+```tsx
+// Bad: Causes mismatch
+<span>{new Date().toLocaleString()}</span>
+
+// Good: Render on client only
+'use client'
+const [time, setTime] = useState<string>()
+useEffect(() => setTime(new Date().toLocaleString()), [])
+```
+
+### Random Values or IDs
+
+```tsx
+// Bad: Random values differ between server and client
+<div id={Math.random().toString()}>
+
+// Good: Use useId hook
+import { useId } from 'react'
+
+function Input() {
+  const id = useId()
+  return <input id={id} />
+}
+```
+
+### Invalid HTML Nesting
+
+```tsx
+// Bad: Invalid - div inside p
+<p><div>Content</div></p>
+
+// Bad: Invalid - p inside p
+<p><p>Nested</p></p>
+
+// Good: Valid nesting
+<div><p>Content</p></div>
+```
+
+### Third-party Scripts
+
+Scripts that modify DOM during hydration.
+
+```tsx
+// Good: Use next/script with afterInteractive
+import Script from 'next/script'
+
+export default function Page() {
+  return (
+    <Script
+      src="https://example.com/script.js"
+      strategy="afterInteractive"
+    />
+  )
+}
+```

.agents/skills/next-best-practices/image.md

@@ -0,0 +1,173 @@
+# Image Optimization
+
+Use `next/image` for automatic image optimization.
+
+## Always Use next/image
+
+```tsx
+// Bad: Avoid native img
+<img src="/hero.png" alt="Hero" />
+
+// Good: Use next/image
+import Image from 'next/image'
+<Image src="/hero.png" alt="Hero" width={800} height={400} />
+```
+
+## Required Props
+
+Images need explicit dimensions to prevent layout shift:
+
+```tsx
+// Local images - dimensions inferred automatically
+import heroImage from './hero.png'
+<Image src={heroImage} alt="Hero" />
+
+// Remote images - must specify width/height
+<Image src="https://example.com/image.jpg" alt="Hero" width={800} height={400} />
+
+// Or use fill for parent-relative sizing
+<div style={{ position: 'relative', width: '100%', height: 400 }}>
+  <Image src="/hero.png" alt="Hero" fill style={{ objectFit: 'cover' }} />
+</div>
+```
+
+## Remote Images Configuration
+
+Remote domains must be configured in `next.config.js`:
+
+```js
+// next.config.js
+module.exports = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: 'https',
+        hostname: 'example.com',
+        pathname: '/images/**',
+      },
+      {
+        protocol: 'https',
+        hostname: '*.cdn.com', // Wildcard subdomain
+      },
+    ],
+  },
+}
+```
+
+## Responsive Images
+
+Use `sizes` to tell the browser which size to download:
+
+```tsx
+// Full-width hero
+<Image
+  src="/hero.png"
+  alt="Hero"
+  fill
+  sizes="100vw"
+/>
+
+// Responsive grid (3 columns on desktop, 1 on mobile)
+<Image
+  src="/card.png"
+  alt="Card"
+  fill
+  sizes="(max-width: 768px) 100vw, 33vw"
+/>
+
+// Fixed sidebar image
+<Image
+  src="/avatar.png"
+  alt="Avatar"
+  width={200}
+  height={200}
+  sizes="200px"
+/>
+```
+
+## Blur Placeholder
+
+Prevent layout shift with placeholders:
+
+```tsx
+// Local images - automatic blur hash
+import heroImage from './hero.png'
+<Image src={heroImage} alt="Hero" placeholder="blur" />
+
+// Remote images - provide blurDataURL
+<Image
+  src="https://example.com/image.jpg"
+  alt="Hero"
+  width={800}
+  height={400}
+  placeholder="blur"
+  blurDataURL="data:image/jpeg;base64,/9j/4AAQSkZJRg..."
+/>
+
+// Or use color placeholder
+<Image
+  src="https://example.com/image.jpg"
+  alt="Hero"
+  width={800}
+  height={400}
+  placeholder="empty"
+  style={{ backgroundColor: '#e0e0e0' }}
+/>
+```
+
+## Priority Loading
+
+Use `priority` for above-the-fold images (LCP):
+
+```tsx
+// Hero image - loads immediately
+<Image src="/hero.png" alt="Hero" fill priority />
+
+// Below-fold images - lazy loaded by default (no priority needed)
+<Image src="/card.png" alt="Card" width={400} height={300} />
+```
+
+## Common Mistakes
+
+```tsx
+// Bad: Missing sizes with fill - downloads largest image
+<Image src="/hero.png" alt="Hero" fill />
+
+// Good: Add sizes for proper responsive behavior
+<Image src="/hero.png" alt="Hero" fill sizes="100vw" />
+
+// Bad: Using width/height for aspect ratio only
+<Image src="/hero.png" alt="Hero" width={16} height={9} />
+
+// Good: Use actual display dimensions or fill with sizes
+<Image src="/hero.png" alt="Hero" fill sizes="100vw" style={{ objectFit: 'cover' }} />
+
+// Bad: Remote image without config
+<Image src="https://untrusted.com/image.jpg" alt="Image" width={400} height={300} />
+// Error: Invalid src prop, hostname not configured
+
+// Good: Add hostname to next.config.js remotePatterns
+```
+
+## Static Export
+
+When using `output: 'export'`, use `unoptimized` or custom loader:
+
+```tsx
+// Option 1: Disable optimization
+<Image src="/hero.png" alt="Hero" width={800} height={400} unoptimized />
+
+// Option 2: Global config
+// next.config.js
+module.exports = {
+  output: 'export',
+  images: { unoptimized: true },
+}
+
+// Option 3: Custom loader (Cloudinary, Imgix, etc.)
+const cloudinaryLoader = ({ src, width, quality }) => {
+  return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 75}/${src}`
+}
+
+<Image loader={cloudinaryLoader} src="sample.jpg" alt="Sample" width={800} height={400} />
+```

.agents/skills/next-best-practices/metadata.md

@@ -0,0 +1,301 @@
+# Metadata
+
+Add SEO metadata to Next.js pages using the Metadata API.
+
+## Important: Server Components Only
+
+The `metadata` object and `generateMetadata` function are **only supported in Server Components**. They cannot be used in Client Components.
+
+If the target page has `'use client'`:
+1. Remove `'use client'` if possible, move client logic to child components
+2. Or extract metadata to a parent Server Component layout
+3. Or split the file: Server Component with metadata imports Client Components
+
+## Static Metadata
+
+```tsx
+import type { Metadata } from 'next'
+
+export const metadata: Metadata = {
+  title: 'Page Title',
+  description: 'Page description for search engines',
+}
+```
+
+## Dynamic Metadata
+
+```tsx
+import type { Metadata } from 'next'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params
+  const post = await getPost(slug)
+  return { title: post.title, description: post.description }
+}
+```
+
+## Avoid Duplicate Fetches
+
+Use React `cache()` when the same data is needed for both metadata and page:
+
+```tsx
+import { cache } from 'react'
+
+export const getPost = cache(async (slug: string) => {
+  return await db.posts.findFirst({ where: { slug } })
+})
+```
+
+## Viewport
+
+Separate from metadata for streaming support:
+
+```tsx
+import type { Viewport } from 'next'
+
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  themeColor: '#000000',
+}
+
+// Or dynamic
+export function generateViewport({ params }): Viewport {
+  return { themeColor: getThemeColor(params) }
+}
+```
+
+## Title Templates
+
+In root layout for consistent naming:
+
+```tsx
+export const metadata: Metadata = {
+  title: { default: 'Site Name', template: '%s | Site Name' },
+}
+```
+
+## Metadata File Conventions
+
+Reference: https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions
+
+Place these files in `app/` directory (or route segments):
+
+| File | Purpose |
+|------|---------|
+| `favicon.ico` | Favicon |
+| `icon.png` / `icon.svg` | App icon |
+| `apple-icon.png` | Apple app icon |
+| `opengraph-image.png` | OG image |
+| `twitter-image.png` | Twitter card image |
+| `sitemap.ts` / `sitemap.xml` | Sitemap (use `generateSitemaps` for multiple) |
+| `robots.ts` / `robots.txt` | Robots directives |
+| `manifest.ts` / `manifest.json` | Web app manifest |
+
+## SEO Best Practice: Static Files Are Often Enough
+
+For most sites, **static metadata files provide excellent SEO coverage**:
+
+```
+app/
+├── favicon.ico
+├── opengraph-image.png     # Works for both OG and Twitter
+├── sitemap.ts
+├── robots.ts
+└── layout.tsx              # With title/description metadata
+```
+
+**Tips:**
+- A single `opengraph-image.png` covers both Open Graph and Twitter (Twitter falls back to OG)
+- Static `title` and `description` in layout metadata is sufficient for most pages
+- Only use dynamic `generateMetadata` when content varies per page
+
+---
+
+# OG Image Generation
+
+Generate dynamic Open Graph images using `next/og`.
+
+## Important Rules
+
+1. **Use `next/og`** - not `@vercel/og` (it's built into Next.js)
+2. **No searchParams** - OG images can't access search params, use route params instead
+3. **Avoid Edge runtime** - Use default Node.js runtime
+
+```tsx
+// Good
+import { ImageResponse } from 'next/og'
+
+// Bad
+// import { ImageResponse } from '@vercel/og'
+// export const runtime = 'edge'
+```
+
+## Basic OG Image
+
+```tsx
+// app/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export const alt = 'Site Name'
+export const size = { width: 1200, height: 630 }
+export const contentType = 'image/png'
+
+export default function Image() {
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          fontSize: 128,
+          background: 'white',
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        Hello World
+      </div>
+    ),
+    { ...size }
+  )
+}
+```
+
+## Dynamic OG Image
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export const alt = 'Blog Post'
+export const size = { width: 1200, height: 630 }
+export const contentType = 'image/png'
+
+type Props = { params: Promise<{ slug: string }> }
+
+export default async function Image({ params }: Props) {
+  const { slug } = await params
+  const post = await getPost(slug)
+
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          fontSize: 48,
+          background: 'linear-gradient(to bottom, #1a1a1a, #333)',
+          color: 'white',
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: 48,
+        }}
+      >
+        <div style={{ fontSize: 64, fontWeight: 'bold' }}>{post.title}</div>
+        <div style={{ marginTop: 24, opacity: 0.8 }}>{post.description}</div>
+      </div>
+    ),
+    { ...size }
+  )
+}
+```
+
+## Custom Fonts
+
+```tsx
+import { ImageResponse } from 'next/og'
+import { join } from 'path'
+import { readFile } from 'fs/promises'
+
+export default async function Image() {
+  const fontPath = join(process.cwd(), 'assets/fonts/Inter-Bold.ttf')
+  const fontData = await readFile(fontPath)
+
+  return new ImageResponse(
+    (
+      <div style={{ fontFamily: 'Inter', fontSize: 64 }}>
+        Custom Font Text
+      </div>
+    ),
+    {
+      width: 1200,
+      height: 630,
+      fonts: [{ name: 'Inter', data: fontData, style: 'normal' }],
+    }
+  )
+}
+```
+
+## File Naming
+
+- `opengraph-image.tsx` - Open Graph (Facebook, LinkedIn)
+- `twitter-image.tsx` - Twitter/X cards (optional, falls back to OG)
+
+## Styling Notes
+
+ImageResponse uses Flexbox layout:
+- Use `display: 'flex'`
+- No CSS Grid support
+- Styles must be inline objects
+
+## Multiple OG Images
+
+Use `generateImageMetadata` for multiple images per route:
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export async function generateImageMetadata({ params }) {
+  const images = await getPostImages(params.slug)
+  return images.map((img, idx) => ({
+    id: idx,
+    alt: img.alt,
+    size: { width: 1200, height: 630 },
+    contentType: 'image/png',
+  }))
+}
+
+export default async function Image({ params, id }) {
+  const images = await getPostImages(params.slug)
+  const image = images[id]
+  return new ImageResponse(/* ... */)
+}
+```
+
+## Multiple Sitemaps
+
+Use `generateSitemaps` for large sites:
+
+```tsx
+// app/sitemap.ts
+import type { MetadataRoute } from 'next'
+
+export async function generateSitemaps() {
+  // Return array of sitemap IDs
+  return [{ id: 0 }, { id: 1 }, { id: 2 }]
+}
+
+export default async function sitemap({
+  id,
+}: {
+  id: number
+}): Promise<MetadataRoute.Sitemap> {
+  const start = id * 50000
+  const end = start + 50000
+  const products = await getProducts(start, end)
+
+  return products.map((product) => ({
+    url: `https://example.com/product/${product.id}`,
+    lastModified: product.updatedAt,
+  }))
+}
+```
+
+Generates `/sitemap/0.xml`, `/sitemap/1.xml`, etc.

.agents/skills/next-best-practices/parallel-routes.md

@@ -0,0 +1,287 @@
+# Parallel & Intercepting Routes
+
+Parallel routes render multiple pages in the same layout. Intercepting routes show a different UI when navigating from within your app vs direct URL access. Together they enable modal patterns.
+
+## File Structure
+
+```
+app/
+├── @modal/                    # Parallel route slot
+│   ├── default.tsx            # Required! Returns null
+│   ├── (.)photos/             # Intercepts /photos/*
+│   │   └── [id]/
+│   │       └── page.tsx       # Modal content
+│   └── [...]catchall/         # Optional: catch unmatched
+│       └── page.tsx
+├── photos/
+│   └── [id]/
+│       └── page.tsx           # Full page (direct access)
+├── layout.tsx                 # Renders both children and @modal
+└── page.tsx
+```
+
+## Step 1: Root Layout with Slot
+
+```tsx
+// app/layout.tsx
+export default function RootLayout({
+  children,
+  modal,
+}: {
+  children: React.ReactNode;
+  modal: React.ReactNode;
+}) {
+  return (
+    <html>
+      <body>
+        {children}
+        {modal}
+      </body>
+    </html>
+  );
+}
+```
+
+## Step 2: Default File (Critical!)
+
+**Every parallel route slot MUST have a `default.tsx`** to prevent 404s on hard navigation.
+
+```tsx
+// app/@modal/default.tsx
+export default function Default() {
+  return null;
+}
+```
+
+Without this file, refreshing any page will 404 because Next.js can't determine what to render in the `@modal` slot.
+
+## Step 3: Intercepting Route (Modal)
+
+The `(.)` prefix intercepts routes at the same level.
+
+```tsx
+// app/@modal/(.)photos/[id]/page.tsx
+import { Modal } from '@/components/modal';
+
+export default async function PhotoModal({
+  params
+}: {
+  params: Promise<{ id: string }>
+}) {
+  const { id } = await params;
+  const photo = await getPhoto(id);
+
+  return (
+    <Modal>
+      <img src={photo.url} alt={photo.title} />
+    </Modal>
+  );
+}
+```
+
+## Step 4: Full Page (Direct Access)
+
+```tsx
+// app/photos/[id]/page.tsx
+export default async function PhotoPage({
+  params
+}: {
+  params: Promise<{ id: string }>
+}) {
+  const { id } = await params;
+  const photo = await getPhoto(id);
+
+  return (
+    <div className="full-page">
+      <img src={photo.url} alt={photo.title} />
+      <h1>{photo.title}</h1>
+    </div>
+  );
+}
+```
+
+## Step 5: Modal Component with Correct Closing
+
+**Critical: Use `router.back()` to close modals, NOT `router.push()` or `<Link>`.**
+
+```tsx
+// components/modal.tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { useCallback, useEffect, useRef } from 'react';
+
+export function Modal({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+  const overlayRef = useRef<HTMLDivElement>(null);
+
+  // Close on escape key
+  useEffect(() => {
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        router.back(); // Correct
+      }
+    }
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [router]);
+
+  // Close on overlay click
+  const handleOverlayClick = useCallback((e: React.MouseEvent) => {
+    if (e.target === overlayRef.current) {
+      router.back(); // Correct
+    }
+  }, [router]);
+
+  return (
+    <div
+      ref={overlayRef}
+      onClick={handleOverlayClick}
+      className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
+    >
+      <div className="bg-white rounded-lg p-6 max-w-2xl w-full mx-4">
+        <button
+          onClick={() => router.back()} // Correct!
+          className="absolute top-4 right-4"
+        >
+          Close
+        </button>
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+
+### Why NOT `router.push('/')` or `<Link href="/">`?
+
+Using `push` or `Link` to "close" a modal:
+1. Adds a new history entry (back button shows modal again)
+2. Doesn't properly clear the intercepted route
+3. Can cause the modal to flash or persist unexpectedly
+
+`router.back()` correctly:
+1. Removes the intercepted route from history
+2. Returns to the previous page
+3. Properly unmounts the modal
+
+## Route Matcher Reference
+
+Matchers match **route segments**, not filesystem paths:
+
+| Matcher | Matches | Example |
+|---------|---------|---------|
+| `(.)` | Same level | `@modal/(.)photos` intercepts `/photos` |
+| `(..)` | One level up | `@modal/(..)settings` from `/dashboard/@modal` intercepts `/settings` |
+| `(..)(..)` | Two levels up | Rarely used |
+| `(...)` | From root | `@modal/(...)photos` intercepts `/photos` from anywhere |
+
+**Common mistake**: Thinking `(..)` means "parent folder" - it means "parent route segment".
+
+## Handling Hard Navigation
+
+When users directly visit `/photos/123` (bookmark, refresh, shared link):
+- The intercepting route is bypassed
+- The full `photos/[id]/page.tsx` renders
+- Modal doesn't appear (expected behavior)
+
+If you want the modal to appear on direct access too, you need additional logic:
+
+```tsx
+// app/photos/[id]/page.tsx
+import { Modal } from '@/components/modal';
+
+export default async function PhotoPage({ params }) {
+  const { id } = await params;
+  const photo = await getPhoto(id);
+
+  // Option: Render as modal on direct access too
+  return (
+    <Modal>
+      <img src={photo.url} alt={photo.title} />
+    </Modal>
+  );
+}
+```
+
+## Common Gotchas
+
+### 1. Missing `default.tsx` → 404 on Refresh
+
+Every `@slot` folder needs a `default.tsx` that returns `null` (or appropriate content).
+
+### 2. Modal Persists After Navigation
+
+You're using `router.push()` instead of `router.back()`.
+
+### 3. Nested Parallel Routes Need Defaults Too
+
+If you have `@modal` inside a route group, each level needs its own `default.tsx`:
+
+```
+app/
+├── (marketing)/
+│   ├── @modal/
+│   │   └── default.tsx     # Needed!
+│   └── layout.tsx
+└── layout.tsx
+```
+
+### 4. Intercepted Route Shows Wrong Content
+
+Check your matcher:
+- `(.)photos` intercepts `/photos` from the same route level
+- If your `@modal` is in `app/dashboard/@modal`, use `(.)photos` to intercept `/dashboard/photos`, not `/photos`
+
+### 5. TypeScript Errors with `params`
+
+In Next.js 15+, `params` is a Promise:
+
+```tsx
+// Correct
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+}
+```
+
+## Complete Example: Photo Gallery Modal
+
+```
+app/
+├── @modal/
+│   ├── default.tsx
+│   └── (.)photos/
+│       └── [id]/
+│           └── page.tsx
+├── photos/
+│   ├── page.tsx           # Gallery grid
+│   └── [id]/
+│       └── page.tsx       # Full photo page
+├── layout.tsx
+└── page.tsx
+```
+
+Links in the gallery:
+
+```tsx
+// app/photos/page.tsx
+import Link from 'next/link';
+
+export default async function Gallery() {
+  const photos = await getPhotos();
+
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {photos.map(photo => (
+        <Link key={photo.id} href={`/photos/${photo.id}`}>
+          <img src={photo.thumbnail} alt={photo.title} />
+        </Link>
+      ))}
+    </div>
+  );
+}
+```
+
+Clicking a photo → Modal opens (intercepted)
+Direct URL → Full page renders
+Refresh while modal open → Full page renders

.agents/skills/next-best-practices/route-handlers.md

@@ -0,0 +1,146 @@
+# Route Handlers
+
+Create API endpoints with `route.ts` files.
+
+## Basic Usage
+
+```tsx
+// app/api/users/route.ts
+export async function GET() {
+  const users = await getUsers()
+  return Response.json(users)
+}
+
+export async function POST(request: Request) {
+  const body = await request.json()
+  const user = await createUser(body)
+  return Response.json(user, { status: 201 })
+}
+```
+
+## Supported Methods
+
+`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
+
+## GET Handler Conflicts with page.tsx
+
+**A `route.ts` and `page.tsx` cannot coexist in the same folder.**
+
+```
+app/
+├── api/
+│   └── users/
+│       └── route.ts    # /api/users
+└── users/
+    ├── page.tsx        # /users (page)
+    └── route.ts        # Warning: Conflicts with page.tsx!
+```
+
+If you need both a page and an API at the same path, use different paths:
+
+```
+app/
+├── users/
+│   └── page.tsx        # /users (page)
+└── api/
+    └── users/
+        └── route.ts    # /api/users (API)
+```
+
+## Environment Behavior
+
+Route handlers run in a **Server Component-like environment**:
+
+- Yes: Can use `async/await`
+- Yes: Can access `cookies()`, `headers()`
+- Yes: Can use Node.js APIs
+- No: Cannot use React hooks
+- No: Cannot use React DOM APIs
+- No: Cannot use browser APIs
+
+```tsx
+// Bad: This won't work - no React DOM in route handlers
+import { renderToString } from 'react-dom/server'
+
+export async function GET() {
+  const html = renderToString(<Component />)  // Error!
+  return new Response(html)
+}
+```
+
+## Dynamic Route Handlers
+
+```tsx
+// app/api/users/[id]/route.ts
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params
+  const user = await getUser(id)
+
+  if (!user) {
+    return Response.json({ error: 'Not found' }, { status: 404 })
+  }
+
+  return Response.json(user)
+}
+```
+
+## Request Helpers
+
+```tsx
+export async function GET(request: Request) {
+  // URL and search params
+  const { searchParams } = new URL(request.url)
+  const query = searchParams.get('q')
+
+  // Headers
+  const authHeader = request.headers.get('authorization')
+
+  // Cookies (Next.js helper)
+  const cookieStore = await cookies()
+  const token = cookieStore.get('token')
+
+  return Response.json({ query, token })
+}
+```
+
+## Response Helpers
+
+```tsx
+// JSON response
+return Response.json({ data })
+
+// With status
+return Response.json({ error: 'Not found' }, { status: 404 })
+
+// With headers
+return Response.json(data, {
+  headers: {
+    'Cache-Control': 'max-age=3600',
+  },
+})
+
+// Redirect
+return Response.redirect(new URL('/login', request.url))
+
+// Stream
+return new Response(stream, {
+  headers: { 'Content-Type': 'text/event-stream' },
+})
+```
+
+## When to Use Route Handlers vs Server Actions
+
+| Use Case | Route Handlers | Server Actions |
+|----------|----------------|----------------|
+| Form submissions | No | Yes |
+| Data mutations from UI | No | Yes |
+| Third-party webhooks | Yes | No |
+| External API consumption | Yes | No |
+| Public REST API | Yes | No |
+| File uploads | Both work | Both work |
+
+**Prefer Server Actions** for mutations triggered from your UI.
+**Use Route Handlers** for external integrations and public APIs.

.agents/skills/next-best-practices/rsc-boundaries.md

@@ -0,0 +1,159 @@
+# RSC Boundaries
+
+Detect and prevent invalid patterns when crossing Server/Client component boundaries.
+
+## Detection Rules
+
+### 1. Async Client Components Are Invalid
+
+Client components **cannot** be async functions. Only Server Components can be async.
+
+**Detect:** File has `'use client'` AND component is `async function` or returns `Promise`
+
+```tsx
+// Bad: async client component
+'use client'
+export default async function UserProfile() {
+  const user = await getUser() // Cannot await in client component
+  return <div>{user.name}</div>
+}
+
+// Good: Remove async, fetch data in parent server component
+// page.tsx (server component - no 'use client')
+export default async function Page() {
+  const user = await getUser()
+  return <UserProfile user={user} />
+}
+
+// UserProfile.tsx (client component)
+'use client'
+export function UserProfile({ user }: { user: User }) {
+  return <div>{user.name}</div>
+}
+```
+
+```tsx
+// Bad: async arrow function client component
+'use client'
+const Dashboard = async () => {
+  const data = await fetchDashboard()
+  return <div>{data}</div>
+}
+
+// Good: Fetch in server component, pass data down
+```
+
+### 2. Non-Serializable Props to Client Components
+
+Props passed from Server → Client must be JSON-serializable.
+
+**Detect:** Server component passes these to a client component:
+- Functions (except Server Actions with `'use server'`)
+- `Date` objects
+- `Map`, `Set`, `WeakMap`, `WeakSet`
+- Class instances
+- `Symbol` (unless globally registered)
+- Circular references
+
+```tsx
+// Bad: Function prop
+// page.tsx (server)
+export default function Page() {
+  const handleClick = () => console.log('clicked')
+  return <ClientButton onClick={handleClick} />
+}
+
+// Good: Define function inside client component
+// ClientButton.tsx
+'use client'
+export function ClientButton() {
+  const handleClick = () => console.log('clicked')
+  return <button onClick={handleClick}>Click</button>
+}
+```
+
+```tsx
+// Bad: Date object (silently becomes string, then crashes)
+// page.tsx (server)
+export default async function Page() {
+  const post = await getPost()
+  return <PostCard createdAt={post.createdAt} /> // Date object
+}
+
+// PostCard.tsx (client) - will crash on .getFullYear()
+'use client'
+export function PostCard({ createdAt }: { createdAt: Date }) {
+  return <span>{createdAt.getFullYear()}</span> // Runtime error!
+}
+
+// Good: Serialize to string on server
+// page.tsx (server)
+export default async function Page() {
+  const post = await getPost()
+  return <PostCard createdAt={post.createdAt.toISOString()} />
+}
+
+// PostCard.tsx (client)
+'use client'
+export function PostCard({ createdAt }: { createdAt: string }) {
+  const date = new Date(createdAt)
+  return <span>{date.getFullYear()}</span>
+}
+```
+
+```tsx
+// Bad: Class instance
+const user = new UserModel(data)
+<ClientProfile user={user} /> // Methods will be stripped
+
+// Good: Pass plain object
+const user = await getUser()
+<ClientProfile user={{ id: user.id, name: user.name }} />
+```
+
+```tsx
+// Bad: Map/Set
+<ClientComponent items={new Map([['a', 1]])} />
+
+// Good: Convert to array/object
+<ClientComponent items={Object.fromEntries(map)} />
+<ClientComponent items={Array.from(set)} />
+```
+
+### 3. Server Actions Are the Exception
+
+Functions marked with `'use server'` CAN be passed to client components.
+
+```tsx
+// Valid: Server Action can be passed
+// actions.ts
+'use server'
+export async function submitForm(formData: FormData) {
+  // server-side logic
+}
+
+// page.tsx (server)
+import { submitForm } from './actions'
+export default function Page() {
+  return <ClientForm onSubmit={submitForm} /> // OK!
+}
+
+// ClientForm.tsx (client)
+'use client'
+export function ClientForm({ onSubmit }: { onSubmit: (data: FormData) => Promise<void> }) {
+  return <form action={onSubmit}>...</form>
+}
+```
+
+## Quick Reference
+
+| Pattern | Valid? | Fix |
+|---------|--------|-----|
+| `'use client'` + `async function` | No | Fetch in server parent, pass data |
+| Pass `() => {}` to client | No | Define in client or use server action |
+| Pass `new Date()` to client | No | Use `.toISOString()` |
+| Pass `new Map()` to client | No | Convert to object/array |
+| Pass class instance to client | No | Pass plain object |
+| Pass server action to client | Yes | - |
+| Pass `string/number/boolean` | Yes | - |
+| Pass plain object/array | Yes | - |

.agents/skills/next-best-practices/runtime-selection.md

@@ -0,0 +1,39 @@
+# Runtime Selection
+
+## Use Node.js Runtime by Default
+
+Use the default Node.js runtime for new routes and pages. Only use Edge runtime if the project already uses it or there's a specific requirement.
+
+```tsx
+// Good: Default - no runtime config needed (uses Node.js)
+export default function Page() { ... }
+
+// Caution: Only if already used in project or specifically required
+export const runtime = 'edge'
+```
+
+## When to Use Each
+
+### Node.js Runtime (Default)
+
+- Full Node.js API support
+- File system access (`fs`)
+- Full `crypto` support
+- Database connections
+- Most npm packages work
+
+### Edge Runtime
+
+- Only for specific edge-location latency requirements
+- Limited API (no `fs`, limited `crypto`)
+- Smaller cold start
+- Geographic distribution needs
+
+## Detection
+
+**Before adding `runtime = 'edge'`**, check:
+1. Does the project already use Edge runtime?
+2. Is there a specific latency requirement?
+3. Are all dependencies Edge-compatible?
+
+If unsure, use Node.js runtime.

.agents/skills/next-best-practices/scripts.md

@@ -0,0 +1,141 @@
+# Scripts
+
+Loading third-party scripts in Next.js.
+
+## Use next/script
+
+Always use `next/script` instead of native `<script>` tags for better performance.
+
+```tsx
+// Bad: Native script tag
+<script src="https://example.com/script.js"></script>
+
+// Good: Next.js Script component
+import Script from 'next/script'
+
+<Script src="https://example.com/script.js" />
+```
+
+## Inline Scripts Need ID
+
+Inline scripts require an `id` attribute for Next.js to track them.
+
+```tsx
+// Bad: Missing id
+<Script dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
+
+// Good: Has id
+<Script id="my-script" dangerouslySetInnerHTML={{ __html: 'console.log("hi")' }} />
+
+// Good: Inline with id
+<Script id="show-banner">
+  {`document.getElementById('banner').classList.remove('hidden')`}
+</Script>
+```
+
+## Don't Put Script in Head
+
+`next/script` should not be placed inside `next/head`. It handles its own positioning.
+
+```tsx
+// Bad: Script inside Head
+import Head from 'next/head'
+import Script from 'next/script'
+
+<Head>
+  <Script src="/analytics.js" />
+</Head>
+
+// Good: Script outside Head
+<Head>
+  <title>Page</title>
+</Head>
+<Script src="/analytics.js" />
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+<Script src="/analytics.js" strategy="afterInteractive" />
+
+// lazyOnload - Load during idle time
+<Script src="/widget.js" strategy="lazyOnload" />
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+<Script src="/critical.js" strategy="beforeInteractive" />
+
+// worker - Load in web worker (experimental)
+<Script src="/heavy.js" strategy="worker" />
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+<Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" />
+<Script id="ga-init">
+  {`window.dataLayer = window.dataLayer || [];
+    function gtag(){dataLayer.push(arguments);}
+    gtag('js', new Date());
+    gtag('config', 'G-XXXXX');`}
+</Script>
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+  return (
+    <html>
+      <body>{children}</body>
+      <GoogleAnalytics gaId="G-XXXXX" />
+    </html>
+  )
+}
+```
+
+## Google Tag Manager
+
+```tsx
+import { GoogleTagManager } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+  return (
+    <html>
+      <GoogleTagManager gtmId="GTM-XXXXX" />
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+## Other Third-Party Scripts
+
+```tsx
+// YouTube embed
+import { YouTubeEmbed } from '@next/third-parties/google'
+
+<YouTubeEmbed videoid="dQw4w9WgXcQ" />
+
+// Google Maps
+import { GoogleMapsEmbed } from '@next/third-parties/google'
+
+<GoogleMapsEmbed
+  apiKey="YOUR_API_KEY"
+  mode="place"
+  q="Brooklyn+Bridge,New+York,NY"
+/>
+```
+
+## Quick Reference
+
+| Pattern | Issue | Fix |
+|---------|-------|-----|
+| `<script src="...">` | No optimization | Use `next/script` |
+| `<Script>` without id | Can't track inline scripts | Add `id` attribute |
+| `<Script>` inside `<Head>` | Wrong placement | Move outside Head |
+| Inline GA/GTM scripts | No optimization | Use `@next/third-parties` |
+| `strategy="beforeInteractive"` outside layout | Won't work | Only use in root layout |

.agents/skills/next-best-practices/self-hosting.md

@@ -0,0 +1,371 @@
+# Self-Hosting Next.js
+
+Deploy Next.js outside of Vercel with confidence.
+
+## Quick Start: Standalone Output
+
+For Docker or any containerized deployment, use standalone output:
+
+```js
+// next.config.js
+module.exports = {
+  output: 'standalone',
+};
+```
+
+This creates a minimal `standalone` folder with only production dependencies:
+
+```
+.next/
+├── standalone/
+│   ├── server.js          # Entry point
+│   ├── node_modules/      # Only production deps
+│   └── .next/             # Build output
+└── static/                # Must be copied separately
+```
+
+## Docker Deployment
+
+### Dockerfile
+
+```dockerfile
+FROM node:20-alpine AS base
+
+# Install dependencies
+FROM base AS deps
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm ci
+
+# Build
+FROM base AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+# Production
+FROM base AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+# Create non-root user
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+# Copy standalone output
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]
+```
+
+### Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+  web:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/api/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+## PM2 Deployment
+
+For traditional server deployments:
+
+```js
+// ecosystem.config.js
+module.exports = {
+  apps: [{
+    name: 'nextjs',
+    script: '.next/standalone/server.js',
+    instances: 'max',
+    exec_mode: 'cluster',
+    env: {
+      NODE_ENV: 'production',
+      PORT: 3000,
+    },
+  }],
+};
+```
+
+```bash
+npm run build
+pm2 start ecosystem.config.js
+```
+
+## ISR and Cache Handlers
+
+### The Problem
+
+ISR (Incremental Static Regeneration) uses filesystem caching by default. This **breaks with multiple instances**:
+
+- Instance A regenerates page → saves to its local disk
+- Instance B serves stale page → doesn't see Instance A's cache
+- Load balancer sends users to random instances → inconsistent content
+
+### Solution: Custom Cache Handler
+
+Next.js 14+ supports custom cache handlers for shared storage:
+
+```js
+// next.config.js
+module.exports = {
+  cacheHandler: require.resolve('./cache-handler.js'),
+  cacheMaxMemorySize: 0, // Disable in-memory cache
+};
+```
+
+#### Redis Cache Handler Example
+
+```js
+// cache-handler.js
+const Redis = require('ioredis');
+
+const redis = new Redis(process.env.REDIS_URL);
+const CACHE_PREFIX = 'nextjs:';
+
+module.exports = class CacheHandler {
+  constructor(options) {
+    this.options = options;
+  }
+
+  async get(key) {
+    const data = await redis.get(CACHE_PREFIX + key);
+    if (!data) return null;
+
+    const parsed = JSON.parse(data);
+    return {
+      value: parsed.value,
+      lastModified: parsed.lastModified,
+    };
+  }
+
+  async set(key, data, ctx) {
+    const cacheData = {
+      value: data,
+      lastModified: Date.now(),
+    };
+
+    // Set TTL based on revalidate option
+    if (ctx?.revalidate) {
+      await redis.setex(
+        CACHE_PREFIX + key,
+        ctx.revalidate,
+        JSON.stringify(cacheData)
+      );
+    } else {
+      await redis.set(CACHE_PREFIX + key, JSON.stringify(cacheData));
+    }
+  }
+
+  async revalidateTag(tags) {
+    // Implement tag-based invalidation
+    // This requires tracking which keys have which tags
+  }
+};
+```
+
+#### S3 Cache Handler Example
+
+```js
+// cache-handler.js
+const { S3Client, GetObjectCommand, PutObjectCommand } = require('@aws-sdk/client-s3');
+
+const s3 = new S3Client({ region: process.env.AWS_REGION });
+const BUCKET = process.env.CACHE_BUCKET;
+
+module.exports = class CacheHandler {
+  async get(key) {
+    try {
+      const response = await s3.send(new GetObjectCommand({
+        Bucket: BUCKET,
+        Key: `cache/${key}`,
+      }));
+      const body = await response.Body.transformToString();
+      return JSON.parse(body);
+    } catch (err) {
+      if (err.name === 'NoSuchKey') return null;
+      throw err;
+    }
+  }
+
+  async set(key, data, ctx) {
+    await s3.send(new PutObjectCommand({
+      Bucket: BUCKET,
+      Key: `cache/${key}`,
+      Body: JSON.stringify({
+        value: data,
+        lastModified: Date.now(),
+      }),
+      ContentType: 'application/json',
+    }));
+  }
+};
+```
+
+## What Works vs What Needs Setup
+
+| Feature | Single Instance | Multi-Instance | Notes |
+|---------|----------------|----------------|-------|
+| SSR | Yes | Yes | No special setup |
+| SSG | Yes | Yes | Built at deploy time |
+| ISR | Yes | Needs cache handler | Filesystem cache breaks |
+| Image Optimization | Yes | Yes | CPU-intensive, consider CDN |
+| Middleware | Yes | Yes | Runs on Node.js |
+| Edge Runtime | Limited | Limited | Some features Node-only |
+| `revalidatePath/Tag` | Yes | Needs cache handler | Must share cache |
+| `next/font` | Yes | Yes | Fonts bundled at build |
+| Draft Mode | Yes | Yes | Cookie-based |
+
+## Image Optimization
+
+Next.js Image Optimization works out of the box but is CPU-intensive.
+
+### Option 1: Built-in (Simple)
+
+Works automatically, but consider:
+- Set `deviceSizes` and `imageSizes` in config to limit variants
+- Use `minimumCacheTTL` to reduce regeneration
+
+```js
+// next.config.js
+module.exports = {
+  images: {
+    minimumCacheTTL: 60 * 60 * 24, // 24 hours
+    deviceSizes: [640, 750, 1080, 1920], // Limit sizes
+  },
+};
+```
+
+### Option 2: External Loader (Recommended for Scale)
+
+Offload to Cloudinary, Imgix, or similar:
+
+```js
+// next.config.js
+module.exports = {
+  images: {
+    loader: 'custom',
+    loaderFile: './lib/image-loader.js',
+  },
+};
+```
+
+```js
+// lib/image-loader.js
+export default function cloudinaryLoader({ src, width, quality }) {
+  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`];
+  return `https://res.cloudinary.com/demo/image/upload/${params.join(',')}${src}`;
+}
+```
+
+## Environment Variables
+
+### Build-time vs Runtime
+
+```js
+// Available at build time only (baked into bundle)
+NEXT_PUBLIC_API_URL=https://api.example.com
+
+// Available at runtime (server-side only)
+DATABASE_URL=postgresql://...
+API_SECRET=...
+```
+
+### Runtime Configuration
+
+For truly dynamic config, don't use `NEXT_PUBLIC_*`. Instead:
+
+```tsx
+// app/api/config/route.ts
+export async function GET() {
+  return Response.json({
+    apiUrl: process.env.API_URL,
+    features: process.env.FEATURES?.split(','),
+  });
+}
+```
+
+## OpenNext: Serverless Without Vercel
+
+[OpenNext](https://open-next.js.org/) adapts Next.js for AWS Lambda, Cloudflare Workers, etc.
+
+```bash
+npx create-sst@latest
+# or
+npx @opennextjs/aws build
+```
+
+Supports:
+- AWS Lambda + CloudFront
+- Cloudflare Workers
+- Netlify Functions
+- Deno Deploy
+
+## Health Check Endpoint
+
+Always include a health check for load balancers:
+
+```tsx
+// app/api/health/route.ts
+export async function GET() {
+  try {
+    // Optional: check database connection
+    // await db.$queryRaw`SELECT 1`;
+
+    return Response.json({ status: 'healthy' }, { status: 200 });
+  } catch (error) {
+    return Response.json({ status: 'unhealthy' }, { status: 503 });
+  }
+}
+```
+
+## Pre-Deployment Checklist
+
+1. **Build locally first**: `npm run build` - catch errors before deploy
+2. **Test standalone output**: `node .next/standalone/server.js`
+3. **Set `output: 'standalone'`** for Docker
+4. **Configure cache handler** for multi-instance ISR
+5. **Set `HOSTNAME="0.0.0.0"`** for containers
+6. **Copy `public/` and `.next/static/`** - not included in standalone
+7. **Add health check endpoint**
+8. **Test ISR revalidation** after deployment
+9. **Monitor memory usage** - Node.js defaults may need tuning
+
+## Testing Cache Handler
+
+**Critical**: Test your cache handler on every Next.js upgrade:
+
+```bash
+# Start multiple instances
+PORT=3001 node .next/standalone/server.js &
+PORT=3002 node .next/standalone/server.js &
+
+# Trigger ISR revalidation
+curl http://localhost:3001/api/revalidate?path=/posts
+
+# Verify both instances see the update
+curl http://localhost:3001/posts
+curl http://localhost:3002/posts
+# Should return identical content
+```

.agents/skills/next-best-practices/suspense-boundaries.md

@@ -0,0 +1,67 @@
+# Suspense Boundaries
+
+Client hooks that cause CSR bailout without Suspense boundaries.
+
+## useSearchParams
+
+Always requires Suspense boundary in static routes. Without it, the entire page becomes client-side rendered.
+
+```tsx
+// Bad: Entire page becomes CSR
+'use client'
+
+import { useSearchParams } from 'next/navigation'
+
+export default function SearchBar() {
+  const searchParams = useSearchParams()
+  return <div>Query: {searchParams.get('q')}</div>
+}
+```
+
+```tsx
+// Good: Wrap in Suspense
+import { Suspense } from 'react'
+import SearchBar from './search-bar'
+
+export default function Page() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <SearchBar />
+    </Suspense>
+  )
+}
+```
+
+## usePathname
+
+Requires Suspense boundary when route has dynamic parameters.
+
+```tsx
+// In dynamic route [slug]
+// Bad: No Suspense
+'use client'
+import { usePathname } from 'next/navigation'
+
+export function Breadcrumb() {
+  const pathname = usePathname()
+  return <nav>{pathname}</nav>
+}
+```
+
+```tsx
+// Good: Wrap in Suspense
+<Suspense fallback={<BreadcrumbSkeleton />}>
+  <Breadcrumb />
+</Suspense>
+```
+
+If you use `generateStaticParams`, Suspense is optional.
+
+## Quick Reference
+
+| Hook | Suspense Required |
+|------|-------------------|
+| `useSearchParams()` | Yes |
+| `usePathname()` | Yes (dynamic routes) |
+| `useParams()` | No |
+| `useRouter()` | No |

.agents/skills/vercel-react-best-practices/README.md

@@ -0,0 +1,123 @@
+# React Best Practices
+
+A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `src/` - Build scripts and utilities
+- `metadata.json` - Document metadata (version, organization, abstract)
+- __`AGENTS.md`__ - Compiled output (generated)
+- __`test-cases.json`__ - Test cases for LLM evaluation (generated)
+
+## Getting Started
+
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+2. Build AGENTS.md from rules:
+   ```bash
+   pnpm build
+   ```
+
+3. Validate rule files:
+   ```bash
+   pnpm validate
+   ```
+
+4. Extract test cases:
+   ```bash
+   pnpm extract-tests
+   ```
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `async-` for Eliminating Waterfalls (Section 1)
+   - `bundle-` for Bundle Size Optimization (Section 2)
+   - `server-` for Server-Side Performance (Section 3)
+   - `client-` for Client-Side Data Fetching (Section 4)
+   - `rerender-` for Re-render Optimization (Section 5)
+   - `rendering-` for Rendering Performance (Section 6)
+   - `js-` for JavaScript Performance (Section 7)
+   - `advanced-` for Advanced Patterns (Section 8)
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+```markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example
+```
+
+Optional explanatory text after examples.
+
+Reference: [Link](https://example.com)
+
+## File Naming Convention
+
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `async-parallel.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+- IDs (e.g., 1.1, 1.2) are auto-generated during build
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, major performance gains
+- `HIGH` - Significant performance improvements
+- `MEDIUM-HIGH` - Moderate-high gains
+- `MEDIUM` - Moderate performance improvements
+- `LOW-MEDIUM` - Low-medium gains
+- `LOW` - Incremental improvements
+
+## Scripts
+
+- `pnpm build` - Compile rules into AGENTS.md
+- `pnpm validate` - Validate all rule files
+- `pnpm extract-tests` - Extract test cases for LLM evaluation
+- `pnpm dev` - Build and validate
+
+## Contributing
+
+When adding or modifying rules:
+
+1. Use the correct filename prefix for your section
+2. Follow the `_template.md` structure
+3. Include clear bad/good examples with explanations
+4. Add appropriate tags
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+6. Rules are automatically sorted by title - no need to manage numbers!
+
+## Acknowledgments
+
+Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).

.agents/skills/vercel-react-best-practices/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-analyzable-paths` - Prefer statically analyzable import and file-system paths to avoid broad bundles and traces
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level
+- `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-parallel-nested-fetching` - Chain nested fetches per item in Promise.all
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-split-combined-hooks` - Split hooks with independent dependencies
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+- `rerender-no-inline-components` - Don't define components inside components
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+- `rendering-resource-hints` - Use React DOM resource hints for preloading
+- `rendering-script-defer-async` - Use defer or async on script tags
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+- `js-flatmap-filter` - Use flatMap to map and filter in one pass
+- `js-request-idle-callback` - Defer non-critical work to browser idle time
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

.agents/skills/vercel-react-best-practices/rules/_sections.md

@@ -0,0 +1,46 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Eliminating Waterfalls (async)
+
+**Impact:** CRITICAL  
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+## 2. Bundle Size Optimization (bundle)
+
+**Impact:** CRITICAL  
+**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+## 3. Server-Side Performance (server)
+
+**Impact:** HIGH  
+**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+## 4. Client-Side Data Fetching (client)
+
+**Impact:** MEDIUM-HIGH  
+**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+## 5. Re-render Optimization (rerender)
+
+**Impact:** MEDIUM  
+**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+## 6. Rendering Performance (rendering)
+
+**Impact:** MEDIUM  
+**Description:** Optimizing the rendering process reduces the work the browser needs to do.
+
+## 7. JavaScript Performance (js)
+
+**Impact:** LOW-MEDIUM  
+**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
+
+## 8. Advanced Patterns (advanced)
+
+**Impact:** LOW  
+**Description:** Advanced patterns for specific cases that require careful implementation.

.agents/skills/vercel-react-best-practices/rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)

.agents/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md

@@ -0,0 +1,56 @@
+---
+title: Do Not Put Effect Events in Dependency Arrays
+impact: LOW
+impactDescription: avoids unnecessary effect re-runs and lint errors
+tags: advanced, hooks, useEffectEvent, dependencies, effects
+---
+
+## Do Not Put Effect Events in Dependency Arrays
+
+Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.
+
+**Incorrect (Effect Event added as a dependency):**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId, handleConnected])
+}
+```
+
+Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.
+
+**Correct (depend on reactive values, not the Effect Event):**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId])
+}
+```
+
+Reference: [React useEffectEvent: Effect Event in deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)

.agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md

@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

.agents/skills/vercel-react-best-practices/rules/advanced-init-once.md

@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)

.agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md

@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```

.agents/skills/vercel-react-best-practices/rules/async-api-routes.md

@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).

.agents/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md

@@ -0,0 +1,37 @@
+---
+title: Check Cheap Conditions Before Async Flags
+impact: HIGH
+impactDescription: avoids unnecessary async work when a synchronous guard already fails
+tags: async, await, feature-flags, short-circuit, conditional
+---
+
+## Check Cheap Conditions Before Async Flags
+
+When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
+
+This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+
+**Incorrect:**
+
+```typescript
+const someFlag = await getFlag()
+
+if (someFlag && someCondition) {
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+if (someCondition) {
+  const someFlag = await getFlag()
+  if (someFlag) {
+    // ...
+  }
+}
+```
+
+This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.
+
+Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.

.agents/skills/vercel-react-best-practices/rules/async-defer-await.md

@@ -0,0 +1,82 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).

.agents/skills/vercel-react-best-practices/rules/async-dependencies.md

@@ -0,0 +1,51 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)

.agents/skills/vercel-react-best-practices/rules/async-parallel.md

@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```

.agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md

@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.

.agents/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md

@@ -0,0 +1,63 @@
+---
+title: Prefer Statically Analyzable Paths
+impact: HIGH
+impactDescription: avoids accidental broad bundles and file traces
+tags: bundle, nextjs, vite, webpack, rollup, esbuild, path
+---
+
+## Prefer Statically Analyzable Paths
+
+Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.
+
+Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.
+
+When analysis becomes too broad, the cost is real:
+- Larger server bundles
+- Slower builds
+- Worse cold starts
+- More memory use
+
+### Import Paths
+
+**Incorrect (the bundler cannot tell what may be imported):**
+
+```ts
+const PAGE_MODULES = {
+  home: './pages/home',
+  settings: './pages/settings',
+} as const
+
+const Page = await import(PAGE_MODULES[pageName])
+```
+
+**Correct (use an explicit map of allowed modules):**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import('./pages/home'),
+  settings: () => import('./pages/settings'),
+} as const
+
+const Page = await PAGE_MODULES[pageName]()
+```
+
+### File-System Paths
+
+**Incorrect (a 2-value enum still hides the final path from static analysis):**
+
+```ts
+const baseDir = path.join(process.cwd(), 'content/' + contentKind)
+```
+
+**Correct (make each final path literal at the callsite):**
+
+```ts
+const baseDir =
+  kind === ContentKind.Blog
+    ? path.join(process.cwd(), 'content/blog')
+    : path.join(process.cwd(), 'content/docs')
+```
+
+In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.
+
+Reference: [Next.js output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [Next.js dynamic imports](https://nextjs.org/learn/seo/dynamic-imports), [Vite features](https://vite.dev/guide/features.html), [esbuild API](https://esbuild.github.io/api/), [Rollup dynamic import vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [Webpack dependency management](https://webpack.js.org/guides/dependency-management/)

.agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md

@@ -0,0 +1,60 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct - Next.js 13.5+ (recommended):**
+
+```js
+// next.config.js - automatically optimizes barrel imports at build time
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+```
+
+```tsx
+// Keep the standard imports - Next.js transforms them to direct imports
+import { Check, X, Menu } from 'lucide-react'
+// Full TypeScript support, no manual path wrangling
+```
+
+This is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.
+
+**Correct - Direct imports (non-Next.js projects):**
+
+```tsx
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+> **TypeScript warning:** Some libraries (notably `lucide-react`) don't ship `.d.ts` files for their deep import paths. Importing from `lucide-react/dist/esm/icons/check` resolves to an implicit `any` type, causing errors under `strict` or `noImplicitAny`. Prefer `optimizePackageImports` when available, or verify the library exports types for its subpaths before using direct imports.
+
+These optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)

.agents/skills/vercel-react-best-practices/rules/bundle-conditional.md

@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.

.agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md

@@ -0,0 +1,49 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: loads after hydration
+tags: bundle, third-party, analytics, defer
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct (loads after hydration):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```

.agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md

@@ -0,0 +1,35 @@
+---
+title: Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: directly affects TTI and LCP
+tags: bundle, dynamic-import, code-splitting, next-dynamic
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```

.agents/skills/vercel-react-best-practices/rules/bundle-preload.md

@@ -0,0 +1,50 @@
+---
+title: Preload Based on User Intent
+impact: MEDIUM
+impactDescription: reduces perceived latency
+tags: bundle, preload, user-intent, hover
+---
+
+## Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example (preload on hover/focus):**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example (preload when feature flag is enabled):**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.

.agents/skills/vercel-react-best-practices/rules/client-event-listeners.md

@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```

.agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md

@@ -0,0 +1,71 @@
+---
+title: Version and Minimize localStorage Data
+impact: MEDIUM
+impactDescription: prevents schema conflicts, reduces storage size
+tags: client, localStorage, storage, versioning, data-minimization
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.

.agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md

@@ -0,0 +1,48 @@
+---
+title: Use Passive Event Listeners for Scrolling Performance
+impact: MEDIUM
+impactDescription: eliminates scroll delay caused by event listeners
+tags: client, event-listeners, scrolling, performance, touch, wheel
+---
+
+## Use Passive Event Listeners for Scrolling Performance
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.

.agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md

@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)

.agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md

@@ -0,0 +1,107 @@
+---
+title: Avoid Layout Thrashing
+impact: MEDIUM
+impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
+tags: javascript, dom, css, performance, reflow, layout-thrashing
+---
+
+## Avoid Layout Thrashing
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK (browser batches style changes):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect (interleaved reads and writes force reflows):**
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct (batch writes, then read once):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct (batch reads, then writes):**
+```typescript
+function avoidThrashing(element: HTMLElement) {
+  // Read phase - all layout queries first
+  const rect1 = element.getBoundingClientRect()
+  const offsetWidth = element.offsetWidth
+  const offsetHeight = element.offsetHeight
+  
+  // Write phase - all style changes after
+  element.style.width = '100px'
+  element.style.height = '200px'
+}
+```
+
+**Better: use CSS classes**
+```css
+.highlighted-box {
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+  border: 1px solid black;
+}
+```
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**React example:**
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.

.agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md

@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)

.agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md

@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+
+## Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+**Incorrect (3 lookups × N iterations):**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct (1 lookup total):**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```

.agents/skills/vercel-react-best-practices/rules/js-cache-storage.md

@@ -0,0 +1,70 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important (invalidate on external changes):**
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```

.agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md

@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct (1 iteration):**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```

.agents/skills/vercel-react-best-practices/rules/js-early-exit.md

@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+
+## Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect (processes all items even after finding answer):**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct (returns immediately on first error):**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```

.agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md

@@ -0,0 +1,60 @@
+---
+title: Use flatMap to Map and Filter in One Pass
+impact: LOW-MEDIUM
+impactDescription: eliminates intermediate array
+tags: javascript, arrays, flatMap, filter, performance
+---
+
+## Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect (2 iterations, intermediate array):**
+
+```typescript
+const userNames = users
+  .map(user => user.isActive ? user.name : null)
+  .filter(Boolean)
+```
+
+**Correct (1 iteration, no intermediate array):**
+
+```typescript
+const userNames = users.flatMap(user =>
+  user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+  .map(r => r.success ? r.data.email : null)
+  .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+  r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+  .map(s => parseInt(s, 10))
+  .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+  const n = parseInt(s, 10)
+  return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+- Transforming items while filtering some out
+- Conditional mapping where some inputs produce no output
+- Parsing/validating where invalid inputs should be skipped

.agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md

@@ -0,0 +1,45 @@
+---
+title: Hoist RegExp Creation
+impact: LOW-MEDIUM
+impactDescription: avoids recreation
+tags: javascript, regexp, optimization, memoization
+---
+
+## Hoist RegExp Creation
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect (new RegExp every render):**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct (memoize or hoist):**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning (global regex has mutable state):**
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```

.agents/skills/vercel-react-best-practices/rules/js-index-maps.md

@@ -0,0 +1,37 @@
+---
+title: Build Index Maps for Repeated Lookups
+impact: LOW-MEDIUM
+impactDescription: 1M ops to 2K ops
+tags: javascript, map, indexing, optimization, performance
+---
+
+## Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+For 1000 orders × 1000 users: 1M ops → 2K ops.

.agents/skills/vercel-react-best-practices/rules/js-length-check-first.md

@@ -0,0 +1,49 @@
+---
+title: Early Length Check for Array Comparisons
+impact: MEDIUM-HIGH
+impactDescription: avoids expensive operations when lengths differ
+tags: javascript, arrays, performance, optimization, comparison
+---
+
+## Early Length Check for Array Comparisons
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect (always runs expensive comparison):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+- It avoids mutating the original arrays
+- It returns early when a difference is found

.agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md

@@ -0,0 +1,82 @@
+---
+title: Use Loop for Min/Max Instead of Sort
+impact: LOW
+impactDescription: O(n) instead of O(n log n)
+tags: javascript, arrays, performance, sorting, algorithms
+---
+
+## Use Loop for Min/Max Instead of Sort
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative (Math.min/Math.max for small arrays):**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.

.agents/skills/vercel-react-best-practices/rules/js-request-idle-callback.md

@@ -0,0 +1,105 @@
+---
+title: Defer Non-Critical Work with requestIdleCallback
+impact: MEDIUM
+impactDescription: keeps UI responsive during background tasks
+tags: javascript, performance, idle, scheduling, analytics
+---
+
+## Defer Non-Critical Work with requestIdleCallback
+
+**Impact: MEDIUM (keeps UI responsive during background tasks)**
+
+Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.
+
+**Incorrect (blocks main thread during user interaction):**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // These block the main thread immediately
+  analytics.track('search', { query })
+  saveToRecentSearches(query)
+  prefetchTopResults(results.slice(0, 3))
+}
+```
+
+**Correct (defers non-critical work to idle time):**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // Defer non-critical work to idle periods
+  requestIdleCallback(() => {
+    analytics.track('search', { query })
+  })
+
+  requestIdleCallback(() => {
+    saveToRecentSearches(query)
+  })
+
+  requestIdleCallback(() => {
+    prefetchTopResults(results.slice(0, 3))
+  })
+}
+```
+
+**With timeout for required work:**
+
+```typescript
+// Ensure analytics fires within 2 seconds even if browser stays busy
+requestIdleCallback(
+  () => analytics.track('page_view', { path: location.pathname }),
+  { timeout: 2000 }
+)
+```
+
+**Chunking large tasks:**
+
+```typescript
+function processLargeDataset(items: Item[]) {
+  let index = 0
+
+  function processChunk(deadline: IdleDeadline) {
+    // Process items while we have idle time (aim for <50ms chunks)
+    while (index < items.length && deadline.timeRemaining() > 0) {
+      processItem(items[index])
+      index++
+    }
+
+    // Schedule next chunk if more items remain
+    if (index < items.length) {
+      requestIdleCallback(processChunk)
+    }
+  }
+
+  requestIdleCallback(processChunk)
+}
+```
+
+**With fallback for unsupported browsers:**
+
+```typescript
+const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))
+
+scheduleIdleWork(() => {
+  // Non-critical work
+})
+```
+
+**When to use:**
+
+- Analytics and telemetry
+- Saving state to localStorage/IndexedDB
+- Prefetching resources for likely next actions
+- Processing non-urgent data transformations
+- Lazy initialization of non-critical features
+
+**When NOT to use:**
+
+- User-initiated actions that need immediate feedback
+- Rendering updates the user is waiting for
+- Time-sensitive operations

.agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md

@@ -0,0 +1,24 @@
+---
+title: Use Set/Map for O(1) Lookups
+impact: LOW-MEDIUM
+impactDescription: O(n) to O(1)
+tags: javascript, set, map, data-structures, performance
+---
+
+## Use Set/Map for O(1) Lookups
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```

.agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md

@@ -0,0 +1,57 @@
+---
+title: Use toSorted() Instead of sort() for Immutability
+impact: MEDIUM-HIGH
+impactDescription: prevents mutation bugs in React state
+tags: javascript, arrays, immutability, react, state, mutation
+---
+
+## Use toSorted() Instead of sort() for Immutability
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect (mutates original array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct (creates new array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support (fallback for older browsers):**
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+- `.toReversed()` - immutable reverse
+- `.toSpliced()` - immutable splice
+- `.with()` - immutable element replacement

.agents/skills/vercel-react-best-practices/rules/rendering-activity.md

@@ -0,0 +1,26 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM
+tags: rendering, activity, visibility, state-preservation
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.

.agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md

@@ -0,0 +1,47 @@
+---
+title: Animate SVG Wrapper Instead of SVG Element
+impact: LOW
+impactDescription: enables hardware acceleration
+tags: rendering, svg, css, animation, performance
+---
+
+## Animate SVG Wrapper Instead of SVG Element
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.

.agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md

@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```

.agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md

@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).

.agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md

@@ -0,0 +1,46 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, optimization
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.

.agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md

@@ -0,0 +1,82 @@
+---
+title: Prevent Hydration Mismatch Without Flickering
+impact: MEDIUM
+impactDescription: avoids visual flicker and hydration errors
+tags: rendering, ssr, hydration, localStorage, flicker
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect (breaks SSR):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct (no flicker, no hydration mismatch):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.

.agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md

@@ -0,0 +1,30 @@
+---
+title: Suppress Expected Hydration Mismatches
+impact: LOW-MEDIUM
+impactDescription: avoids noisy hydration warnings for known differences
+tags: rendering, hydration, ssr, nextjs
+---
+
+## Suppress Expected Hydration Mismatches
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect (known mismatch warnings):**
+
+```tsx
+function Timestamp() {
+  return <span>{new Date().toLocaleString()}</span>
+}
+```
+
+**Correct (suppress expected mismatch only):**
+
+```tsx
+function Timestamp() {
+  return (
+    <span suppressHydrationWarning>
+      {new Date().toLocaleString()}
+    </span>
+  )
+}
+```

.agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md

@@ -0,0 +1,85 @@
+---
+title: Use React DOM Resource Hints
+impact: HIGH
+impactDescription: reduces load time for critical resources
+tags: rendering, preload, preconnect, prefetch, resource-hints
+---
+
+## Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example (preconnect to third-party APIs):**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+  prefetchDNS('https://analytics.example.com')
+  preconnect('https://api.example.com')
+
+  return <main>{/* content */}</main>
+}
+```
+
+**Example (preload critical fonts and styles):**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+  // Preload font file
+  preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+  // Fetch and apply critical stylesheet immediately
+  preinit('/styles/critical.css', { as: 'style' })
+
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+**Example (preload modules for code-split routes):**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+  const preloadDashboard = () => {
+    preloadModule('/dashboard.js', { as: 'script' })
+  }
+
+  return (
+    <nav>
+      <a href="/dashboard" onMouseEnter={preloadDashboard}>
+        Dashboard
+      </a>
+    </nav>
+  )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+|-----|----------|
+| `prefetchDNS` | Third-party domains you'll connect to later |
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+| `preload` | Critical resources needed for current page |
+| `preloadModule` | JS modules for likely next navigation |
+| `preinit` | Stylesheets/scripts that must execute early |
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [React DOM Resource Preloading APIs](https://react.dev/reference/react-dom#resource-preloading-apis)

.agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md

@@ -0,0 +1,68 @@
+---
+title: Use defer or async on Script Tags
+impact: HIGH
+impactDescription: eliminates render-blocking
+tags: rendering, script, defer, async, performance
+---
+
+## Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect (blocks rendering):**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        <script src="https://example.com/analytics.js" />
+        <script src="/scripts/utils.js" />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        {/* Independent script - use async */}
+        <script src="https://example.com/analytics.js" async />
+        {/* DOM-dependent script - use defer */}
+        <script src="/scripts/utils.js" defer />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+  return (
+    <>
+      <Script src="https://example.com/analytics.js" strategy="afterInteractive" />
+      <Script src="/scripts/utils.js" strategy="beforeInteractive" />
+    </>
+  )
+}
+```
+
+Reference: [MDN - Script element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)

.agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md

@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct (1 decimal place):**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```

.agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md

@@ -0,0 +1,75 @@
+---
+title: Use useTransition Over Manual Loading States
+impact: LOW
+impactDescription: reduces re-renders and improves code clarity
+tags: rendering, transitions, useTransition, loading, state
+---
+
+## Use useTransition Over Manual Loading States
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect (manual loading state):**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct (useTransition with built-in pending state):**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+- **Error resilience**: Pending state correctly resets even if the transition throws
+- **Better responsiveness**: Keeps the UI responsive during updates
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [useTransition](https://react.dev/reference/react/useTransition)

.agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md

@@ -0,0 +1,39 @@
+---
+title: Defer State Reads to Usage Point
+impact: MEDIUM
+impactDescription: avoids unnecessary subscriptions
+tags: rerender, searchParams, localStorage, optimization
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```

.agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md

@@ -0,0 +1,45 @@
+---
+title: Narrow Effect Dependencies
+impact: LOW
+impactDescription: minimizes effect re-runs
+tags: rerender, useEffect, dependencies, optimization
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```

.agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md

@@ -0,0 +1,40 @@
+---
+title: Calculate Derived State During Rendering
+impact: MEDIUM
+impactDescription: avoids redundant renders and state drift
+tags: rerender, derived-state, useEffect, state
+---
+
+## Calculate Derived State During Rendering
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect (redundant state and effect):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const [fullName, setFullName] = useState('')
+
+  useEffect(() => {
+    setFullName(firstName + ' ' + lastName)
+  }, [firstName, lastName])
+
+  return <p>{fullName}</p>
+}
+```
+
+**Correct (derive during render):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const fullName = firstName + ' ' + lastName
+
+  return <p>{fullName}</p>
+}
+```
+
+References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)

.agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md

@@ -0,0 +1,29 @@
+---
+title: Subscribe to Derived State
+impact: MEDIUM
+impactDescription: reduces re-render frequency
+tags: rerender, derived-state, media-query, optimization
+---
+
+## Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect (re-renders on every pixel change):**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```

.agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md

@@ -0,0 +1,74 @@
+---
+title: Use Functional setState Updates
+impact: MEDIUM
+impactDescription: prevents stale closures and unnecessary callback recreations
+tags: react, hooks, useState, useCallback, callbacks, closures
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+2. **No stale closures** - Always operates on the latest state value
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+- Inside useCallback/useMemo when state is needed
+- Event handlers that reference state
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+- Setting state from props/arguments only: `setName(newName)`
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.

.agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md

@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.

.agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md

@@ -0,0 +1,38 @@
+---
+
+title: Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+impact: MEDIUM
+impactDescription: restores memoization by using a constant for default value
+tags: rerender, memo, optimization
+
+---
+
+## Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect (`onClick` has different values on every rerender):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct (stable default value):**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```

.agents/skills/vercel-react-best-practices/rules/rerender-memo.md

@@ -0,0 +1,44 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns
+tags: rerender, memo, useMemo, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.

.agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md

@@ -0,0 +1,45 @@
+---
+title: Put Interaction Logic in Event Handlers
+impact: MEDIUM
+impactDescription: avoids effect re-runs and duplicate side effects
+tags: rerender, useEffect, events, side-effects, dependencies
+---
+
+## Put Interaction Logic in Event Handlers
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect (event modeled as state + effect):**
+
+```tsx
+function Form() {
+  const [submitted, setSubmitted] = useState(false)
+  const theme = useContext(ThemeContext)
+
+  useEffect(() => {
+    if (submitted) {
+      post('/api/register')
+      showToast('Registered', theme)
+    }
+  }, [submitted, theme])
+
+  return <button onClick={() => setSubmitted(true)}>Submit</button>
+}
+```
+
+**Correct (do it in the handler):**
+
+```tsx
+function Form() {
+  const theme = useContext(ThemeContext)
+
+  function handleSubmit() {
+    post('/api/register')
+    showToast('Registered', theme)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)

.agents/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md

@@ -0,0 +1,82 @@
+---
+title: Don't Define Components Inside Components
+impact: HIGH
+impactDescription: prevents remount on every render
+tags: rerender, components, remount, performance
+---
+
+## Don't Define Components Inside Components
+
+**Impact: HIGH (prevents remount on every render)**
+
+Defining a component inside another component creates a new component type on every render. React sees a different component each time and fully remounts it, destroying all state and DOM.
+
+A common reason developers do this is to access parent variables without passing props. Always pass props instead.
+
+**Incorrect (remounts on every render):**
+
+```tsx
+function UserProfile({ user, theme }) {
+  // Defined inside to access `theme` - BAD
+  const Avatar = () => (
+    <img
+      src={user.avatarUrl}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+
+  // Defined inside to access `user` - BAD
+  const Stats = () => (
+    <div>
+      <span>{user.followers} followers</span>
+      <span>{user.posts} posts</span>
+    </div>
+  )
+
+  return (
+    <div>
+      <Avatar />
+      <Stats />
+    </div>
+  )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct (pass props instead):**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+  return (
+    <img
+      src={src}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+}
+
+function Stats({ followers, posts }: { followers: number; posts: number }) {
+  return (
+    <div>
+      <span>{followers} followers</span>
+      <span>{posts} posts</span>
+    </div>
+  )
+}
+
+function UserProfile({ user, theme }) {
+  return (
+    <div>
+      <Avatar src={user.avatarUrl} theme={theme} />
+      <Stats followers={user.followers} posts={user.posts} />
+    </div>
+  )
+}
+```
+
+**Symptoms of this bug:**
+- Input fields lose focus on every keystroke
+- Animations restart unexpectedly
+- `useEffect` cleanup/setup runs on every parent render
+- Scroll position resets inside the component

.agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md

@@ -0,0 +1,35 @@
+---
+title: Do not wrap a simple expression with a primitive result type in useMemo
+impact: LOW-MEDIUM
+impactDescription: wasted computation on every render
+tags: rerender, useMemo, optimization
+---
+
+## Do not wrap a simple expression with a primitive result type in useMemo
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```

.agents/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md

@@ -0,0 +1,64 @@
+---
+title: Split Combined Hook Computations
+impact: MEDIUM
+impactDescription: avoids recomputing independent steps
+tags: rerender, useMemo, useEffect, dependencies, optimization
+---
+
+## Split Combined Hook Computations
+
+When a hook contains multiple independent tasks with different dependencies, split them into separate hooks. A combined hook reruns all tasks when any dependency changes, even if some tasks don't use the changed value.
+
+**Incorrect (changing `sortOrder` recomputes filtering):**
+
+```tsx
+const sortedProducts = useMemo(() => {
+  const filtered = products.filter((p) => p.category === category)
+  const sorted = filtered.toSorted((a, b) =>
+    sortOrder === "asc" ? a.price - b.price : b.price - a.price
+  )
+  return sorted
+}, [products, category, sortOrder])
+```
+
+**Correct (filtering only recomputes when products or category change):**
+
+```tsx
+const filteredProducts = useMemo(
+  () => products.filter((p) => p.category === category),
+  [products, category]
+)
+
+const sortedProducts = useMemo(
+  () =>
+    filteredProducts.toSorted((a, b) =>
+      sortOrder === "asc" ? a.price - b.price : b.price - a.price
+    ),
+  [filteredProducts, sortOrder]
+)
+```
+
+This pattern also applies to `useEffect` when combining unrelated side effects:
+
+**Incorrect (both effects run when either dependency changes):**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+  document.title = `${pageTitle} | My App`
+}, [pathname, pageTitle])
+```
+
+**Correct (effects run independently):**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+}, [pathname])
+
+useEffect(() => {
+  document.title = `${pageTitle} | My App`
+}, [pageTitle])
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, it automatically optimizes dependency tracking and may handle some of these cases for you.

.agents/skills/vercel-react-best-practices/rules/rerender-transitions.md

@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```

.agents/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md

@@ -0,0 +1,59 @@
+---
+title: Use useDeferredValue for Expensive Derived Renders
+impact: MEDIUM
+impactDescription: keeps input responsive during heavy computation
+tags: rerender, useDeferredValue, optimization, concurrent
+---
+
+## Use useDeferredValue for Expensive Derived Renders
+
+When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.
+
+**Incorrect (input feels laggy while filtering):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const filtered = items.filter(item => fuzzyMatch(item, query))
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <ResultsList results={filtered} />
+    </>
+  )
+}
+```
+
+**Correct (input stays snappy, results render when ready):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const deferredQuery = useDeferredValue(query)
+  const filtered = useMemo(
+    () => items.filter(item => fuzzyMatch(item, deferredQuery)),
+    [items, deferredQuery]
+  )
+  const isStale = query !== deferredQuery
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <div style={{ opacity: isStale ? 0.7 : 1 }}>
+        <ResultsList results={filtered} />
+      </div>
+    </>
+  )
+}
+```
+
+**When to use:**
+
+- Filtering/searching large lists
+- Expensive visualizations (charts, graphs) reacting to input
+- Any derived state that causes noticeable render delays
+
+**Note:** Wrap the expensive computation in `useMemo` with the deferred value as a dependency, otherwise it still runs on every render.
+
+Reference: [React useDeferredValue](https://react.dev/reference/react/useDeferredValue)

.agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md

@@ -0,0 +1,73 @@
+---
+title: Use useRef for Transient Values
+impact: MEDIUM
+impactDescription: avoids unnecessary re-renders on frequent updates
+tags: rerender, useref, state, performance
+---
+
+## Use useRef for Transient Values
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect (renders every update):**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX)
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: lastX,
+        width: 8,
+        height: 8,
+        background: 'black',
+      }}
+    />
+  )
+}
+```
+
+**Correct (no re-render for tracking):**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0)
+  const dotRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX
+      const node = dotRef.current
+      if (node) {
+        node.style.transform = `translateX(${e.clientX}px)`
+      }
+    }
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      ref={dotRef}
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: 8,
+        height: 8,
+        background: 'black',
+        transform: 'translateX(0px)',
+      }}
+    />
+  )
+}
+```

.agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md

@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)

.agents/skills/vercel-react-best-practices/rules/server-auth-actions.md

@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)

.agents/skills/vercel-react-best-practices/rules/server-cache-lru.md

@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)

.agents/skills/vercel-react-best-practices/rules/server-cache-react.md

@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)

.agents/skills/vercel-react-best-practices/rules/server-dedup-props.md

@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

.agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md

@@ -0,0 +1,149 @@
+---
+title: Hoist Static I/O to Module Level
+impact: HIGH
+impactDescription: avoids repeated file/network I/O per request
+tags: server, io, performance, next.js, route-handlers, og-image
+---
+
+## Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect (reads font file on every request):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct (loads once at module initialization):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Correct (synchronous fs at module level):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Incorrect (reads config on every call):**
+
+```typescript
+import fs from 'node:fs/promises'
+
+export async function processRequest(data: Data) {
+  const config = JSON.parse(
+    await fs.readFile('./config.json', 'utf-8')
+  )
+  const template = await fs.readFile('./template.html', 'utf-8')
+
+  return render(template, data, config)
+}
+```
+
+**Correct (hoists config and template to module level):**
+
+```typescript
+import fs from 'node:fs/promises'
+
+const configPromise = fs
+  .readFile('./config.json', 'utf-8')
+  .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise,
+  ])
+
+  return render(template, data, config)
+}
+```
+
+When to use this pattern:
+
+- Loading fonts for OG image generation
+- Loading static logos, icons, or watermarks
+- Reading configuration files that don't change at runtime
+- Loading email templates or other static templates
+- Any static asset that's the same across all requests
+
+When not to use this pattern:
+
+- Assets that vary per request or user
+- Files that may change during runtime (use caching with TTL instead)
+- Large files that would consume too much memory if kept loaded
+- Sensitive data that shouldn't persist in memory
+
+With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.

.agents/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md

@@ -0,0 +1,50 @@
+---
+title: Avoid Shared Module State for Request Data
+impact: HIGH
+impactDescription: prevents concurrency bugs and request data leaks
+tags: server, rsc, ssr, concurrency, security, state
+---
+
+## Avoid Shared Module State for Request Data
+
+For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race conditions, cross-request contamination, and security bugs where one user's data appears in another user's response.
+
+Treat module scope on the server as process-wide shared memory, not request-local state.
+
+**Incorrect (request data leaks across concurrent renders):**
+
+```tsx
+let currentUser: User | null = null
+
+export default async function Page() {
+  currentUser = await auth()
+  return <Dashboard />
+}
+
+async function Dashboard() {
+  return <div>{currentUser?.name}</div>
+}
+```
+
+If two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.
+
+**Correct (keep request data local to the render tree):**
+
+```tsx
+export default async function Page() {
+  const user = await auth()
+  return <Dashboard user={user} />
+}
+
+function Dashboard({ user }: { user: User | null }) {
+  return <div>{user?.name}</div>
+}
+```
+
+Safe exceptions:
+
+- Immutable static assets or config loaded once at module scope
+- Shared caches intentionally designed for cross-request reuse and keyed correctly
+- Process-wide singletons that do not store request- or user-specific mutable data
+
+For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).

.agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

.agents/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md

@@ -0,0 +1,34 @@
+---
+title: Parallel Nested Data Fetching
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, promise-chaining
+---
+
+## Parallel Nested Data Fetching
+
+When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.
+
+**Incorrect (a single slow item blocks all nested fetches):**
+
+```tsx
+const chats = await Promise.all(
+  chatIds.map(id => getChat(id))
+)
+
+const chatAuthors = await Promise.all(
+  chats.map(chat => getUser(chat.author))
+)
+```
+
+If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.
+
+**Correct (each item chains its own nested fetch):**
+
+```tsx
+const chatAuthors = await Promise.all(
+  chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))
+)
+```
+
+Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.

.agents/skills/vercel-react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

.claude/memory/project_drawRoofByAttribute_internals.md

@@ -0,0 +1,396 @@
+---
+name: drawRoofByAttribute 내부 구조 (후반부 상세)
+description: qpolygon-utils.js drawRoofByAttribute (1680-5455, 3777줄) 의 단계별 정밀 분석. 라인 분류→가선분(linesAnalysis) 누적→MAX_ITERATIONS 교점 처리→하단지붕 파생→최종 split. 수정 시 어느 stage 인지 식별 필수.
+type: project
+---
+
+# drawRoofByAttribute 내부 구조 (후반부 상세)
+
+`src/util/qpolygon-utils.js:1680-5455` 의 정밀 분해. catch-all 함수라 모든 비표준 케이스(요세무네/맨사드/형이동/벽취합/팔작/반절처/케라바 혼합 등)가 여기 모인다.
+
+## 0. 데이터 흐름 한 장 요약
+
+```
+wall.baseLines → [zero merge] → baseLines (mutated copy)
+              ↓
+              type 분류: sheds / hipAndGables / eaves / jerkinHeads / gables
+              ↓
+              [stage1 처리] 각 type 별로:
+                 - innerLines.push(drawHip/Ridge/RoofLine ...)  ← 즉시 그림
+                 - linesAnalysis.push({start, end, left, right, type, degree})  ← 가선분 누적
+              ↓
+              [stage2 MAX_ITERATIONS 루프] linesAnalysis 끼리 교점 → drawHip/Ridge + newAnalysis 분기
+              ↓
+              [stage3 가선분 잔여] 평행 라인 예외처리
+              ↓
+              [stage4 벽취합 잔여] 벽-벽 라인 처리
+              ↓
+              [stage5 하단지붕 파생] downRoofGable (A/B) + downRoofEaves
+              ↓
+              [stage6 최종 split] roof.lines × innerLinesPoints 분할 → drawHip/RoofLine
+              ↓
+              roof.innerLines = innerLines (덮어쓰기)
+```
+
+`innerLines` 와 `linesAnalysis` 는 **다른 컨테이너**:
+- `innerLines`: 실제 캔버스에 그려진 QLine 객체들 (drawHip/Ridge/RoofLine 반환값)
+- `linesAnalysis`: 가상 선분 메타데이터 (`{start, end, left, right, type, degree, gableId?, connectCnt?}`) — 아직 캔버스에 안 그려짐, 교점 계산용
+
+`TYPES = { HIP, RIDGE, GABLE_LINE, NEW }` 는 linesAnalysis 내부 enum (canvas 의 `LINE_TYPE.SUBLINE` 과 별개).
+
+## 1. 전반부 (1680-1995) — 이미 파악된 영역
+
+- **1680-1759 형이동 zero-merge**: `wall.baseLines` 중 `planeSize<EPSILON` 인덱스를 prev/next 페어로 모아 같은 vector 라인 끼리 합쳐 `baseLines` 재구성. zero-merge 후엔 `wall.baseLines` 의 중간 라인이 사라진 짧은 형태가 됨.
+- **1761 `checkWallPolygon`**: `baseLines` 의 시작점만 모아 만든 임시 QPolygon. inPolygon 판정 전용.
+- **1766-1995 벽취합 corner extension**: WALL+offset>0 라인의 prev/next 처리, `addRoofLine1/2` 추가. `name='addRoofLine'`, `attributes.type=WALLLINE.ETC`.
+
+## 2. analyzeLine 헬퍼 (2000-2133)
+
+drawGableRoof 의 `analyzeEavesLine` 과 거의 동일하지만 모든 type 에 적용. **return**:
+```
+{ startPoint, endPoint, length, angleDegree, normalizedAngle,
+  isHorizontal, isVertical, isDiagonal,
+  directionVector: {x,y},
+  roofLine: 매칭된 roof.lines 의 한 라인,
+  roofVector: {x,y} (지붕 안쪽 방향, 단위벡터) }
+```
+
+핵심:
+- tolerance 1° 로 H/V/Diagonal 분류
+- `roof.lines` 중 directionVector 가 같은 것을 `checkRoofLines` 로 거름
+- offset=0: 좌표 직접 매칭. 실패 시 `currentRoof = { roofLine: line }` 자기 자신 fallback (NPE 방지)
+- offset>0: midPoint 에서 roofVector 방향으로 offset 만큼 가선 그어서 `edgesIntersection` 검색, intersect 길이 - offset < 0.1 으로 best match 선택
+
+⚠️ `roofLine` 매칭 실패 시 `currentRoof.roofLine` 직접 접근 (2130) — fallback 로직이 있어서 안전하지만 추가 변경 시 NPE 주의.
+
+## 3. getRidgeDrivePoint 헬퍼 (2142-2270)
+
+마루(ridge)/이등분선 등이 **반대편 케라바(GABLE) 또는 이중처마(EAVES-EAVES) 코너**까지만 뻗도록 클램프하는 포인트를 계산.
+
+- prevLine/nextLine 이 모두 EAVES 가 아니면 `null` (호출처에서 fallback 처리)
+- prevLine 이 EAVES 이고 그 prev 가 GABLE 이면 → GABLE 의 roofLine 과 testPoint 의 교점 (=GABLE 코너)
+- prevLine 이 EAVES 이고 그 prev 도 EAVES 이면 → 두 EAVES 의 사잇각 vector 로 hip edge 그어서 testPoint 와의 교점
+- nextLine 쪽도 대칭
+- 둘 다 있으면 가까운 쪽
+- prevHasGable / nextHasGable 우선순위: `prevLength <= nextLength` 면 prev, 아니면 next 의 GABLE 사용
+
+호출처: hipAndGables, ridgeEaves, jerkinHeads, MAX_ITERATIONS 루프(NEW 가선분 분기 시)
+
+## 4. 라인 분류 (2275-2300)
+
+```
+baseLines.forEach(switch on attributes.type):
+  SHED          → sheds[]
+  HIPANDGABLE   → hipAndGables[]    (팔작지붕/이리모야)
+  EAVES         → eaves[]           (처마)
+  JERKINHEAD    → jerkinHeads[]     (반절처)
+  GABLE         → gables[]          (케라바/박공)
+  default       → 무시 (WALL, ETC, DEFAULT 등)
+```
+
+`linesAnalysis = []` 초기화 (2303).
+
+## 5. 단계별 처리 (1~5)
+
+### 5-1. sheds.forEach (2306-2467) — 한쪽흐름
+
+가드: 양옆이 둘 다 GABLE 이어야 함. 아니면 return.
+
+1. 맞은편 EAVES 라인 찾기 → shedDegree 산출 (없으면 4寸 default)
+2. roofLine 양 끝점에서 지붕 안쪽으로의 vector 두 개 (`checkRoofVector1/2`) 그어서 반대편 roof.lines 와의 교점 (`intersectPoints1/2`)
+3. **HIP 가선분 2개 push** (양 끝점 → 교점), `left=beforePrevIndex/nextIndex`, `right=prevIndex/afterNextIndex`, `type=TYPES.HIP`, `degree=shedDegree`
+
+⚠️ `intersectPoints1[0]` 직접 인덱스 접근 (2441) — sort 후 비어있으면 NPE.
+
+### 5-2. hipAndGables.forEach (2470-2699) — 팔작지붕
+
+가드: 양옆이 둘 다 EAVES. 그리고 prevLine/nextLine 의 vector 가 같으면(같은 방향, U자) silent return.
+
+1. `lineWidth = min(currentLine.attributes.width, roofLength/2)` — 팔작지붕 두께 클램프
+2. prevRoofLine/nextRoofLine 와 currentRoofLine 의 사잇각 vector 로 prevHipPoint/nextHipPoint 산출 (지붕 안쪽 방향 정규화)
+3. **HIP 2개 즉시 그림** (`innerLines.push(drawHipLine prev, next)`)
+4. 양옆이 모두 EAVES (gable 이 짧을 때): midPoint 에서 양쪽 gable hip 두개 추가 + roofVector 반대 방향으로 10000 길이 가선 그어서 반대편 roof 교점 → `getRidgeDrivePoint` 로 클램프 → `oppLine.attributes.type` 별 offset 보정 (HIPANDGABLE=width, JERKINHEAD=width/2, WALL=0) → **RIDGE 가선분 push**
+5. else (gable 길이 충분): `drawRoofLine(gablePoint)` 즉시 그림. 길이 ~0 이면 RIDGE 가선분만 push
+
+### 5-3. eaves 처리 (2701-3143)
+
+eaves 를 `planeSize` 오름차순 sort 후 두 그룹으로 분리:
+- **`ridgeEaves`** (2704-2723): 양옆 모두 EAVES + prev/next vector 가 다른 방향 + checkWallPolygon.inPolygon(midPoint+nextVector) — 즉 처마-처마-처마 코너에서 안쪽 들여진 모양
+- **`hipedEaves`** (2725): 나머지 (= 옆이 GABLE 등)
+
+#### ridgeEaves.forEach (2731-3036) — 가장 복잡한 블록
+
+상태 누적기:
+- `proceedEaves[]`: `{prev, current, point: {x1,y1,x2,y2}, length}` — 처리된 처마 hip
+- `proceedRidges[]`: `{prev, next, point}` — 처리된 ridge
+
+알고리즘:
+1. pHipVector/nHipVector (양 옆과의 사잇각) 산출, inPolygon 으로 정규화
+2. `findRoofPoints(checkPoint)` 헬퍼: hipEdge 와 roof.lines 교점들을 forward/backward 로 분리 후 가까운 것 선택. forward+backward / backward 2개 / forward 2개 fallback
+3. prevHipPoint/nextHipPoint 두 hip 의 `edgesIntersection` 으로 정점 보정
+4. **proceedRidges 루프**: 같은 base index 영향권의 ridge 가 prev/next hip 와 교차하면 `isRidgePrev/isRidgeNext` 플래그 → hip 좌표를 forward 로 되돌림(roof 정점까지)
+5. **proceedEaves 중복 처리**: `alreadyPrev/Next` 가 있으면 길이가 짧은 쪽으로 교체 (또는 새 hip 좌표를 기존 것으로 덮음). isRidge 플래그 시 무조건 교체
+6. prevHipPoint.x2 와 nextHipPoint.x2 가 같으면(=정점 만남) **ridge 생성**:
+   - midPoint 에서 ridgeVector(nextLine 방향, inPolygon 정규화) 로 가선
+   - roof.lines 와의 가까운 교점 → ridge 끝점
+   - `getRidgeDrivePoint` 로 클램프
+   - `isOverlapBefore/After` (beforePrev/afterNext 가 currentLine 과 동일 좌표 범위) 시 oppLine.type 별 offset 보정 분기:
+     - 양옆에 GABLE 있음(otherGable): drivePoint 우선
+     - 없음 + oppLine=EAVES + 양옆에 EAVES: 길이 같으면 drivePoint, 다르면 offset
+     - 없음 + 그 외: offset 만 적용
+7. ridge 중복 체크 후 `proceedRidges.push`
+
+#### hipedEaves.forEach (3038-3143)
+
+가드: prevLine 이 EAVES 여야 함. 아니면 return.
+
+1. currentLine 와 prevLine 의 사잇각 vector → hipVector (inPolygon 정규화)
+2. `currentLine.x1` 에서 hipVector × `analyze.length` 길이로 가선 → roof.lines 의 forward/backward 교점
+3. **HIP 가선분 push** (linesAnalysis), `degree=currentDegree` (currentLine.pitch)
+
+#### proceedEaves → linesAnalysis 변환 (3146-3219)
+
+```
+proceedEaves.forEach((eaves, index)):
+  - jointEaves = 같은 끝점(point.x2,y2) 공유하는 다른 eaves 검색
+  - jointEaves.length === 1 + ridgeEaves.length > 1:
+      drawHipLine 즉시 그림 (innerLines.push)
+  - jointEaves.length === 2 (3-way 코너):
+      jointIndex 3개 모두 drawHipLine 즉시
+      proceedRidges 에서 해당 코너 ridge 제거
+      "denyVector" (반대쌍 없는 vector) 찾아서 roof 와의 교점 → HIP 가선분 push (uniqueLine 좌우)
+  - else:
+      HIP 가선분 push (linesAnalysis)
+```
+
+#### proceedRidges → linesAnalysis (3220-3229): 모두 RIDGE 가선분으로 push
+
+### 5-4. jerkinHeads.forEach (3232-3445) — 반절처
+
+가드: 양옆 EAVES. 양옆 vector 같으면 silent return.
+
+1. `gableWidth = currentLine.attributes.width`, `lineLength = (roofLength - gableWidth) / 2`
+2. roofLine 따라 4개 점 (`jerkinPoints`): 시작 → +lineLength → +gableWidth → +lineLength=끝
+3. `gableWidth >= roofLength`: **drawRoofLine** 즉시 (roofPoints 그대로)
+4. 정상: **drawHipLine(gable1, prevDegree) + drawRoofLine(gable2) + drawHipLine(gable3, nextDegree)** 즉시
+5. 추가로 prevRoofLine/nextRoofLine 과의 사잇각 hipVector × gableWidth → prevHipEdge/nextHipEdge 교점 hipIntersection
+6. hipIntersection 있으면 **drawHipLine prev/next 2개 즉시** + roofVector 반대 방향으로 10000 가선 → roof 교점 → drivePoint 클램프 → offset 보정 → **RIDGE 가선분 push**
+
+### 5-5. gables.forEach (3447-4239) — 케라바/박공 (가장 큰 블록)
+
+가드: 양옆 EAVES. 그리고 vector 다른 방향 + checkWallPolygon.inPolygon 통과해야 본 처리.
+
+#### isOverlap 분기 (3502-3562)
+
+`isOverlapBefore/After` (beforePrev 또는 afterNext 가 currentLine 좌표 범위 동일) + otherGable 없음 → **isOverlap=true**:
+- mid-to-mid ridge: cMid + ridgeVector*cOffset → oMid - ridgeVector*oOffset, oppLine.type 별 추가 offset
+- 중복 체크 후 **RIDGE 가선분 push**
+
+#### 일반 분기 (3563-4182)
+
+stdLine 결정: prevLine/nextLine 의 거리 (`prevDistance/nextDistance`) 비교, 둘 다 GABLE 이면 긴 쪽, 아니면 짧은 쪽. `stdFindOppVector` 도 같이 결정.
+
+`stdPoints` 좌표 보정:
+- **stdPrevVector === stdNextVector** (U자 코너): isHorizontal/isVertical × stdVector × prev/next y/x 비교로 8가지 분기, GABLE 일 때만 offset 적용
+- 다른 방향: 양 끝점에 prev/nextLine offset 적용
+
+`oppositeLine` 검색: stdLine 의 반대편 (stdFindOppVector 방향) 평행 라인들 (overlap 케이스 포함)
+
+`oppositeLine.forEach(opposite)` (3787-4083):
+1. ridgePoint 산출:
+   - oppPrev/oppNextVector 같으면 (U자): 평행 offset 두번 적용
+   - 다르면 (Y/L자): inPolygon 분기로 offset 부호 결정
+2. stdAnalyze 축에 맞춰 ridgePoint 의 한 축을 mid 좌표로 통일
+3. **oppLine 양옆 EAVES/GABLE 혼합 케이스 분기** (3835-3976):
+   - oppPrev xor oppNext 가 EAVES: stdLine 길이 >= oppLine 길이일 때 hipEdge 와 ridgeEdge 교점 → ridgePoint 시작점 보정
+   - 짧은 stdLine + EAVES 짧은 stdPrev/Next: drivePoint 보정
+4. stdPrev/Next 가 EAVES: driveEdge 와 ridgeEdge 교점 → stdPoints 의 해당 끝점 좌표 갱신
+5. overlap 영역(stdMin/Max × ridgeMin/Max) 으로 ridgePoint 클램프, vector 정렬 보정
+6. `ridgePoints.push({point, left:stdLine, right:oppLine})`
+
+`ridgePoints.forEach(r)` (4085-4180):
+- inPolygon1/2 체크, 밖이면 vector 내 가장 가까운 roof.line 으로 보정
+- roof boundary 위에 있는 점이 1개만이면 그 점이 startPoint
+- **RIDGE 가선분 push** (중복 체크)
+
+#### 4185-4231 — 양옆 vector 같음 (반절마루 불가) 케이스
+
+`prevLineVector === nextLineVector` (U자): roofLine 직각 방향으로 가선 → 반대편 roof.line 교점 (가장 먼 것) → 시작점은 roofLine 양 끝 중 교점에서 먼 쪽 → **GABLE_LINE 가선분 push** (`degree = prevLine.pitch`, `gableId=baseLines.findIndex(currentLine)`, `connectCnt=0`)
+
+## 6. MAX_ITERATIONS 루프 (4242-4608) — 가선분 교점 처리
+
+`linesAnalysis` 가 비거나 1000회 도달까지 반복:
+
+### 6-1. intersections 수집 (4248-4297)
+
+각 currLine 마다:
+- length<EPSILON 무시
+- GABLE_LINE + connectCnt>1 무시
+- 다른 nextLine 과 `lineIntersection(seg-seg)` 시도
+- 가장 짧은 distance1 (+ 같은 GABLE_LINE pair gableId 같으면 skip) 의 partner 선택
+- distance1==minDistance 일 때 `isSameLine` (left/right 공유) 우선
+
+### 6-2. 단일 교점 보정 (4302-4305)
+
+`intersectPoints` unique 가 1개고 intersections 가 ≥2 → 첫 두개를 서로 partner 로 강제.
+
+### 6-3. for-of 처리 (4310-4597)
+
+intersection 페어마다:
+- mutual partner 아니거나 left/right 공통 안 되면 skip
+- 각각 drawHip/Ridge 그림 (innerLines.push, alreadyPoints 중복 차단):
+  - `cLine.type === HIP` → drawHipLine (cLine.degree)
+  - `RIDGE` → drawRidgeLine
+  - `NEW` → diagonal 이면 hip, 아니면 ridge
+  - `GABLE_LINE` → degree>0 hip, 아니면 ridge
+
+#### 동일 교점에 다른 라인이 더 있으면 (otherIs)
+- 관련 baseline 공유하는 라인은 추가 그리고 processed
+- (GABLE_LINE 페어인 경우는 otherIs 처리 skip)
+
+#### GABLE_LINE 분기 (4425-4467)
+- `gableLine.connectCnt++`
+- uniqueLines 2개면:
+  - connectCnt<2: GABLE_LINE 가선분 새로 push (intersect → end)
+  - connectCnt>=2: HIP 더미 (start==end) push — "가선분 발생만 시키는" trigger 용
+
+#### 일반 분기 (4468-4588) — NEW 가선분 생성
+1. uniqueLines 2개 → bisector 계산 (`isParallel` 면 `getBisectLines`(평행 시 길이 보정 100), 아니면 `getBisectBaseLines`)
+2. bisector 방향으로 roof.lines 와 교점 → 가까운 것
+3. **이미 같은 교점 가진 미처리 라인 있으면 그것을 newAnalysis 로 교체** (재활용)
+4. 아니면 NEW 가선분 push (`type=NEW`, `degree= isDiagonal ? cLine.degree : 0`)
+5. drivePoint 로 ridge 길이 클램프 (NEW + horizontal/vertical 일 때만)
+
+`newAnalysis.length > 0` 이면 break (한 페어 처리 후 즉시 재계산)
+
+### 6-4. 루프 종료 후 (4599-4608)
+
+`linesAnalysis = newAnalysis ⊕ (linesAnalysis - processed)`. newAnalysis 비면 while 종료.
+
+## 7. 가선분 잔여 (4610-4696)
+
+남은 linesAnalysis 의 평행 페어 처리:
+- isOpposite (반대 방향): start-start 사이 line, type 별 drawHip/Ridge
+- 동일 방향: 4개 점 중 unique 2개로 line, isDiagonal 여부에 따라 drawHip/Ridge
+- 처리된 라인은 `proceedAnalysis` 로 마킹 후 linesAnalysis 에서 제외
+
+## 8. 벽취합 잔여 (4698-4732)
+
+linesAnalysis 에 남은 line 중:
+- start/end 가 모두 roof.lines 위에 있으면:
+  - line.type=RIDGE + baseLines.length===4 + (start 또는 end 가 onLine): drawRidgeLine
+  - 그 외 (양쪽 다 onLine): degree===0 → drawRoofLine, 아니면 drawHipLine
+- innerLines 에 같은 끝점이 3개 미만, 다른 끝점은 없을 때만 그림 (중복 차단)
+
+## 9. 하단지붕 분류 (4734-4778)
+
+baseLines 순회하며 3종류로 분류:
+
+- **downRoofGable type 'A'** (4750-4757): prevVector === nextVector (U자) + currentLine=EAVES + 양옆 중 하나라도 GABLE
+- **downRoofGable type 'B'** (4759-4766): prevVector ≠ nextVector + checkWallPolygon.inPolygon(mid+nextVector) + 양옆 둘 다 GABLE
+- **downRoofEaves** (4768-4777): prevVector === nextVector + currentLine=EAVES + 양옆 중 하나라도 EAVES + originPoint ≠ 현재 좌표 (=형이동된 라인)
+
+## 10. downRoofLines (4780-5158)
+
+### 10-1. type='A' (4782-4971) — U자 케라바 사이 처마
+
+1. `gableLine` = prev 또는 next (currVector × prev/nextVector 8가지 분기)
+2. `stdPoint` = currentLine 양 끝 (gableLine 쪽 그대로 + 반대쪽 -currVector × otherLine.offset)
+3. `oppLines` = baseLines 중 stdLine 반대쪽 평행 라인들
+4. `innerRidge` = innerLines 중 RIDGE 라인 + currVector 와 같은 축 + stdPoint 범위 안
+5. `roofLinePoint` = stdPoint 에 currOffset 적용 (currVector.x===0 이면 ±y, 아니면 ∓x)
+6. **drawRoofLine(roofLinePoint)** push
+7. roofLinePoint 에서 oppFindVector 방향 가선 → innerRidge 와 교점 가장 가까운 것 → **drawHipLine + drawRoofLine** (intersect → 인접한 ridge 끝점)
+
+### 10-2. type='B' (4974-5157) — 안쪽으로 들어간 케라바 양쪽
+
+1. `ridgeFindVector` = nextVector (mid 가 polygon 안일 때) 또는 prevVector
+2. `oppLines` = innerLines RIDGE 중 ridgeFindVector 방향 + currentLine 범위 안
+3. `roofPoint` = currentLine 좌표에 -nextVector × currOffset 적용
+4. **drawRoofLine(roofPoint)** push
+5. orthogonalStart/EndPoint = currentLine 양 끝에서 oppLines 의 가까운 끝점에 직각으로 투영
+6. orthogonalStartLine === orthogonalEndLine: **drawRoofLine(start→end)** 1개
+7. 다르면: **drawRoofLine 2개** (각 ridge 의 먼 끝점까지 연장)
+8. 추가로 **drawHipLine 2개** (roofPoint 양 끝 → orthogonalPoint 양 끝)
+
+## 11. downRoofEaves.forEach (5160-5376) — 처마 형이동 흡수 라인
+
+핵심 데이터:
+- `flowDistance` = currentLine 과 originPoint 의 axis 거리
+- `isFlowInside` = inPolygon 으로 안/밖 결정
+- `upLine` (상단 지붕) = isFlowInside 면 otherLine, 아니면 currentLine
+- `downLine` (하단 지붕) = 반대
+- `joinPoint` = upLine 과 downLine 이 만나는 모서리
+
+상단 지붕 처리:
+1. `upRoofPoint` = upRoofLine 끝점에 upRoofVector × addUpOffset(=flowDistance) 더한 좌표 (inPolygon 통과하는 방향)
+2. `upHipStartPoint` = upRoofLine 의 다른 끝
+3. `upHipVector` = upLine + downLine 사잇각 (inPolygon 정규화)
+4. `joinHipLine` = innerLines 중 joinPoint + (joinPoint+upHipVector) 둘 다 위에 있는 라인 (=기존에 그려진 추녀마루)
+
+하단 지붕 처리:
+5. `downRoofPoint` = downRoofLine 끝점 + downRoofVector × addDownOffset(=upLine.offset), inPolygon 분기
+6. `intersectJoin` = upRoofEdge × joinHipEdge — 상단 지붕선과 추녀마루의 교점 → joinHipLine.set 으로 좌표 갱신 (mutated!)
+
+upSideLine 분기 (upLine 의 다른 인접 라인):
+- upSideLine = EAVES (= 처마 끼고 추녀마루 분기 가능):
+  - innerLines 중 joinHipLine 외에 upRoofEdge 와 교점 + minDistance > EPSILON: **drawHipLine(connectPoint) + drawRoofLine(connectPoint→intersectJoin)**
+  - 없음: **drawRoofLine(upHipStartPoint→intersectJoin)**
+- 아니면: **drawRoofLine(upHipStartPoint→intersectJoin)**
+
+각 그릴 때 `roof.adjustRoofLines.push({point, roofIdx: upRoofLine.idx})` — 회로/모듈 배치에서 보정 참조용.
+
+하단 지붕 추녀마루 (intersectDownJoin = downHipEdge × joinHipEdge):
+- 있으면 **drawRoofLine(downRoofPoint) + drawHipLine(downHip1) + drawHipLine(downHip2 → joinEndPoint)** — 지붕선/추녀마루1/추녀마루2 트리오
+
+## 12. 최종 split + finalize (5379-5454)
+
+```js
+innerLines.push(...downRoofLines)     // 하단 지붕 모두 합류
+
+// roof.lines 각 라인을 innerLines 끝점들로 분할
+innerLinesPoints = unique(innerLines.{x1,y1,x2,y2})
+roof.lines.forEach((currentLine, idx) => {
+  if (innerLine 이 currentLine 을 완전 포함 또는 그 반대) skip   // hasOverlapLine 가드
+  splitPoint = innerLinesPoints 중 currentLine 위에 있고 끝점 아닌 것
+
+  if (splitPoint > 0):
+    // 첫 분할 = drawHipLine(prevDegree)
+    // 중간 = drawRoofLine
+    // 마지막 = splitPoint===1 이면 drawRoofLine, 아니면 drawHipLine(nextDegree)
+  else:
+    // 통째로 drawRoofLine
+})
+
+roof.innerLines = innerLines    // ← 덮어쓰기 (drawGableRoof 의 push 와 다름!)
+canvas 의 'check' 객체 제거 + renderAll
+```
+
+## 13. 수정 작업 시 어느 stage 인지 식별 가이드
+
+| 증상 | 의심 stage |
+|---|---|
+| 한쪽흐름 추녀가 안 그려짐 | 5-1 sheds (양옆 GABLE 가드) |
+| 팔작 모서리 잘못 그려짐 | 5-2 hipAndGables, prev/nextHipVector inPolygon 분기 |
+| 처마 hip 길이가 비대칭 | 5-3 ridgeEaves proceedEaves alreadyPrev/Next 길이 비교 |
+| 마루가 코너 직전에서 끊김/넘침 | getRidgeDrivePoint 또는 isOverlapBefore/After offset 분기 |
+| 반절처 추녀마루 안 생김 | 5-4 jerkinHeads hipIntersection 또는 width >= roofLength 가드 |
+| 케라바 ridge 가 비뚤어짐 | 5-5 gables stdLine 결정/oppositeLine 보정 |
+| `connectCnt`/`gableId` 충돌 | 6-3 GABLE_LINE 분기 |
+| 가짜 ridge 가 남음 | 7 가선분 잔여 또는 8 벽취합 잔여 |
+| 형이동 처마 위로 추녀마루 누락 | 11 downRoofEaves joinHipLine 분기 |
+| roof boundary 가 hip 으로 잘못 분류 | 12 최종 split splitPoint 0개 케이스 |
+| 라인이 두 번 그려짐 | `alreadyPoints(innerLines, point)` 가드 누락 또는 splitPoint 의 hasOverlapLine 미작동 |
+
+## 14. 함정 모음
+
+1. **`linesAnalysis` 와 `innerLines` 혼동 금지**. 가선분 메타와 그려진 QLine 은 동기화되지 않음. 어떤 코드는 즉시 그리고 어떤 코드는 가선분만 push 한다.
+2. **`drawRoofLine` 의 name 이 SUBLINE.HIP** — 후처리(평균화) 에서 hip 로 분류됨. 이름 보고 type 구분 금지.
+3. **TYPES.NEW = 가선분 분기 결과** — bisector 로 만들어진 가상 ridge/hip. degree 는 isDiagonal 일 때만 cLine.degree, 아니면 0 (=plane).
+4. **GABLE_LINE.connectCnt** — 0/1/2 단계로 increment. 2 이상이면 더미 가선분만 발생, 본인은 더 이상 그리지 않음.
+5. **roof.adjustRoofLines** — downRoofEaves 단계에서만 push. 회로/모듈 배치 단계에서 참조. roof.innerLines 와 별도.
+6. **MAX_ITERATIONS=1000** — 무한루프 방지지만 도달하면 silent 미완성 (경고 없음). 케이스 추가 시 수렴 보장 확인 필수.
+7. **`joinHipLine.set(...)`** (5278) — 기존 라인을 mutate 한다. 즉 5단계 이전에 만들어진 hip 의 좌표가 바뀐다.
+8. **`checkWallPolygon`** (1761) — `baseLines.map(line => ({x:line.x1, y:line.y1}))` 로 만듦. zero-merge 후의 baseLines 시작점만 사용. 전체 라인 좌표가 아님.
+9. **여러 곳에서 `intersectionsByRoof[0]`/`intersectPoints1[0]` 직접 접근** — 비어있을 가능성 가드 없음. 케이스 추가 시 NPE 위험.
+10. **proceedRidges/proceedEaves 는 ridgeEaves 루프 전용 누적기** — 다른 단계(hipedEaves, jerkinHeads, gables)에서 보지 않음. 즉 케이스 간 충돌 가능.

.claude/memory/project_qpolygon_utils_roof_creation.md

@@ -0,0 +1,171 @@
+---
+name: qpolygon-utils 지붕 생성 구조
+description: src/util/qpolygon-utils.js (6507줄) 의 지붕 그리기 3대 진입점(drawGableRoof / drawShedRoof / drawRoofByAttribute) + 하부 헬퍼 + 호출 경로 매핑. 지붕 생성 로직 수정 전 필독.
+type: project
+---
+
+# qpolygon-utils 지붕 생성 구조 (수정 작업 전 reference)
+
+`src/util/qpolygon-utils.js` 는 6507줄·49개 top-level decl. **지붕 그리기는 이 파일이 단독 책임**(용마루/SK 케이스만 `skeleton-utils.js` 로 분기).
+
+## 1. 호출 진입점 (caller side)
+
+**유일한 호출자**: `QPolygon.drawHelpLine(settingModalFirstOptions, forceRedraw=false)` — `src/components/fabric/QPolygon.js:472`
+
+분기 (`drawHelpLine` 내부, `QPolygon.js:584-602`):
+
+```
+types = lines.map(l => l.attributes.type)
+
+if every type === EAVES:
+  if verifyMoveBoundary === 'crossed': drawSkeletonRidgeRoofFromBaseLines  ← skeleton-utils
+  else:                                drawSkeletonRidgeRoof                 ← skeleton-utils
+elif isGableRoof(types):              drawGableRoof          ← qpolygon-utils
+elif isShedRoof(types, lines):        drawShedRoof           ← qpolygon-utils
+else:                                 drawRoofByAttribute    ← qpolygon-utils  (catch-all)
+```
+
+판정 함수 (모두 QPolygon.js inline):
+- `isGableRoof(types)`: 홀짝 인덱스로 EAVES/GABLE(or JERKINHEAD) 교차 패턴 — 박공(A/B형)
+- `isShedRoof(types, lines)`: SHED 포함 + SHED 라인들이 평행 + SHED 반대편이 모두 EAVES + 나머지가 GABLE/JERKINHEAD
+- 그 외(혼합)는 모두 `drawRoofByAttribute`
+
+`drawHelpLine` 호출 지점 (재빌드 트리거):
+- `hooks/useMode.js:1561`
+- `hooks/roofcover/useMovementSetting.js:841,985`
+- `hooks/roofcover/useRoofShapeSetting.js:502`
+- `hooks/roofcover/usePropertiesSetting.js:176`
+- `hooks/roofcover/useEavesGableEdit.js:276,280`
+- `QPolygon.js:664` — `forceRedraw=true` wrapper (verifyMoveBoundary crossed 가드 우회용)
+
+`drawHelpLine` 직후(`QPolygon.js:606-647`)에 **대칭 hip 쌍 dimension 평균화** 후처리: ±5mm 묶어 평균 plane/actual 산정 → 0.5 단위 round → 라인 attribute + lengthText 동기화. (round-off 비대칭 보정용)
+
+## 2. qpolygon-utils.js 섹션 맵
+
+| 라인 범위 | 카테고리 | 주요 함수 |
+|---|---|---|
+| 10-100 | 상수·기본 | `EPSILON=1e-10`, `defineQPolygon`, `calculateAngle`, `inward/outwardEdgeNormal`, `createPolygon` |
+| 102-372 | 다각형 offset/clip | `edgesIntersection`, `appendArc`, `createOffsetEdge`, `createMargin/PaddingPolygon`, `clipOffsetToOriginal` |
+| 373-456 | 자가교차/중복 | `cleanSelfIntersectingPolygon`, `offsetPolygon`(default export), `removeDuplicatePolygons` |
+| 478-651 | 검증/유틸 | `doSegmentsIntersect`, `checkPolygonSelfIntersection`, `isValidPoints`, `isSamePoint`(<=2 tol) |
+| **659-1585** | **drawGableRoof** | 박공 (A/B 패턴) |
+| **1593-1672** | **drawShedRoof** | 한쪽흐름 |
+| **1680-5455** | **drawRoofByAttribute** | 변별 설정 (catch-all, ~3777줄) |
+| 5467-5493 | createArrow | (디버그/방향 화살표) |
+| 5501-5702 | 벡터/교점 헬퍼 | `lineIntersection`, `clamp01`, `isParallel`, `getBisectLines/BaseLines`, `almostEqual`, `getDirection`, `alreadyPoints` |
+| **5712-5841** | **drawing primitives** | `drawHipLine`, `drawRidgeLine`, `drawRoofLine` |
+| 5848-5883 | 벡터 정규화 | `normalizeVector`, `getHalfAngleVector` |
+| 5890-5936 | reDrawPolygon | polygon 재생성 |
+| 6167-6262 | 사이즈/변환 | `arePointsEqual`(<=1 tol), `toGeoJSON`, `calcLinePlaneSize`(×10 round), `calcLineActualSize`(/cos), `calcLineActualSize2`(tan, str return), `calcLineActualSizeByLineLength`, `createLinesFromPolygon` |
+| 6378-6507 | 정렬 | `getSortedOrthogonalPoints` (시계/반시계 방향 진행규칙 기반) |
+
+## 3. drawGableRoof — 박공 (659-1585)
+
+**입력 데이터**:
+- `roof` = `canvas.objects.find(id===roofId)` (POLYGON_TYPE.ROOF)
+- `wall` = `canvas.objects.find(name===POLYGON_TYPE.WALL && attributes.roofId===roofId)`
+- `baseLines = wall.baseLines.filter(planeSize>0)`
+- `eavesLines = baseLines.filter(type===WALLLINE.EAVES)`
+
+**내부 헬퍼** (모두 클로저):
+- `analyzeEavesLine(line)` — 처마 분석. horizontal/vertical/diagonal 분류 (tolerance 1°), `roofVector` (안쪽 향한 단위벡터), 매칭되는 roofLine 검색 (offset=0 이면 wall 자기 자신을 fallback)
+- `isOverlapLine(curr, check)` — 같은 방향 + 같은 좌표축 + range 겹침
+- `analyzeAllEavesLines(lines)` — `forwardLines`(directionVector x>0 또는 y>0) / `backwardLines` 분리, 같은 방향 겹침은 합병
+- `calculateIntersection(distance, angleA, angleB)` — `tan` 으로 마루 정점까지의 거리 분배
+- `findPloygonLineOverlap(polygon, linePoints)` — line 을 polygon 경계 안쪽으로 클립
+- `findInnerRidge(currentLine, roofVector, lines, tolerance=1)` — currentLine 안쪽에 있는 ridge 라인들을 거리 정렬해 ridge1/ridge2 매핑
+- `drawRoofPlane(currentLine)` — eaves 1개당 지붕면 1개 빌드
+
+**전체 흐름**:
+1. `analyzeAllEavesLines(eavesLines)` → forward/backward 페어 묶기
+2. `forwardLines.forEach`: backward 매칭 찾고 `calculateIntersection` 으로 각도별 정점 → `findPloygonLineOverlap` 으로 ridge 좌표 클립 → `drawRidgeLine` 호출 → `ridgeLines[]` 추가
+3. forward+backward 각각에 `drawRoofPlane` 호출 → 안쪽 ridge 와 inner roof line 매칭, `getSortedOrthogonalPoints` 정렬, 같은 방향이면 `drawRoofLine` 다른 방향이면 `drawHipLine` 호출 → `innerLines[]` 추가
+4. `roof.innerLines.push(...ridgeLines, ...innerLines)`
+5. `name==='check'` 디버그 객체 제거 + `canvas.renderAll()`
+
+## 4. drawShedRoof — 한쪽흐름 (1593-1672)
+
+**가드**: `roof.lines` 에 대각선(`|dx|>1 && |dy|>1`)이 있으면 **silent return** (alert 주석처리됨).
+
+**처리**:
+1. lines 를 `sheds` / `gables` / `eaves` 로 분리 (WALLLINE.SHED/GABLE/EAVES)
+2. shed 의 `pitch` 로 `shedDegree` 산출
+3. `gables.forEach`: `actualSize = calcLineActualSize(coord, shedDegree)` 갱신
+4. shed × eaves 페어마다 `pitchSizeLine` (중간축 점선) 생성 — `attributes.type='pitchSizeLine'`, dashArray `[5,5]`
+5. **최장 라인 1개만** canvas.add (다른 건 버림 — 의도된 동작인지 확인 필요)
+
+## 5. drawRoofByAttribute — 변별 설정 (1680-5455)
+
+**catch-all**. 박공/한쪽흐름이 아닌 모든 케이스 (요세무네, 맨사드, 형이동, 벽취합 혼합 등).
+
+**전반부 (1680-1759) 형이동 흡수 라인 병합**:
+- `wall.baseLines` 중 `planeSize<EPSILON` 인덱스를 `zeroLines[]` 로
+- 각 zero 라인의 prev/next 페어를 `mergedLines[]` 로
+- 같은 방향 vector 의 라인들을 `indexList` 합쳐 `[startLine.x1, startLine.y1, endLine.x2, endLine.y2]` 로 한 라인으로 압축, `setLength` fire
+- 결과 `baseLines` 재구성
+
+**중반부 (1766-...) 벽취합+offset 보강**:
+- `WALLLINE.WALL && offset>0` 인 currentLine 마다 prev/next 페어와 함께 roof.lines 의 대응 라인 찾고
+- `addRoofLine1`, `addRoofLine2` (corner extension) 을 `attributes.type=WALLLINE.ETC, name='addRoofLine'` 으로 추가
+
+**후반부 (~5380-5455)**:
+- `innerLines` 의 모든 끝점 수집 → `innerLinesPoints[]`
+- `roof.lines` 각 라인이 inner 와 겹치면 skip, 아니면 `splitPoint` 로 분할
+- splitPoint 첫번째: `drawHipLine(prevDegree)`, 그 다음: `drawRoofLine`, 마지막 splitPoint: `drawHipLine(nextDegree)`
+- 분할 없으면 `drawRoofLine` 1개
+- `roof.innerLines = innerLines` (덮어쓰기. drawGableRoof 의 push 와 다름!)
+- `name==='check'` 제거 + render
+
+## 6. Drawing primitives (5712-5841)
+
+세 함수 모두 `new QLine(points, {...})` 만들어 `canvas.add(line) → bringToFront() → renderAll()` 후 라인 객체 반환.
+
+| 함수 | name | stroke | actualSize 계산 | 비고 |
+|---|---|---|---|---|
+| `drawHipLine(points, canvas, roof, textMode, prevDegree, currentDegree)` | `SUBLINE.HIP` | `#1083E3` | prev===current 이면 `calcLineActualSize(points, currentDegree)`, 다르면 `0` | 대각선이면 hypotenuse/base/tan 로 prev·current degree 재산출 (`|degreeX-degreeY|<1` 일 때만 적용) |
+| `drawRidgeLine(points, canvas, roof, textMode)` | `SUBLINE.RIDGE` | `#1083E3` | `calcLinePlaneSize` (수평 거리 그대로) | actual==plane |
+| `drawRoofLine(points, canvas, roof, textMode)` | **`SUBLINE.HIP`** (의도적 재사용) | `#1083E3` | `calcLinePlaneSize` | hip 와 같은 name 으로 분류됨 — 대칭 hip 평균화 후처리에 영향 |
+
+**공통 attributes**: `{ roofId, planeSize, actualSize }`. parentId=roof.id, fontSize=roof.fontSize, strokeWidth=2.
+
+## 7. 데이터 모델 (수정 작업 시 핵심)
+
+### Wall/Roof QPolygon
+- `wall.baseLines`: `QLine[]`. 각 라인 `attributes`:
+  - `type`: `LINE_TYPE.WALLLINE.*` (EAVES, GABLE, SHED, WALL, JERKINHEAD, ETC, ...)
+  - `planeSize`, `actualSize`, `offset`, `pitch`
+  - `originPoint: { x1, y1, x2, y2 }` (offset 적용 전 원본)
+- `roof.lines`: 지붕 외곽 boundary 라인들 (offset 적용 후 또는 wall 동일)
+- `roof.innerLines`: 추녀/마루/지붕선 등 그려진 inner 라인 컬렉션 (drawHelpLine 시작 시 비워짐)
+
+### LINE_TYPE / POLYGON_TYPE (`src/common/common.js`)
+- `LINE_TYPE.WALLLINE`: DEFAULT, EAVES, EAVE_HELP_LINE, GABLE(+LEFT/RIGHT), WALL, HIPANDGABLE, JERKINHEAD, SHED, ETC
+- `LINE_TYPE.SUBLINE`: HIP(추녀), RIDGE(마루), GABLE, VERGE, ONESIDE_FLOW_RIDGE, YOSEMUNE, VALLEY, L_ABANDON_VALLEY, MANSARD, WALL_COLLECTION(+TYPE/FLOW/+L/R)
+- `POLYGON_TYPE`: ROOF, WALL, TRESTLE, MODULE_SETUP_SURFACE, MODULE, OBJECT_SURFACE
+
+## 8. 수정 작업 시 주의사항
+
+1. **drawHelpLine 진입 직후 innerLines 가 비워진다** (`QPolygon.js:489-505`). 즉 매번 from-scratch 그리기 — undo/redo 시도 마찬가지.
+2. **drawGableRoof 는 push, drawRoofByAttribute 는 덮어쓰기** — `roof.innerLines`. 일관성 없음.
+3. **drawShedRoof 의 silent return** — 대각선 케이스가 들어오면 아무것도 안 그린다. (이전엔 alert 였음)
+4. **drawRoofLine 의 name=SUBLINE.HIP** — 후처리(대칭 hip 평균화)에서 hip 로 분류됨. 의도적이지만 함정 포인트.
+5. **calcLinePlaneSize 는 ×10 round** — 모든 사이즈가 10배 정수로 저장됨 (mm 단위). UI 표시 시 /10.
+6. **tolerance 들이 다 다름**:
+   - `EPSILON=1e-10` 수학 비교
+   - 방향 분류 1° / 1px
+   - `arePointsEqual` 1px / `isSamePoint` 2px
+   - 후처리 hip 평균화 5mm
+   - SHOULDER_ABSORBED 임계 < 10 (별도 메모리 참조)
+7. **wall.baseLines 의 zero-length 라인** = 형이동 흡수 결과. drawRoofByAttribute 만 합병 처리. 다른 두 함수는 `planeSize>0` 으로 필터만 함.
+8. **`name==='check'` 객체** = 디버그 화살표/마커. 모든 draw 함수가 마지막에 제거.
+9. **skeleton-utils.js (5227줄)** 는 별도 파일. 용마루(전체 EAVES) 케이스 전용. qpolygon-utils 와 데이터 모델 일부 공유하지만 로직 독립.
+10. **현재 브랜치 `feature/redo-undo`** — 최근 커밋 3개가 모두 지붕 형상 undo/redo 관련. 수정 시 history 정합성 영향 고려 필요.
+
+## 9. 권장 작업 순서
+
+지붕 생성 로직 수정 시:
+1. 어떤 케이스(박공/한쪽흐름/변별) 가 영향 받는지 먼저 식별 (`isGableRoof`/`isShedRoof` 분기 추적)
+2. 해당 함수의 입력 데이터 (wall.baseLines / roof.lines) 의 invariant 확인 — `planeSize>0` 필터링 여부, type 분포
+3. drawing primitive (drawHip/Ridge/RoofLine) 의 attributes 가 후처리(hip 평균화, lengthText 표시) 와 정합 유지하는지 확인
+4. drawHelpLine 호출 7곳 모두에서 동작 검증 (특히 `useMovementSetting`, `useRoofShapeSetting`)
+5. undo/redo 의 경우 `roof.innerLines` 가 매 재호출마다 from-scratch 라는 점 유의 (history snapshot 은 wall.baseLines/roof.lines 만으로 결정적)

.claude/memory/project_skeleton_utils_ridge_roof.md

@@ -0,0 +1,77 @@
+---
+name: skeleton-utils 용마루 지붕 두 경로 차이
+description: src/util/skeleton-utils.js 의 drawSkeletonRidgeRoof(일반) vs drawSkeletonRidgeRoofFromBaseLines(오버 전용) 차이 + skeletonBuilder 전처리 파이프라인 + SK_INPUT_USE_WALL_BASELINE_DIRECT 플래그. 용마루(전체 EAVES) 케이스 수정 전 reference.
+type: project
+---
+
+# skeleton-utils 용마루 지붕 — 일반 vs 오버 두 경로
+
+`src/util/skeleton-utils.js`. **용마루 지붕(라인 type 이 전부 EAVES)** 케이스 전용. straight-skeleton(`SkeletonBuilder.BuildFromGeoJSON`)으로 용마루/추녀 내부선 생성. 박공/한쪽흐름/변별은 `qpolygon-utils.js` 가 담당 (별도 메모리 참조: [[qpolygon-utils 지붕 생성 구조]]).
+
+## 1. 분기 (QPolygon.js:677-684)
+
+`drawHelpLine` 에서 `types.every(EAVES)` 일 때:
+
+```
+verdict = verifyMoveBoundary(this.id, this.canvas)
+if verdict === 'crossed':  drawSkeletonRidgeRoofFromBaseLines  ← 오버(경계 넘음) 전용
+else:                      drawSkeletonRidgeRoof               ← 일반
+```
+
+`'crossed'` = 마루/벽 이동이 roof 경계를 넘어선 "오버" 상태. wall.baseLines 가 이미 오버된 좌표로 mutate 됨.
+
+## 2. drawSkeletonRidgeRoof (일반, :71-75)
+
+```js
+export const drawSkeletonRidgeRoof = (roofId, canvas, textMode) => {
+  skeletonBuilder(roofId, canvas, textMode)   // 얇은 래퍼
+}
+```
+
+실체는 `skeletonBuilder` (:922). 전처리 파이프라인:
+1. roof.lines ↔ wall.lines index 매칭으로 `wallLine` id 주입
+2. `baseLines = wall.baseLines.filter(planeSize>0)`, `createOrderedBasePoints` 로 roof.points 순서 정렬
+3. **45° 대각 확장 계산** (:1011-1066): contactData(baseLine→roofLine 방향벡터) → `maxStep`(전체 꼭짓점 중 min(|dx|,|dy|) 의 max) → centroid 보정 → `changRoofLinePoints` (maxContactDistance=√2·maxStep 확장)
+4. 마루이동(`moveFlowLine`/`moveUpDown` ≠ 0) 시 `safeMovedPointsWithFallback` 의 `movedPoints` 로 대체 (:1071-1121)
+5. **⚠️ `SK_INPUT_USE_WALL_BASELINE_DIRECT = true` (:36, :1128)** → 위 3·4 결과를 **전부 무시**하고 `orderedBaseLinePoints`(=wall.baseLines corner) 직접 사용. + 평행오버 corner 흡수(DUP_EPS=1.0, COLLINEAR_EPS=50.0, 최대 5패스)
+6. 좌표 유효성/중복점/일직선/**방향 뒤집힘(isOverDetected, cross product 부호 반전)** 검출 (:1175-1236)
+7. `roof.skeletonPoints` 갱신 → SK 빌드 → `createInnerLinesFromSkeleton`
+
+즉 45° 확장 코드는 **계산만 하고 버려지는** 상태(점진 리팩토링 흔적). 실입력은 baseLines corner.
+
+## 3. drawSkeletonRidgeRoofFromBaseLines (오버 전용, :1363-1444)
+
+헤더 주석(:1350-1362) 의 존재 이유: 일반 경로의 45° 확장/roof 경계 클램핑이 오버 상태에선 **폴리곤 자가교차/경계 되돌림**을 일으켜 엉뚱한 SK 를 만든다 → 전처리 다 건너뛰고 baseLines 그대로 입력.
+
+처리:
+1. `wall.baseLines` 순차 끝점(`{x:bl.x1, y:bl.y1}`) 수집, **확장·offset 없이 그대로**. `planeSize<1`(SHOULDER_ABSORBED) 스킵
+2. rawPoints < 3 이면 중단
+3. `roof.skeletonPoints = rawPoints` (오버 좌표 그대로)
+4. `perturbPolygonPoints` → `toGeoJSON` → `SkeletonBuilder.BuildFromGeoJSON`
+5. `createInnerLinesFromSkeleton(..., isOverDetected=true, rawPoints)`
+6. `canvas.skeletonStates[roofId]=true`, `canvas.skeletonLines` 갱신
+7. **`canvas.skeleton.lastPoints` 는 기존 값 보존** (`__preservedLastPoints`) — 오버 상태에서 새 누적 기준점 안 만듦
+
+**건드리지 않는 것**: `roof.points` / `roof.lines` / `outerLine` / `lengthText` (주석 :1358 명시).
+
+## 4. 핵심 차이 요약
+
+| 항목 | drawSkeletonRidgeRoof (일반) | ...FromBaseLines (오버) |
+|---|---|---|
+| 트리거 | EAVES 전부 + verdict ≠ crossed | EAVES 전부 + verdict === crossed |
+| 실체 | skeletonBuilder 래퍼 | 자체 SK 빌드 |
+| SK 입력 | 전처리 파이프라인(but 플래그로 baseLine 직접) | baseLines 끝점 그대로 |
+| roof.points/lines/outerLine/lengthText | 마루이동 시 갱신·검증 | **불변 (side-effect free)** |
+| lastPoints | 새로 계산/누적 | **보존** |
+| isOverDetected | cross 부호 반전 검출로 산출 | 무조건 true 마킹 |
+| 공통 | createInnerLinesFromSkeleton, planeSize<1 스킵 | 동일 |
+
+**현 시점 진짜 차이**: 플래그(`SK_INPUT_USE_WALL_BASELINE_DIRECT=true`) 때문에 두 함수의 SK 입력 좌표는 거의 같아짐. 실질 차이는 **주변 상태(roof.points/lastPoints 등) 를 mutate 하느냐 보존하느냐**. 오버를 undo/redo 단축수단으로 쓸 때 history snapshot(wall.baseLines/roof.lines) 오염 없이 SK 만 재그리기 위함 (현재 `feature/redo-undo` 브랜치 맥락).
+
+## 5. 수정 시 주의
+
+1. **45° 확장 코드(:1011-1066) 는 dead 입력** — `SK_INPUT_USE_WALL_BASELINE_DIRECT` 끄지 않는 한 결과 미사용. 만지기 전 플래그 확인.
+2. `createInnerLinesFromSkeleton` (:1455) 은 두 경로 공유 — 여기 바꾸면 양쪽 영향. `processEavesEdge`(처마) + `processGableEdge`(케라바 후처리) 호출.
+3. 오버 경로는 `lastPoints` 보존이 의도 — 무심코 갱신하면 누적 마루이동 기준 붕괴.
+4. 예외 시 보호 정책(:1341-1346): SK/innerLines 유지, `skeletonStates[roofId]=false` 만, `skeletonLines` 비우지 않음 (이전 성공 상태 보존).
+5. `verifyMoveBoundary` 는 QPolygon.drawHelpLine 과 skeletonBuilder(:1077) **두 곳에서** 호출 — 'crossed' 시 경고 로그만, 흐름은 진행.

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "CMD=$(python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('tool_input',d).get('command',''))\" 2>/dev/null || true); set -- $CMD; case \"$1\" in grep|egrep|fgrep|rg|ripgrep|find|fd|ack|ag) [ -f graphify-out/graph.json ] && echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files.\"}}' || true ;; esac"
+          }
+        ]
+      }
+    ]
+  }
+}

.codex/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "CMD=$(python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('tool_input',d).get('command',''))\" 2>/dev/null || true); set -- $CMD; case \"$1\" in grep|egrep|fgrep|rg|ripgrep|find|fd|ack|ag) [ -f graphify-out/graph.json ] && echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files.\"}}' || true ;; esac"
+          }
+        ]
+      }
+    ]
+  }
+}