-
+ {users.map(user =>
- {user.name} )} +
...
;
+}
+```
+
+### 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 ...
;
+}
+```
+
+### Solution 2: Streaming with Suspense
+
+```tsx
+// Good: Show content progressively
+import { Suspense } from 'react';
+
+async function Dashboard() {
+ return (
+
+
+ );
+}
+
+async function UserSection() {
+ const user = await getUser(); // Fetches independently
+ return {user.name}
;
+}
+
+async function PostsSection() {
+ const posts = await getPosts(); // Fetches independently
+ return {user.name}
;
+}
+```
+
+## 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 {data.value}
;
+}
+```
+
+### 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 {data?.value}
;
+}
+```
+
+**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 |
diff --git a/.agent/skills/next-best-practices/debug-tricks.md b/.agent/skills/next-best-practices/debug-tricks.md
new file mode 100644
index 000000000..9151ce66c
--- /dev/null
+++ b/.agent/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:
+
+ )
+}
+```
+
+**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 (
+
+
+ Something went wrong!
+ +Something went wrong!
+ + + + ) +} +``` + +**Important:** Must include `` and `` 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) + } + + returnYou don't have access to this resource
+}
+
+// app/unauthorized.tsx
+export default function Unauthorized() {
+ return Please log in to continue
+}
+```
+
+## Not Found
+
+### `not-found.tsx`
+
+Custom 404 page for a route segment:
+
+```tsx
+export default function NotFound() {
+ return (
+
+
+ )
+}
+```
+
+### 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 Not Found
+Could not find the requested resource
+{post.title}
+}
+```
+
+## 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
+```
diff --git a/.agent/skills/next-best-practices/file-conventions.md b/.agent/skills/next-best-practices/file-conventions.md
new file mode 100644
index 000000000..c2b3b4069
--- /dev/null
+++ b/.agent/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 proxyConfig = {
+ matcher: ['/dashboard/:path*', '/api/:path*'],
+};
+```
+
+| Version | File | Export | Config |
+|---------|------|--------|--------|
+| v14-15 | `middleware.ts` | `middleware()` | `config` |
+| v16+ | `proxy.ts` | `proxy()` | `proxyConfig` |
+
+**Migration**: Run `npx @next/codemod@latest upgrade` to auto-rename.
+
+## File Conventions Reference
+
+Reference: https://nextjs.org/docs/app/api-reference/file-conventions
diff --git a/.agent/skills/next-best-practices/font.md b/.agent/skills/next-best-practices/font.md
new file mode 100644
index 000000000..7e5268509
--- /dev/null
+++ b/.agent/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 (
+
+ {children}
+
+ )
+}
+```
+
+## 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 (
+
+ {children}
+
+ )
+}
+```
+
+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 (
+
+ {children}
+
+ )
+}
+```
+
+```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 `` tags for Google Fonts.
+
+```tsx
+// Bad: Manual link tag (blocks rendering, no optimization)
+
+
+// Bad: Missing display and preconnect
+
+
+// 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 {children}
+} +``` diff --git a/.agent/skills/next-best-practices/functions.md b/.agent/skills/next-best-practices/functions.md new file mode 100644 index 000000000..8f28a8b67 --- /dev/null +++ b/.agent/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 `` tags. + +```tsx +// Bad: Plain anchor tag +About + +// Good: Next.js Link +import Link from 'next/link' + +About +``` + +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 ( + + {children} + + ) +} +``` + +### 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 }) +} +``` diff --git a/.agent/skills/next-best-practices/hydration-error.md b/.agent/skills/next-best-practices/hydration-error.md new file mode 100644 index 000000000..36d48295b --- /dev/null +++ b/.agent/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 +{window.innerWidth}
+
+// 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
+{new Date().toLocaleString()}
+
+// Good: Render on client only
+'use client'
+const [time, setTime] = useState
+
+// Good: Use useId hook
+import { useId } from 'react'
+
+function Input() {
+ const id = useId()
+ return
+}
+```
+
+### Invalid HTML Nesting
+
+```tsx
+// Bad: Invalid - div inside p
+
+```
+
+### 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 (
+
+ )
+}
+```
diff --git a/.agent/skills/next-best-practices/image.md b/.agent/skills/next-best-practices/image.md
new file mode 100644
index 000000000..aa9d28db9
--- /dev/null
+++ b/.agent/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
+
+
+// Good: Use next/image
+import Image from 'next/image'
+ {
+ 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(
+ (
+ {
+ 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.
diff --git a/.agent/skills/next-best-practices/parallel-routes.md b/.agent/skills/next-best-practices/parallel-routes.md
new file mode 100644
index 000000000..51e270d82
--- /dev/null
+++ b/.agent/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 (
+
+
+ {children}
+ {modal}
+
+
+ );
+}
+```
+
+## 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 (
+
+ 
+
+ );
+}
+```
+
+## 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 (
+ (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 (
+
+
+
+ );
+}
+```
+
+## 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 (
+ }) {
+ return
+}
+```
+
+## 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 | - |
diff --git a/.agent/skills/next-best-practices/runtime-selection.md b/.agent/skills/next-best-practices/runtime-selection.md
new file mode 100644
index 000000000..cec960d76
--- /dev/null
+++ b/.agent/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.
diff --git a/.agent/skills/next-best-practices/scripts.md b/.agent/skills/next-best-practices/scripts.md
new file mode 100644
index 000000000..4eeb744c8
--- /dev/null
+++ b/.agent/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 `
+
+// Good: Next.js Script component
+import Script from 'next/script'
+
+
+```
+
+## Inline Scripts Need ID
+
+Inline scripts require an `id` attribute for Next.js to track them.
+
+```tsx
+// Bad: Missing id
+
+
+// Good: Has id
+
+
+// Good: Inline with id
+
+```
+
+## 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'
+
+
+
+
+
+// Good: Script outside Head
+
+ Page
+
+
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+
+
+// lazyOnload - Load during idle time
+
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+
+
+// worker - Load in web worker (experimental)
+
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+
+
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+ return (
+
+ {children}
+ Page
+
+
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+
+
+// lazyOnload - Load during idle time
+
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+
+
+// worker - Load in web worker (experimental)
+
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+
+
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+ return (
+
+ {children}
+ Page
+
+
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+
+
+// lazyOnload - Load during idle time
+
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+
+
+// worker - Load in web worker (experimental)
+
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+
+
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+ return (
+
+ {children}
+ Page
+
+
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+
+
+// lazyOnload - Load during idle time
+
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+
+
+// worker - Load in web worker (experimental)
+
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+
+
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+ return (
+
+ {children}
+ Page
+
+
+```
+
+## Loading Strategies
+
+```tsx
+// afterInteractive (default) - Load after page is interactive
+
+
+// lazyOnload - Load during idle time
+
+
+// beforeInteractive - Load before page is interactive (use sparingly)
+// Only works in app/layout.tsx or pages/_document.js
+
+
+// worker - Load in web worker (experimental)
+
+```
+
+## Google Analytics
+
+Use `@next/third-parties` instead of inline GA scripts.
+
+```tsx
+// Bad: Inline GA script
+
+
+
+// Good: Next.js component
+import { GoogleAnalytics } from '@next/third-parties/google'
+
+export default function Layout({ children }) {
+ return (
+
+ {children}
+
Content
+
+// Bad: Invalid - p inside p
+Nested
+ +// Good: Valid nesting +Content
+
+// Good: Use next/image
+import Image from 'next/image'
+
+
+```
+
+## 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
+
+ Hello World
+
+ ),
+ { ...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(
+ (
+
+
+ ),
+ { ...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(
+ (
+ {post.title}
+ {post.description}
+
+ Custom Font Text
+
+ ),
+ {
+ 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
+
+
+ );
+}
+```
+
+## Step 5: Modal Component with Correct Closing
+
+**Critical: Use `router.back()` to close modals, NOT `router.push()` or ``.**
+
+```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{photo.title}
+
+
+ );
+}
+```
+
+### Why NOT `router.push('/')` or ``?
+
+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 (
+
+
+ {children}
+
+
+ {photos.map(photo => (
+
+ 
+
+ ))}
+
+ );
+}
+```
+
+Clicking a photo → Modal opens (intercepted)
+Direct URL → Full page renders
+Refresh while modal open → Full page renders
diff --git a/.agent/skills/next-best-practices/route-handlers.md b/.agent/skills/next-best-practices/route-handlers.md
new file mode 100644
index 000000000..25e6f4d79
--- /dev/null
+++ b/.agent/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({user.name}
+}
+
+// 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 {user.name}
+}
+```
+
+```tsx
+// Bad: async arrow function client component
+'use client'
+const Dashboard = async () => {
+ const data = await fetchDashboard()
+ return {data}
+}
+
+// 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