-
- {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/.agents/skills/next-best-practices/debug-tricks.md b/.agents/skills/next-best-practices/debug-tricks.md
deleted file mode 100644
index 9151ce66..00000000
--- a/.agents/skills/next-best-practices/debug-tricks.md
+++ /dev/null
@@ -1,105 +0,0 @@
-# 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/.agents/skills/next-best-practices/file-conventions.md b/.agents/skills/next-best-practices/file-conventions.md
deleted file mode 100644
index c2b3b406..00000000
--- a/.agents/skills/next-best-practices/file-conventions.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# 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/.agents/skills/next-best-practices/font.md b/.agents/skills/next-best-practices/font.md
deleted file mode 100644
index 7e526850..00000000
--- a/.agents/skills/next-best-practices/font.md
+++ /dev/null
@@ -1,245 +0,0 @@
-# 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/.agents/skills/next-best-practices/functions.md b/.agents/skills/next-best-practices/functions.md deleted file mode 100644 index 8f28a8b6..00000000 --- a/.agents/skills/next-best-practices/functions.md +++ /dev/null @@ -1,108 +0,0 @@ -# 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/.agents/skills/next-best-practices/hydration-error.md b/.agents/skills/next-best-practices/hydration-error.md deleted file mode 100644 index 36d48295..00000000 --- a/.agents/skills/next-best-practices/hydration-error.md +++ /dev/null @@ -1,91 +0,0 @@ -# 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/.agents/skills/next-best-practices/image.md b/.agents/skills/next-best-practices/image.md
deleted file mode 100644
index aa9d28db..00000000
--- a/.agents/skills/next-best-practices/image.md
+++ /dev/null
@@ -1,173 +0,0 @@
-# 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/.agents/skills/next-best-practices/parallel-routes.md b/.agents/skills/next-best-practices/parallel-routes.md
deleted file mode 100644
index 51e270d8..00000000
--- a/.agents/skills/next-best-practices/parallel-routes.md
+++ /dev/null
@@ -1,287 +0,0 @@
-# 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/.agents/skills/next-best-practices/runtime-selection.md b/.agents/skills/next-best-practices/runtime-selection.md
deleted file mode 100644
index cec960d7..00000000
--- a/.agents/skills/next-best-practices/runtime-selection.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# 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/.agents/skills/next-best-practices/scripts.md b/.agents/skills/next-best-practices/scripts.md
deleted file mode 100644
index 4eeb744c..00000000
--- a/.agents/skills/next-best-practices/scripts.md
+++ /dev/null
@@ -1,141 +0,0 @@
-# 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}
-
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/.agents/skills/next-best-practices/route-handlers.md b/.agents/skills/next-best-practices/route-handlers.md
deleted file mode 100644
index 25e6f4d7..00000000
--- a/.agents/skills/next-best-practices/route-handlers.md
+++ /dev/null
@@ -1,146 +0,0 @@
-# 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