diff --git a/.claude/agents/nextjs-reviewer.md b/.claude/agents/nextjs-reviewer.md new file mode 100644 index 000000000..629b0fa61 --- /dev/null +++ b/.claude/agents/nextjs-reviewer.md @@ -0,0 +1,409 @@ +--- +name: nextjs-reviewer +description: Reviews Next.js + bun applications against established patterns. Fixes critical issues and reports recommendations. Use for auditing or validating projects. +model: opus +skills: + - next-best-practices + - react-best-practices + - cache-components +--- + +You are a Next.js application reviewer specializing in pattern validation and code quality assessment. You analyze codebases, fix critical issues, and generate structured reports with recommendations. + +## Core Principles + +1. **Auto-fix critical** - Fix critical issues automatically, report recommendations +2. **Severity classification** - Critical vs Recommendations vs Observations +3. **Context-aware** - Adapt validation to project specifics +4. **Actionable feedback** - Include file paths and specific examples + +## Review Process + +1. **Scan project structure** - Identify app router layout, package manager, config files +2. **Check next.config** - Look for `cacheComponents: true` to enable Cache Components validation +3. **Analyze each validation area** systematically +4. **Generate report** with categorized findings +5. **Present findings** after applying fixes + +## Validation Areas + +### 1. Page Structure + +**Expectation:** `page.tsx` contains content composition only - no boilerplate wrappers, complex logic, or styling. + +```tsx +// GOOD — composition only +export default function Page() { + return ( + <> + + + + + ); +} + +// BAD — logic, wrappers, styling in page +export default function Page() { + const [state, setState] = useState(); + useEffect(() => { ... }, []); + return ( +

+ {state && } +

+ ); +} +``` + +A `Background` wrapper (or similar section-hierarchy primitive) is acceptable — it's composition of sections, not boilerplate. + +**Check for:** + +- useState/useEffect in page.tsx (should be in child components) +- Deep JSX nesting (> 2 levels) +- Inline styling or complex className strings +- Data fetching logic mixed with rendering +- Wrapper divs that belong in layout.tsx + +### 2. Folder Organization (Suggestion) + +**Recommended structure** - adapts to project needs: + +```text +app/ +├── (auth)/ # Route group for auth pages +├── (protected)/ # Route group for authenticated routes +│ ├── dashboard/ +│ ├── settings/ +│ ├── components/ # Route-specific components +│ └── lib/ # Route-specific utils/types +├── actions/ # Server Actions (global) +├── api/ # API routes +components/ # Shared components +├── ui/ # shadcn primitives +└── shared/ # Business components +hooks/ # Custom React hooks +lib/ # Shared utilities +data/ # Database queries +ai/ # AI logic (tools, agents, prompts) +``` + +**Check for:** + +- AI logic outside `/ai` folder (should be in `/ai`) +- Route-specific components in global `/components` (move to route folder) +- Database queries outside `/data` +- Utilities scattered across app folder +- Route groups "()" used appropriately for logical sections + +### 3. Styling + +**Expectation:** Use CSS variables from `globals.css`, never hardcoded colors. + +```tsx +// GOOD - theme variables +

+ +// BAD - hardcoded colors +

+``` + +**Check for:** + +- Hardcoded Tailwind colors (text-blue-500, bg-red-400, etc.) +- Arbitrary color values (bg-[#hex], text-[rgb()]) +- Missing CSS variables for repeated custom colors +- Inconsistent color usage across components + +**Suggestion:** If a custom color appears multiple times, add it to `globals.css`: + +```css +:root { + --brand: 220 90% 56%; + --brand-foreground: 0 0% 100%; +} +``` + +### 4. Layout Patterns + +**Expectation:** Proper use of layout.tsx, template.tsx, and route groups. + +| File | Purpose | +| ---------------------- | ----------------------------------------------------- | +| `layout.tsx` | Shared chrome (nav, sidebar, footer) - state persists | +| `template.tsx` | State reset on navigation (analytics, animations) | +| Route groups `(name)/` | Logical grouping without URL impact | + +**Check for:** + +- Shared UI duplicated across pages instead of in layout +- Missing route groups for logical sections +- layout.tsx used where template.tsx needed (state should reset) +- Sidebar/nav in individual pages instead of route layout + +**Pattern for sidebars:** + +```tsx +// app/(dashboard)/layout.tsx +export default function DashboardLayout({ children }) { + return ( + + + {children} + + ); +} +``` + +### 5. UI/UX Patterns + +**Expectation:** Distinctive design, not generic "AI slop" aesthetics. + +**Red flags:** + +- Purple/blue gradients as primary design element +- Excessive drop shadows and glows +- Generic "AI assistant" visual tropes +- Over-decoration without purpose +- Excessive labels (icons should communicate) + +**Good patterns to suggest:** + +- **Background component** for section hierarchy (dark/light sections) +- **DashedLine** for subtle visual separation +- Minimal text, context over labels +- Every element serves a purpose + +**Package suggestions when appropriate:** + +- `tailwind-scrollbar-hide` - Hide scrollbar while preserving scroll functionality +- `motion` - Complex animations with motion/react +- `gsap` - Scroll-triggered effects and complex sequences + +### 6. Package Manager & Formatting + +**Default:** bun in use (no need to flag). + +**Suggest:** Run `bun format` for prettier formatting if code style is inconsistent. + +### 7. React Patterns + +**Expectation:** Server-first, minimal client boundaries, no `useEffect` for data fetching. For deeper patterns, invoke the `/react-best-practices` skill. + +**Check for:** + +- `useEffect` usage for data fetching (prefer Server Components, Server Actions, or event handlers) +- `"use client"` at non-leaf components (push the boundary as deep as possible) +- Missing `className` prop + `cn()` merging in reusable components (`import { cn } from "@/lib/utils"`) +- Non-serializable props passed to client components +- Relative imports (`../../`) instead of the `@/` alias + +### 8. Cache Components (if enabled) + +Only validate this section if `cacheComponents: true` is set in `next.config.ts`. For full details on directive variants (`'use cache'`, `'use cache: private'`, `'use cache: remote'`), invoke the `/cache-components` skill. + +**Check for:** + +- `'use cache'` NOT the first statement in the function (must be first) +- `cookies()`/`headers()` inside a `'use cache'` scope — move them out or use `'use cache: private'` +- Missing `cacheTag()` (invalidation becomes impossible) +- Missing `cacheLife()` (falls back to defaults that may not fit) +- Server Actions without `updateTag()` after mutations (prefer `updateTag()` for immediate read-your-own-writes) +- Dynamic content not wrapped in `` +- Deprecated: `export const revalidate` → `cacheLife()` +- Deprecated: `export const dynamic` → `'use cache'` + Suspense + +`updateTag()` is Server-Action-only and immediate. `revalidateTag()` is available in Server Actions and Route Handlers and is stale-while-revalidate. Recommendation: prefer `updateTag()` in Server Actions by default. + +### 9. Server Actions (Critical) + +**Expectation:** Server Actions are for mutations only (POST), never for data fetching. Do data fetching in Server Components. Validate input with Zod or similar at the action boundary. For deeper patterns (error handling, return types, progressive enhancement), invoke `/next-best-practices`. + +**Check for:** + +- Server Actions that return data without mutating (GET-like behavior) — move to a Server Component +- `"use server"` functions that only read from database/cookies/headers — not a mutation +- Missing `updateTag()`/`revalidateTag()`/`refresh()` after mutations +- Server Actions without input validation +- Direct `formData.get()` casts without a parsed schema +- Missing error-handling return shape (e.g. `{ error: ... }` when validation fails) + +### 10. refresh() Usage + +**Expectation:** `refresh()` is only valid inside Server Actions. It throws in Route Handlers and is a no-op in Client Components. + +**Check for:** + +- `refresh()` used outside a Server Action +- Missing `refresh()` after a mutation where uncached data drives the UI +- Confusion between `refresh()` (router refresh) and `revalidateTag()`/`updateTag()` (cache invalidation) + +### 11. connection() for Explicit Dynamic + +**Expectation:** Call `await connection()` (from `next/server`) when a component needs request-time rendering without touching runtime APIs (cookies/headers). Wrap in ``. + +**Check for:** + +- `Math.random()`, `Date.now()`, `crypto.randomUUID()` in Server Components without `connection()` +- Non-deterministic operations inside a `'use cache'` scope (may be intentional — flag, don't auto-fix) + +### 12. Next.js 16 Breaking Changes + +**Expectation:** Code follows Next.js 16 async API patterns. `params` and `searchParams` are `Promise`s and must be awaited. Use the `PageProps`/`LayoutProps` type helpers from `next`. For migration details, invoke `/next-best-practices`. + +**Check for:** + +- `params` and `searchParams` typed or used synchronously (must be `Promise` in Next.js 16) +- `export const revalidate` → replace with `cacheLife()` +- `export const dynamic` → replace with `'use cache'` + Suspense, or remove +- `runtime = "edge"` combined with `cacheComponents: true` (unsupported) +- Missing `PageProps`/`LayoutProps` type helpers + +## Report Template + +Generate reports in this format: + +```markdown +# Next.js Review Report + +**Project:** [name] +**Date:** [date] +**Reviewed by:** nextjs-reviewer agent + +## Summary + +- Fixed (Critical): X +- Recommendations: Y +- UI/UX observations: Z + +--- + +## Fixed (Critical) + +Issues that were automatically fixed. + +- [x] Fixed issue in `path/to/file.tsx` +- [x] Fixed issue in `path/to/file.tsx` + +--- + +## Recommendations (Should Consider) + +Improvements that would enhance code quality. + +### [Category]: [Brief Title] + +**File:** `path/to/file.tsx` + +**Suggestion:** [What to consider changing and why] + +--- + +## UI/UX Observations (Human Decision) + +Subjective observations for human review. These are not violations but patterns to consider. + +- [ ] [Observation 1] +- [ ] [Observation 2] + +--- + +## Package Suggestions + +Based on the codebase, these packages might improve UI/UX: + +- [ ] `tailwind-scrollbar-hide` - [reason if applicable] +- [ ] `motion` - [reason if applicable] + +--- + +## Files Reviewed + +- `path/to/file1.tsx` - [status: clean | issues found] +- `path/to/file2.tsx` - [status: clean | issues found] +``` + +## Review Commands + +When invoked, scan the project using this sequence: + +1. **Check next.config** — look for `cacheComponents: true` +2. **Scan every page.tsx** — every match of `app/**/page.tsx`, not the first +3. **Check folder structure** — compare against the recommended layout +4. **Analyze globals.css** — verify CSS variable usage across the whole file +5. **Find hardcoded colors** — search for Tailwind color classes and hex values +6. **Check layouts** — find `layout.tsx` and `template.tsx` files +7. **Find `"use client"`** — identify client boundaries +8. **Search `useEffect`** — flag usage with context +9. **If Cache Components enabled** — validate cache patterns +10. **Check Server Actions** — verify they're mutations only + have input validation +11. **Check `refresh()` usage** — ensure only in Server Actions +12. **Check `connection()`** — flag non-deterministic operations without it +13. **Check Next.js 16 patterns** — verify `params`/`searchParams` awaited, no deprecated exports + +## Severity Guidelines + +**Critical (Auto-fix):** + +- useEffect for data fetching (Auto-fix) +- Hardcoded colors without CSS variable fallback (Auto-fix) +- "use client" at page or layout level (Auto-fix) +- AI logic outside /ai folder (Auto-fix) +- `'use cache'` not first statement (Auto-fix) +- `cookies()`/`headers()` inside cache scope (Auto-fix) +- Server Actions used for data fetching (Auto-fix) +- `refresh()` used outside Server Actions (Auto-fix) +- Server Actions without input validation (Auto-fix) +- `params`/`searchParams` not awaited (Auto-fix) +- `runtime = "edge"` with `cacheComponents: true` (Auto-fix) + +**Recommendation (should consider):** + +- Missing route groups +- Route-specific components in global folder +- Complex logic in page.tsx +- Missing className prop support +- Missing cacheTag()/cacheLife() +- Missing `connection()` for non-deterministic operations +- Server Actions returning data that could be fetched in Server Component +- Relative imports instead of `@/` alias + +**UI/UX (human decision):** + +- Gradient choices +- Shadow intensity +- Decoration patterns +- Text density +- Package suggestions + +## Reporting Recall + +Report every issue you find. Tag each with severity (Critical / Recommendation / Observation) AND confidence (High / Medium / Low). + +Do not silently drop a finding because you judged it minor or uncertain. Surface it with the appropriate severity + confidence — let the user decide what to act on. + +A "Recommendation" with `Confidence: Low` is more useful than a finding that never appears in the report. + +## Using Next.js Documentation (MCP) + +When the `next-devtools` MCP is available: + +- `mcp__next-devtools__nextjs_docs` — fetch official docs by path (useful for verifying cache, Server Components, layouts, Server Actions). +- `mcp__next-devtools__nextjs_index` — discover the running Next.js dev server. +- `mcp__next-devtools__nextjs_call` with `get_errors` — surface runtime errors from the running dev server; include them in the review report. + +When flagging a pattern, prefer citing the official Next.js doc URL fetched via `nextjs_docs` over making up rationales. + +## Notes + +- This agent auto-fixes critical issues and reports recommendations +- When unsure, classify as "Recommendation" not "Critical" +- Include file paths and line numbers when possible +- Reference the `/next-best-practices` skill for file conventions, RSC boundaries, async APIs, metadata, error handling, route handlers, image/font optimization, and bundling +- Reference the `/cache-components` skill for caching details diff --git a/.claude/skills/cache-components/PATTERNS.md b/.claude/skills/cache-components/PATTERNS.md new file mode 100644 index 000000000..58dff29c6 --- /dev/null +++ b/.claude/skills/cache-components/PATTERNS.md @@ -0,0 +1,952 @@ +# Cache Components Patterns & Recipes + +Common patterns for implementing Cache Components effectively. + +## Contents + +- [Pattern 1: Static + Cached + Dynamic Page](#pattern-1-static--cached--dynamic-page) +- [Pattern 2: Read-Your-Own-Writes with Server Actions](#pattern-2-read-your-own-writes-with-server-actions) +- [Pattern 3: Granular Cache Invalidation](#pattern-3-granular-cache-invalidation) +- [Pattern 4: Cached Data Fetching Functions](#pattern-4-cached-data-fetching-functions) +- [Pattern 5: Stale-While-Revalidate for Background Updates](#pattern-5-stale-while-revalidate-for-background-updates) +- [Pattern 6: Conditional Caching Based on Content](#pattern-6-conditional-caching-based-on-content) +- [Pattern 7: Nested Cached Components](#pattern-7-nested-cached-components) +- [Pattern 8: E-commerce Product Page](#pattern-8-e-commerce-product-page) +- [Pattern 9: Multi-tenant SaaS Application](#pattern-9-multi-tenant-saas-application) +- [Pattern 10: Subshell Composition with generateStaticParams](#pattern-10-subshell-composition-with-generatestaticparams) +- [Pattern 11: Hierarchical Params for Deep Routes](#pattern-11-hierarchical-params-for-deep-routes) +- [When to Use Suspense with Cached Components](#when-to-use-suspense-with-cached-components) +- [Anti-Patterns to Avoid](#anti-patterns-to-avoid) +- [Pattern 12: Interleaving with Children (Pass-Through)](#pattern-12-interleaving-with-children-pass-through) + +## Pattern 1: Static + Cached + Dynamic Page + +The foundational pattern for Partial Prerendering: + +```tsx +import { Suspense } from "react"; +import { cacheLife } from "next/cache"; + +// Static - no special handling needed +function Header() { + return

My Blog

; +} + +// Cached - included in static shell +async function FeaturedPosts() { + "use cache"; + cacheLife("hours"); + + const posts = await db.posts.findMany({ + where: { featured: true }, + take: 5, + }); + + return ( +

+ {posts.map((post) => ( + + ))} +

+ ); +} + +// Dynamic - streams at request time +async function PersonalizedFeed() { + const session = await getSession(); + const feed = await db.posts.findMany({ + where: { authorId: { in: session.following } }, + }); + + return ; +} + +// Page composition +export default async function HomePage() { + return ( + <> +

+ + }> + + + + ); +} +``` + +--- + +## Pattern 2: Read-Your-Own-Writes with Server Actions + +Ensure users see their changes immediately: + +```tsx +// components/posts.tsx +import { cacheTag, cacheLife } from "next/cache"; + +async function PostsList() { + "use cache"; + cacheTag("posts"); + cacheLife("hours"); + + const posts = await db.posts.findMany({ orderBy: { createdAt: "desc" } }); + return ( +

+ ))} +

+ ); +} + +// actions/posts.ts +("use server"); +import { updateTag } from "next/cache"; + +export async function createPost(formData: FormData) { + const post = await db.posts.create({ + data: { + title: formData.get("title") as string, + content: formData.get("content") as string, + }, + }); + + // Immediate invalidation - user sees new post right away + updateTag("posts"); + + return { success: true, postId: post.id }; +} + +// components/create-post-form.tsx +("use client"); +import { useTransition } from "react"; +import { createPost } from "@/actions/posts"; + +export function CreatePostForm() { + const [isPending, startTransition] = useTransition(); + + return ( +

{ + startTransition(() => createPost(formData)); + }} + > + +

+      <button disabled={isPending}>
+        {isPending ? "Creating..." : "Create Post"}
+      </button>
+    </form>
+  );
+}
+```
+
+---
+
+## Pattern 3: Granular Cache Invalidation
+
+Tag caches at multiple levels for precise invalidation:
+
+```tsx
+// Cached with multiple tags
+async function BlogPost({ postId }: { postId: string }) {
+  "use cache";
+  cacheTag("posts", `post-${postId}`);
+  cacheLife("days");
+
+  const post = await db.posts.findUnique({
+    where: { id: postId },
+    include: { author: true, comments: true },
+  });
+
+  return <Article post={post} />;
+}
+
+async function AuthorPosts({ authorId }: { authorId: string }) {
+  "use cache";
+  cacheTag("posts", `author-${authorId}`);
+  cacheLife("hours");
+
+  const posts = await db.posts.findMany({
+    where: { authorId },
+  });
+
+  return <PostGrid posts={posts} />;
+}
+
+// Server actions with targeted invalidation
+("use server");
+import { updateTag } from "next/cache";
+
+export async function updatePost(postId: string, data: FormData) {
+  const post = await db.posts.update({
+    where: { id: postId },
+    data: { title: data.get("title"), content: data.get("content") },
+  });
+
+  // Invalidate specific post only
+  updateTag(`post-${postId}`);
+}
+
+export async function deleteAuthorPosts(authorId: string) {
+  await db.posts.deleteMany({ where: { authorId } });
+
+  // Invalidate all author's posts
+  updateTag(`author-${authorId}`);
+}
+
+export async function clearAllPosts() {
+  await db.posts.deleteMany();
+
+  // Nuclear option - invalidate everything tagged 'posts'
+  updateTag("posts");
+}
+```
+
+---
+
+## Pattern 4: Cached Data Fetching Functions
+
+Create reusable cached data fetchers:
+
+```tsx
+// lib/data.ts
+import { cacheTag, cacheLife } from "next/cache";
+
+export async function getUser(userId: string) {
+  "use cache";
+  cacheTag("users", `user-${userId}`);
+  cacheLife("hours");
+
+  return db.users.findUnique({ where: { id: userId } });
+}
+
+export async function getPostsByCategory(category: string) {
+  "use cache";
+  cacheTag("posts", `category-${category}`);
+  cacheLife("minutes");
+
+  return db.posts.findMany({
+    where: { category },
+    orderBy: { createdAt: "desc" },
+  });
+}
+
+export async function getPopularProducts() {
+  "use cache";
+  cacheTag("products", "popular");
+  cacheLife("hours");
+
+  return db.products.findMany({
+    orderBy: { salesCount: "desc" },
+    take: 10,
+  });
+}
+
+// Usage in components
+async function Sidebar() {
+  const popular = await getPopularProducts();
+  return <ProductList products={popular} />;
+}
+```
+
+---
+
+## Pattern 5: Stale-While-Revalidate for Background Updates
+
+Use `revalidateTag` for non-critical updates:
+
+```tsx
+// For background analytics or non-user-facing updates
+"use server";
+import { revalidateTag } from "next/cache";
+
+export async function trackView(postId: string) {
+  await db.posts.update({
+    where: { id: postId },
+    data: { views: { increment: 1 } },
+  });
+
+  // Background revalidation - old count shown while updating
+  revalidateTag(`post-${postId}`, "max");
+}
+
+// For user-facing mutations, use updateTag instead
+export async function likePost(postId: string) {
+  await db.likes.create({ data: { postId, userId: getCurrentUserId() } });
+
+  // Immediate - user sees their like right away
+  updateTag(`post-${postId}`);
+}
+```
+
+---
+
+## Pattern 6: Conditional Caching Based on Content
+
+Cache based on content characteristics:
+
+```tsx
+async function ContentBlock({ id }: { id: string }) {
+  "use cache";
+
+  const content = await db.content.findUnique({ where: { id } });
+
+  // Adjust cache life based on content type
+  if (content.type === "static") {
+    cacheLife("max");
+    cacheTag("static-content");
+  } else if (content.type === "news") {
+    cacheLife("minutes");
+    cacheTag("news", `news-${id}`);
+  } else {
+    cacheLife("default");
+    cacheTag("content", `content-${id}`);
+  }
+
+  return <ContentRenderer content={content} />;
+}
+```
+
+---
+
+## Pattern 7: Nested Cached Components
+
+Compose cached components for fine-grained caching:
+
+```tsx
+// Each component caches independently
+async function Header() {
+  "use cache";
+  cacheTag("layout", "header");
+  cacheLife("days");
+
+  const nav = await db.navigation.findFirst();
+  return <Nav items={nav.items} />;
+}
+
+async function Footer() {
+  "use cache";
+  cacheTag("layout", "footer");
+  cacheLife("days");
+
+  const footer = await db.footer.findFirst();
+  return <FooterContent data={footer} />;
+}
+
+async function Sidebar({ category }: { category: string }) {
+  "use cache";
+  cacheTag("sidebar", `category-${category}`);
+  cacheLife("hours");
+
+  const related = await db.posts.findMany({
+    where: { category },
+    take: 5,
+  });
+  return <RelatedPosts posts={related} />;
+}
+
+// Page composes cached components
+export default async function BlogLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: { category: string };
+}) {
+  return (
+    <>
+      <Header />
+      <main>
+        {children}
+        <Sidebar category={params.category} />
+      </main>
+      <Footer />
+    </>
+  );
+}
+```
+
+---
+
+## Pattern 8: E-commerce Product Page
+
+Complete example for e-commerce:
+
+```tsx
+// app/products/[id]/page.tsx
+import { Suspense } from "react";
+import { cacheTag, cacheLife } from "next/cache";
+
+// Cached product details (changes rarely)
+async function ProductDetails({ productId }: { productId: string }) {
+  "use cache";
+  cacheTag("products", `product-${productId}`);
+  cacheLife("hours");
+
+  const product = await db.products.findUnique({
+    where: { id: productId },
+    include: { images: true, specifications: true },
+  });
+
+  return (
+    <div>
+      <ProductGallery images={product.images} />
+      <ProductInfo product={product} />
+      <Specifications specs={product.specifications} />
+    </div>
+  );
+}
+
+// Cached reviews (moderate change frequency)
+async function ProductReviews({ productId }: { productId: string }) {
+  "use cache";
+  cacheTag(`product-${productId}-reviews`);
+  cacheLife("minutes");
+
+  const reviews = await db.reviews.findMany({
+    where: { productId },
+    orderBy: { createdAt: "desc" },
+    take: 10,
+  });
+
+  return <ReviewsList reviews={reviews} />;
+}
+
+// Dynamic inventory (real-time)
+async function InventoryStatus({ productId }: { productId: string }) {
+  // No cache - always fresh
+  const inventory = await db.inventory.findUnique({
+    where: { productId },
+  });
+
+  return (
+    <div>
+      {inventory.quantity > 0 ? (
+        <span className="text-green-600">In Stock ({inventory.quantity})</span>
+      ) : (
+        <span className="text-red-600">Out of Stock</span>
+      )}
+    </div>
+  );
+}
+
+// Page composition
+export default async function ProductPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+
+  return (
+    <>
+      <ProductDetails productId={id} />
+
+      <Suspense fallback={<InventorySkeleton />}>
+        <InventoryStatus productId={id} />
+      </Suspense>
+
+      {/* Suspense around cached components:
+          - At BUILD TIME (PPR): Cached content is pre-rendered into the static shell,
+            so the fallback is never shown for initial page loads.
+          - At RUNTIME (cache miss/expiration): When the cache expires or on cold start,
+            Suspense shows the fallback while fresh data loads.
+          - For long-lived caches ('minutes', 'hours', 'days'), Suspense is optional
+            but improves UX during the rare cache miss. */}
+      <Suspense fallback={<ReviewsSkeleton />}>
+        <ProductReviews productId={id} />
+      </Suspense>
+    </>
+  );
+}
+```
+
+---
+
+## Pattern 9: Multi-tenant SaaS Application
+
+Handle tenant-specific caching:
+
+```tsx
+// lib/tenant.ts
+export async function getTenantId() {
+  const host = (await headers()).get("host");
+  return host?.split(".")[0]; // subdomain as tenant ID
+}
+
+// Tenant-scoped cached data
+async function TenantDashboard({ tenantId }: { tenantId: string }) {
+  "use cache";
+  cacheTag(`tenant-${tenantId}`, "dashboards");
+  cacheLife("minutes");
+
+  const data = await db.dashboards.findFirst({
+    where: { tenantId },
+  });
+
+  return <Dashboard data={data} />;
+}
+
+// Page with tenant context
+export default function DashboardPage() {
+  return (
+    <Suspense fallback={<DashboardSkeleton />}>
+      <DashboardLoader />
+    </Suspense>
+  );
+}
+
+async function DashboardLoader() {
+  const tenantId = await getTenantId();
+  return <TenantDashboard tenantId={tenantId} />;
+}
+
+// Tenant-specific invalidation
+("use server");
+import { updateTag } from "next/cache";
+
+export async function updateTenantSettings(data: FormData) {
+  const tenantId = await getTenantId();
+
+  await db.settings.update({
+    where: { tenantId },
+    data: {
+      /* ... */
+    },
+  });
+
+  // Only invalidate this tenant's cache
+  updateTag(`tenant-${tenantId}`);
+}
+```
+
+---
+
+## Pattern 10: Subshell Composition with generateStaticParams
+
+Leverage parameter permutations to create reusable subshells:
+
+```tsx
+// app/products/[category]/[slug]/page.tsx
+import { Suspense } from "react";
+import { cacheLife, cacheTag } from "next/cache";
+
+// Product details - uses both params
+async function ProductDetails({
+  category,
+  slug,
+}: {
+  category: string;
+  slug: string;
+}) {
+  "use cache";
+  cacheTag("products", `product-${slug}`);
+  cacheLife("hours");
+
+  const product = await db.products.findUnique({
+    where: { category, slug },
+  });
+
+  return <ProductCard product={product} />;
+}
+
+export default async function ProductPage({
+  params,
+}: {
+  params: Promise<{ category: string; slug: string }>;
+}) {
+  const { category, slug } = await params;
+
+  return <ProductDetails category={category} slug={slug} />;
+}
+
+// Provide params to enable subshell generation
+export async function generateStaticParams() {
+  const products = await db.products.findMany({
+    select: { category: true, slug: true },
+    take: 100,
+  });
+  return products.map(({ category, slug }) => ({ category, slug }));
+}
+```
+
+```tsx
+// app/products/[category]/layout.tsx
+import { Suspense } from "react";
+import { cacheLife, cacheTag } from "next/cache";
+
+// Category header - uses only category param
+async function CategoryHeader({ category }: { category: string }) {
+  "use cache";
+  cacheTag("categories", `category-${category}`);
+  cacheLife("days");
+
+  const cat = await db.categories.findUnique({ where: { slug: category } });
+  return (
+    <header>
+      <h1>{cat.name}</h1>
+      <p>{cat.description}</p>
+    </header>
+  );
+}
+
+export default async function CategoryLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ category: string }>;
+}) {
+  const { category } = await params;
+
+  return (
+    <>
+      <CategoryHeader category={category} />
+      {/* Suspense enables subshell generation */}
+      <Suspense fallback={<ProductSkeleton />}>{children}</Suspense>
+    </>
+  );
+}
+```
+
+**Result**: When users navigate to `/products/jackets/unknown-jacket`:
+
+1. Category subshell (`/products/jackets/[slug]`) served instantly
+2. Product details stream in as they load
+3. Future visits to any jacket product reuse the category shell
+
+---
+
+## Pattern 11: Hierarchical Params for Deep Routes
+
+For deeply nested routes, structure layouts to maximize subshell reuse:
+
+```tsx
+// Route: /store/[region]/[category]/[productId]
+
+// app/store/[region]/layout.tsx
+export default async function RegionLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ region: string }>;
+}) {
+  const { region } = await params;
+
+  return (
+    <>
+      <RegionHeader region={region} /> {/* Cached */}
+      <RegionPromos region={region} /> {/* Cached */}
+      <Suspense>{children}</Suspense> {/* Subshell boundary */}
+    </>
+  );
+}
+
+// app/store/[region]/[category]/layout.tsx
+export default async function CategoryLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ region: string; category: string }>;
+}) {
+  const { region, category } = await params;
+
+  return (
+    <>
+      <CategoryNav region={region} category={category} /> {/* Cached */}
+      <Suspense>{children}</Suspense> {/* Subshell boundary */}
+    </>
+  );
+}
+
+// app/store/[region]/[category]/[productId]/page.tsx
+export default async function ProductPage({
+  params,
+}: {
+  params: Promise<{ region: string; category: string; productId: string }>;
+}) {
+  const { region, category, productId } = await params;
+
+  return <ProductDetails region={region} productId={productId} />;
+}
+
+export async function generateStaticParams() {
+  // Return popular products - subshells generated for all unique region/category combos
+  return [
+    { region: "us", category: "electronics", productId: "iphone-16" },
+    { region: "us", category: "electronics", productId: "macbook-pro" },
+    { region: "us", category: "clothing", productId: "hoodie-xl" },
+    { region: "eu", category: "electronics", productId: "iphone-16" },
+  ];
+}
+```
+
+**Generated subshells:**
+
+- `/store/us/[category]/[productId]` - US region shell
+- `/store/eu/[category]/[productId]` - EU region shell
+- `/store/us/electronics/[productId]` - US Electronics shell
+- `/store/us/clothing/[productId]` - US Clothing shell
+- `/store/eu/electronics/[productId]` - EU Electronics shell
+
+---
+
+## When to Use Suspense with Cached Components
+
+Understanding when Suspense is required vs. optional for cached components:
+
+### Dynamic Components (no cache) → Suspense Required
+
+```tsx
+// Dynamic content MUST have Suspense for streaming
+async function PersonalizedFeed() {
+  const session = await getSession(); // Dynamic - reads cookies
+  const feed = await fetchFeed(session.userId);
+  return <Feed posts={feed} />;
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<FeedSkeleton />}>
+      <PersonalizedFeed />
+    </Suspense>
+  );
+}
+```
+
+### Cached Components → Suspense Optional (but recommended)
+
+```tsx
+// Cached content: Suspense is optional but improves UX
+async function ProductReviews({ productId }: { productId: string }) {
+  'use cache'
+  cacheLife('minutes')
+  const reviews = await fetchReviews(productId)
+  return <ReviewsList reviews={reviews} />
+}
+
+// ✅ With Suspense - handles cache miss gracefully
+<Suspense fallback={<ReviewsSkeleton />}>
+  <ProductReviews productId={id} />
+</Suspense>
+
+// ✅ Without Suspense - also valid for long-lived caches
+<ProductReviews productId={id} />
+```
+
+### Why Cached Components Don't Always Need Suspense
+
+| Scenario                     | What Happens                                | Suspense Needed?          |
+| ---------------------------- | ------------------------------------------- | ------------------------- |
+| **Build time (PPR enabled)** | Content pre-rendered into static shell      | No - fallback never shown |
+| **Runtime - cache hit**      | Cached result returned immediately          | No - no suspension        |
+| **Runtime - cache miss**     | Async function executes, component suspends | Yes - for better UX       |
+
+### Recommendations by Cache Lifetime
+
+| Cache Lifetime       | Suspense Recommendation | Reasoning                        |
+| -------------------- | ----------------------- | -------------------------------- |
+| `'seconds'`          | **Recommended**         | Frequent cache misses            |
+| `'minutes'`          | Optional                | ~5 min expiry, occasional misses |
+| `'hours'` / `'days'` | Optional                | Rare cache misses                |
+| `'max'`              | Not needed              | Essentially static               |
+
+### The Trade-off
+
+**Without Suspense**: On cache miss, the page waits for data before rendering anything downstream. For long-lived caches, this is rare and brief.
+
+**With Suspense**: On cache miss, users see the skeleton immediately while data loads. Better perceived performance, slightly more code.
+
+**Rule of thumb**: When in doubt, add Suspense. It never hurts and handles edge cases gracefully.
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ Caching user-specific data without parameters
+
+```tsx
+// BAD: Same cache for all users
+async function UserProfile() {
+  "use cache";
+  const user = await getCurrentUser(); // Different per user!
+  return <Profile user={user} />;
+}
+
+// GOOD: User ID as parameter (becomes cache key)
+async function UserProfile({ userId }: { userId: string }) {
+  "use cache";
+  cacheTag(`user-${userId}`);
+  const user = await db.users.findUnique({ where: { id: userId } });
+  return <Profile user={user} />;
+}
+```
+
+### ❌ Over-caching volatile data
+
+```tsx
+// BAD: Caching real-time data
+async function StockPrice({ symbol }: { symbol: string }) {
+  "use cache";
+  cacheLife("hours"); // Stale prices!
+  return await fetchStockPrice(symbol);
+}
+
+// GOOD: Don't cache, or use very short cache
+async function StockPrice({ symbol }: { symbol: string }) {
+  "use cache";
+  cacheLife("seconds"); // 1 second max
+  return await fetchStockPrice(symbol);
+}
+
+// BETTER: No cache for truly real-time
+async function StockPrice({ symbol }: { symbol: string }) {
+  return await fetchStockPrice(symbol);
+}
+```
+
+### ❌ Forgetting Suspense for dynamic content
+
+```tsx
+// BAD: No fallback for DYNAMIC content - breaks streaming
+export default async function Page() {
+  return (
+    <>
+      <CachedHeader />
+      <DynamicContent /> {/* Dynamic - NEEDS Suspense */}
+    </>
+  );
+}
+
+// GOOD: Proper Suspense boundary for dynamic content
+export default async function Page() {
+  return (
+    <>
+      <CachedHeader />
+      <Suspense fallback={<ContentSkeleton />}>
+        <DynamicContent />
+      </Suspense>
+    </>
+  );
+}
+
+// ALSO GOOD: Cached content without Suspense (optional for long-lived caches)
+export default async function Page() {
+  return (
+    <>
+      <CachedHeader /> {/* 'use cache' - no Suspense needed */}
+      <CachedSidebar /> {/* 'use cache' - no Suspense needed */}
+      <Suspense fallback={<ContentSkeleton />}>
+        <DynamicContent /> {/* Dynamic - Suspense required */}
+      </Suspense>
+    </>
+  );
+}
+```
+
+---
+
+## Pattern 12: Interleaving with Children (Pass-Through)
+
+Pass non-serializable values like `children` (ReactNode) and Server Actions through cached components. These values are forwarded to the output unchanged — they do NOT become part of the cache key and must NOT be read or invoked inside the cached scope.
+
+### Cached Wrapper Passing Through Children
+
+```tsx
+import { cacheLife, cacheTag } from "next/cache";
+
+// Cached layout wrapper - children pass through without affecting cache
+async function CachedPageShell({
+  children,
+  category,
+}: {
+  children: React.ReactNode;
+  category: string;
+}) {
+  "use cache";
+  cacheTag(`shell-${category}`);
+  cacheLife("days");
+
+  const nav = await db.navigation.findFirst({ where: { category } });
+  const promo = await db.promos.findFirst({
+    where: { category, active: true },
+  });
+
+  return (
+    <div>
+      <Nav items={nav.items} />
+      <PromoBanner promo={promo} />
+      {children} {/* Pass-through: NOT read by cache, just forwarded */}
+    </div>
+  );
+}
+
+// Usage: cached shell wraps dynamic content
+export default function CategoryPage({
+  params,
+}: {
+  params: Promise<{ category: string }>;
+}) {
+  const { category } = React.use(params);
+
+  return (
+    <CachedPageShell category={category}>
+      <Suspense fallback={<ProductsSkeleton />}>
+        <DynamicProducts category={category} />
+      </Suspense>
+    </CachedPageShell>
+  );
+}
+```
+
+### Server Action Pass-Through to Client Component
+
+```tsx
+// Server Action defined in a server file
+"use server";
+import { updateTag } from "next/cache";
+
+export async function addToCart(productId: string) {
+  await db.cart.add({ productId });
+  updateTag("cart");
+}
+
+// Cached component passes Server Action to Client Component
+async function CachedProductCard({ productId }: { productId: string }) {
+  "use cache";
+  cacheTag(`product-${productId}`);
+  cacheLife("hours");
+
+  const product = await db.products.findUnique({ where: { id: productId } });
+
+  // Server Action passed as prop - NOT invoked in cached scope
+  return <AddToCartButton product={product} onAdd={addToCart} />;
+}
+
+// Client Component receives the action
+("use client");
+function AddToCartButton({
+  product,
+  onAdd,
+}: {
+  product: Product;
+  onAdd: (id: string) => Promise<void>;
+}) {
+  return (
+    <button onClick={() => onAdd(product.id)}>
+      Add {product.name} to Cart
+    </button>
+  );
+}
+```
+
+### Rules for Pass-Through
+
+1. **Do NOT read `children`** inside the cached scope — only render them in JSX output
+2. **Do NOT invoke Server Actions** inside the cached scope — only pass them as props
+3. Pass-through values do not affect the cache key — only serializable arguments do
+4. This pattern enables interleaving cached shells with dynamic or interactive content
diff --git a/.claude/skills/cache-components/REFERENCE.md b/.claude/skills/cache-components/REFERENCE.md
new file mode 100644
index 000000000..90f6dce5e
--- /dev/null
+++ b/.claude/skills/cache-components/REFERENCE.md
@@ -0,0 +1,1441 @@
+# Cache Components API Reference
+
+Complete API reference for Next.js Cache Components.
+
+## Contents
+
+- [Directive: `'use cache'`](#directive-use-cache)
+- [`cacheLife()`](#function-cachelife)
+- [`cacheTag()`](#function-cachetag)
+- [Understanding Cache Scope](#understanding-cache-scope)
+- [`updateTag()`](#function-updatetag)
+- [`revalidateTag()`](#function-revalidatetag)
+- [`updateTag()` vs `revalidateTag()`](#updatetag-vs-revalidatetag-when-to-use-each)
+- [`revalidatePath()`](#function-revalidatepath)
+- [`connection()`](#function-connection)
+- [Configuration: `next.config.ts`](#configuration-nextconfigts)
+- [`generateStaticParams` with Cache Components](#generatestaticparams-with-cache-components)
+- [GET Route Handlers](#get-route-handlers-with-cache-components)
+- [Deprecated Segment Configurations](#deprecated-segment-configurations)
+- [Migration Scenarios](#migration-scenarios)
+- [Runtime Behaviors](#runtime-behaviors)
+- [Type Definitions](#type-definitions)
+
+## Directive: `'use cache'`
+
+Marks a function or file as cacheable. The cached output is included in the static shell during Partial Prerendering.
+
+### Syntax
+
+```tsx
+// File-level (applies to all exports)
+"use cache";
+
+export async function getData() {
+  /* ... */
+}
+
+// Function-level
+async function Component() {
+  "use cache";
+  // ...
+}
+```
+
+### Variants
+
+| Directive                               | Description               | Cache Storage                                |
+| --------------------------------------- | ------------------------- | -------------------------------------------- |
+| `'use cache'`                           | Standard cache (default)  | Default handler + Remote                     |
+| `'use cache: remote'`                   | Platform remote cache     | Remote handler only                          |
+| `'use cache: private'` _(experimental)_ | Per-request private cache | Browser memory only (never stored on server) |
+
+### `'use cache: remote'`
+
+Uses platform-specific remote cache handler. Requires network roundtrip.
+
+```tsx
+async function HeavyComputation() {
+  "use cache: remote";
+  cacheLife("days");
+
+  return await expensiveCalculation();
+}
+```
+
+### `'use cache: private'`
+
+> **⚠️ Experimental**: This directive is experimental and **not recommended for
+> production** — its behavior may change. See the
+> [official docs](https://nextjs.org/docs/app/api-reference/directives/use-cache-private).
+
+Unlike `'use cache'`, the private variant **lets you access runtime request APIs**
+(`cookies()`, `headers()`, `searchParams`) inside a cached scope. Its results are
+**never stored on the server** — they are cached only in the **browser's memory**
+and **do not persist across page reloads**. This makes it suitable for compliance
+scenarios where data must not be stored server-side, even temporarily.
+
+```tsx
+import { cookies } from "next/headers";
+
+async function UserComplianceData() {
+  "use cache: private";
+  cacheLife("seconds");
+
+  // Runtime APIs are allowed here; result cached in browser memory only
+  const session = (await cookies()).get("session")?.value;
+  return await fetchSensitiveReport(session);
+}
+```
+
+**When to use**: Reach for `'use cache: private'` only when (a) you want to cache a
+function that already accesses runtime data and refactoring to pass values as
+arguments is impractical, OR (b) compliance prevents storing the data on the
+server even temporarily. Prefer `'use cache'` with parameterized arguments for
+most cases.
+
+### Understanding Cache Handlers
+
+Next.js uses **cache handlers** to store and retrieve cached data. The directive variant determines which handlers are used:
+
+| Handler   | Description                                                                |
+| --------- | -------------------------------------------------------------------------- |
+| `default` | Local in-memory cache with optional persistence. Fast, single-server scope |
+| `remote`  | Platform-specific distributed cache. Network roundtrip, multi-server scope |
+
+**How variants map to handlers:**
+
+- `'use cache'` → Uses **both** default and remote handlers. Data is cached locally for fast access and remotely for sharing across instances
+- `'use cache: remote'` → Stores the cached output in the **remote** handler instead of in-memory. Durable and shared across all server instances (adds network latency)
+
+**When to use each:**
+
+| Use Case                              | Recommended Variant    |
+| ------------------------------------- | ---------------------- |
+| Most cached data                      | `'use cache'`          |
+| Heavy computations to share globally  | `'use cache: remote'`  |
+| Data that must be consistent globally | `'use cache: remote'`  |
+| Compliance: no cross-request sharing  | `'use cache: private'` |
+
+### Rules
+
+1. **Must be async** - All cached functions must return a Promise
+2. **First statement** - `'use cache'` must be the first statement in the function body
+3. **No runtime APIs** - Cannot call `cookies()`, `headers()`, `searchParams` directly (exception: `'use cache: private'` allows request-scoped access since it is not shared across requests)
+4. **Serializable arguments** - All arguments must be serializable (no functions, class instances)
+5. **Serializable return values** - Cached functions must return serializable data (no functions, class instances)
+
+---
+
+## Function: `cacheLife()`
+
+Configures cache duration and revalidation behavior.
+
+### Import
+
+```tsx
+import { cacheLife } from "next/cache";
+```
+
+### Signature
+
+```tsx
+function cacheLife(profile: string): void;
+function cacheLife(options: CacheLifeOptions): void;
+
+interface CacheLifeOptions {
+  stale?: number; // Client cache duration (seconds)
+  revalidate?: number; // Background revalidation window (seconds)
+  expire?: number; // Absolute expiration (seconds)
+}
+```
+
+### Parameters
+
+| Parameter    | Description                                             | Constraint            |
+| ------------ | ------------------------------------------------------- | --------------------- |
+| `stale`      | How long the client can cache without server validation | None                  |
+| `revalidate` | When to start background refresh                        | `revalidate ≤ expire` |
+| `expire`     | Absolute expiration; deopts to dynamic if exceeded      | Must be largest       |
+
+### Predefined Profiles
+
+| Profile     | stale | revalidate    | expire         |
+| ----------- | ----- | ------------- | -------------- |
+| `'default'` | 300\* | 900 (15min)   | ∞ (INFINITE)   |
+| `'seconds'` | 30    | 1             | 60             |
+| `'minutes'` | 300   | 60 (1min)     | 3600 (1hr)     |
+| `'hours'`   | 300   | 3600 (1hr)    | 86400 (1day)   |
+| `'days'`    | 300   | 86400 (1day)  | 604800 (1wk)   |
+| `'weeks'`   | 300   | 604800 (1wk)  | 2592000 (30d)  |
+| `'max'`     | 300   | 2592000 (30d) | 31536000 (1yr) |
+
+\* Default `stale` falls back to `experimental.staleTimes.static` (300 seconds)
+
+> **Important:** Profiles with `expire < 300` seconds (like `'seconds'`) are treated as **dynamic** and won't be included in the static shell during Partial Prerendering. See [Dynamic Threshold](#dynamic-threshold) below.
+
+### Custom Profiles
+
+Define custom profiles in `next.config.ts`:
+
+```typescript
+const nextConfig: NextConfig = {
+  cacheLife: {
+    // Custom profile
+    "blog-posts": {
+      stale: 300, // 5 minutes
+      revalidate: 3600, // 1 hour
+      expire: 86400, // 1 day
+    },
+    // Override default
+    default: {
+      stale: 60,
+      revalidate: 600,
+      expire: 3600,
+    },
+  },
+};
+```
+
+### Usage
+
+```tsx
+async function BlogPosts() {
+  "use cache";
+  cacheLife("blog-posts"); // Custom profile
+
+  return await db.posts.findMany();
+}
+```
+
+### HTTP Cache-Control Mapping
+
+```
+stale     → max-age
+revalidate → s-maxage
+expire - revalidate → stale-while-revalidate
+
+Example: stale=60, revalidate=3600, expire=86400
+→ Cache-Control: max-age=60, s-maxage=3600, stale-while-revalidate=82800
+```
+
+### Dynamic Threshold
+
+Cache entries with short expiration times are treated as **dynamic holes** during Partial Prerendering:
+
+| Condition               | Behavior                                 |
+| ----------------------- | ---------------------------------------- |
+| `expire < 300` seconds  | Treated as dynamic (not in static shell) |
+| `revalidate === 0`      | Treated as dynamic (not in static shell) |
+| `expire >= 300` seconds | Included in static shell                 |
+
+**Why `expire`, not `stale`?**
+
+The threshold uses `expire` (absolute expiration) because:
+
+- `expire` defines the **maximum lifetime** of the cache entry
+- If `expire` is very short, the cached content would immediately become invalid in the static shell
+- `stale` only affects **client-side freshness perception** - how long before the browser revalidates
+- Including short-lived content in the static shell would serve guaranteed-stale data
+
+**Practical implications:**
+
+- `cacheLife('seconds')` (expire=60) → **Dynamic** - streams at request time
+- `cacheLife('minutes')` (expire=3600) → **Static** - included in PPR shell
+- Custom `cacheLife({ expire: 120 })` → **Dynamic** - below 300s threshold
+
+This 300-second threshold ensures that very short-lived caches don't pollute the static shell with immediately-stale content.
+
+```tsx
+// This cache is DYNAMIC (expire=60 < 300)
+async function RealtimePrice() {
+  "use cache";
+  cacheLife("seconds"); // expire=60, below threshold
+  return await fetchPrice();
+}
+
+// This cache is STATIC (expire=3600 >= 300)
+async function ProductDetails() {
+  "use cache";
+  cacheLife("minutes"); // expire=3600, above threshold
+  return await fetchProduct();
+}
+```
+
+---
+
+## Function: `cacheTag()`
+
+Tags cached data for targeted invalidation.
+
+### Import
+
+```tsx
+import { cacheTag } from "next/cache";
+```
+
+### Signature
+
+```tsx
+function cacheTag(...tags: string[]): void;
+```
+
+### Usage
+
+```tsx
+async function UserProfile({ userId }: { userId: string }) {
+  "use cache";
+  cacheTag("users", `user-${userId}`); // Multiple tags
+  cacheLife("hours");
+
+  return await db.users.findUnique({ where: { id: userId } });
+}
+```
+
+### Tagging Strategies
+
+**Entity-based tagging**:
+
+```tsx
+cacheTag("posts"); // All posts
+cacheTag(`post-${postId}`); // Specific post
+cacheTag(`user-${userId}-posts`); // User's posts
+```
+
+**Feature-based tagging**:
+
+```tsx
+cacheTag("homepage");
+cacheTag("dashboard");
+cacheTag("admin");
+```
+
+**Combined approach**:
+
+```tsx
+cacheTag("posts", `post-${id}`, `author-${authorId}`);
+```
+
+### Tag Constraints
+
+Tags have enforced limits:
+
+| Limit          | Value          | Behavior if exceeded           |
+| -------------- | -------------- | ------------------------------ |
+| Max tag length | 256 characters | Warning logged, tag ignored    |
+| Max total tags | 128 tags       | Warning logged, excess ignored |
+
+```tsx
+// ❌ Tag too long (>256 chars) - will be ignored with warning
+cacheTag("a".repeat(300));
+
+// ❌ Too many tags (>128) - excess will be ignored with warning
+cacheTag(...Array(200).fill("tag"));
+
+// ✅ Valid usage
+cacheTag("products", `product-${id}`, `category-${category}`);
+```
+
+### Implicit Tags (Automatic)
+
+In addition to explicit `cacheTag()` calls, Next.js automatically applies **implicit tags** based on the route hierarchy. This means `revalidatePath()` works without any explicit `cacheTag()` calls:
+
+```tsx
+"use server";
+import { revalidatePath } from "next/cache";
+
+export async function publishBlogPost() {
+  await db.posts.create({
+    /* ... */
+  });
+
+  // Works without explicit cacheTag() - uses implicit route-based tags
+  revalidatePath("/blog", "layout"); // Invalidates all /blog/* routes
+}
+```
+
+**How it works:**
+
+- Each route segment (layout, page) automatically receives an internal tag
+- `revalidatePath('/blog', 'layout')` invalidates the `/blog` layout and all nested routes
+- `revalidatePath('/blog/my-post')` invalidates only that specific page
+
+**Choosing between implicit and explicit tags**:
+
+| Use Case                                 | Approach                            |
+| ---------------------------------------- | ----------------------------------- |
+| Invalidate all cached data under a route | `revalidatePath()` (uses implicit)  |
+| Invalidate specific entity across routes | `cacheTag()` + `updateTag()`        |
+| User needs to see their change (eager)   | `updateTag()` with explicit tag     |
+| Background update, eventual OK (lazy)    | `revalidateTag()` with explicit tag |
+
+---
+
+## Understanding Cache Scope
+
+### What Creates a New Cache Entry?
+
+A new cache entry is created when ANY of these differ:
+
+| Factor                | Example                                 |
+| --------------------- | --------------------------------------- |
+| **Function identity** | Different functions = different entries |
+| **Arguments**         | `getUser("123")` vs `getUser("456")`    |
+| **File path**         | Same function name in different files   |
+
+### Cache Key Composition
+
+Cache keys are composed of multiple parts:
+
+```
+[buildId, functionId, serializedArgs, (hmrRefreshHash)]
+```
+
+| Part             | Description                                                     |
+| ---------------- | --------------------------------------------------------------- |
+| `buildId`        | Unique build identifier (prevents cross-deployment cache reuse) |
+| `functionId`     | Server reference ID for the cached function                     |
+| `serializedArgs` | React Flight-encoded function arguments                         |
+| `hmrRefreshHash` | (Dev only) Invalidates cache on file changes                    |
+
+```tsx
+// These create TWO separate cache entries (third call is a cache hit):
+async function getProduct(id: string) {
+  "use cache";
+  return db.products.findUnique({ where: { id } });
+}
+
+await getProduct("prod-1"); // Cache entry 1: [buildId, getProduct, "prod-1"]
+await getProduct("prod-2"); // Cache entry 2: [buildId, getProduct, "prod-2"]
+await getProduct("prod-1"); // Cache HIT on entry 1
+```
+
+### Object Arguments and Cache Keys
+
+Arguments are serialized using React's `encodeReply()`, which performs **structural serialization**:
+
+```tsx
+async function getData(options: { limit: number }) {
+  "use cache";
+  return fetch(`/api?limit=${options.limit}`);
+}
+
+// Objects with identical structure produce the same cache key
+getData({ limit: 10 }); // Cache key includes serialized { limit: 10 }
+getData({ limit: 10 }); // HIT! Same structural content
+
+// Different values = different cache keys
+getData({ limit: 20 }); // MISS - different content
+```
+
+**Best practice:** While objects work correctly, primitives are simpler to reason about:
+
+```tsx
+// ✅ Clear and explicit
+async function getData(limit: number) {
+  "use cache";
+  return fetch(`/api?limit=${limit}`);
+}
+```
+
+> **Note:** Non-serializable values (functions, class instances, Symbols) cannot be used as arguments to cached functions and will cause errors.
+
+> **Pass-through exception:** Some non-serializable values — such as `children` (ReactNode) and Server Actions — can be passed through cached components without affecting the cache key. These values are not read or invoked inside the cached scope; they are forwarded to the output unchanged. See Pattern 12 (Interleaving with Children) in PATTERNS.md.
+
+### React.cache Isolation
+
+`React.cache()` provides per-request deduplication for regular Server Components, but it does **not** work across `'use cache'` boundaries. Each `'use cache'` function runs in its own isolated scope — `React.cache()` storage from the outer request is not available inside a cached function.
+
+```tsx
+import { cache } from "react";
+
+const getUser = cache(async (id: string) => {
+  console.log("Fetching user", id);
+  return await db.users.findUnique({ where: { id } });
+});
+
+// Outside 'use cache' - React.cache deduplicates normally
+async function UserHeader({ userId }: { userId: string }) {
+  const user = await getUser(userId); // Fetch #1
+  return <h1>{user.name}</h1>;
+}
+
+async function UserSidebar({ userId }: { userId: string }) {
+  const user = await getUser(userId); // Deduplicated - reuses Fetch #1
+  return <aside>{user.bio}</aside>;
+}
+
+// Inside 'use cache' - React.cache does NOT deduplicate
+async function CachedUserCard({ userId }: { userId: string }) {
+  "use cache";
+  const user = await getUser(userId); // Separate fetch - isolated scope
+  return <div>{user.name}</div>;
+}
+```
+
+**Key takeaway**: If you need deduplication inside `'use cache'`, rely on the `'use cache'` mechanism itself (same function + same arguments = cache hit). Do not depend on `React.cache()` for cross-boundary deduplication.
+
+---
+
+## Function: `updateTag()`
+
+Immediately invalidates cache entries and ensures read-your-own-writes.
+
+### Import
+
+```tsx
+import { updateTag } from "next/cache";
+```
+
+### Signature
+
+```tsx
+function updateTag(tag: string): void;
+```
+
+### Usage
+
+```tsx
+"use server";
+import { updateTag } from "next/cache";
+
+export async function createPost(formData: FormData) {
+  const post = await db.posts.create({ data: formData });
+
+  updateTag("posts"); // Update all cache entries tagged with 'posts'
+  updateTag(`user-${userId}`); // Update all cache entries tagged with this user
+
+  // Client immediately sees fresh data
+}
+```
+
+### Behavior
+
+- **Immediate**: Cache invalidated synchronously
+- **Read-your-own-writes**: Subsequent reads return fresh data
+- **Server Actions only**: Must be called from Server Actions
+
+---
+
+## Function: `revalidateTag()`
+
+Marks cache entries as stale for background revalidation.
+
+### Import
+
+```tsx
+import { revalidateTag } from "next/cache";
+```
+
+### Signature
+
+```tsx
+function revalidateTag(
+  tag: string,
+  profile: string | { expire?: number },
+): void;
+```
+
+### Parameters
+
+| Parameter | Type                            | Description                                             |
+| --------- | ------------------------------- | ------------------------------------------------------- |
+| `tag`     | `string`                        | The cache tag to invalidate                             |
+| `profile` | `string \| { expire?: number }` | Cache profile name or object with expire time (seconds) |
+
+> **Note:** Unlike `cacheLife()` which accepts `stale`, `revalidate`, and `expire`, the `revalidateTag()` object form only accepts `expire`. Use a predefined profile name (like `'hours'`) for full control over stale-while-revalidate behavior.
+
+### Usage
+
+```tsx
+"use server";
+import { revalidateTag } from "next/cache";
+
+export async function updateSettings(data: FormData) {
+  await db.settings.update({ data });
+
+  // With predefined profile (recommended)
+  revalidateTag("settings", "hours");
+
+  // With custom expiration
+  revalidateTag("settings", { expire: 3600 });
+}
+```
+
+### Behavior
+
+- **Stale-while-revalidate**: Serves cached content while refreshing in background
+- **Background refresh**: Cache entry is refreshed in the background after the next visit
+- **Broader context**: Can be called from Route Handlers and Server Actions
+
+> **⚠️ Deprecated:** The single-argument form `revalidateTag('tag')` is deprecated in
+> Next.js 16. It currently works only when TypeScript errors are suppressed, and it
+> may be removed in a future version. Always pass a profile (`'max'` recommended for
+> stale-while-revalidate) or `{ expire: <seconds> }` as the second argument. For
+> webhooks requiring immediate expiration, use `revalidateTag(tag, { expire: 0 })`.
+> Source: [Next.js docs — revalidateTag](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)
+
+---
+
+## updateTag() vs revalidateTag(): When to Use Each
+
+The key distinction is **eager vs lazy** invalidation:
+
+- **`updateTag()`** - Eager invalidation. Cache is immediately invalidated, and the next read fetches fresh data synchronously. Use when the user who triggered the action needs to see the result.
+- **`revalidateTag()`** - Lazy (SWR-style) invalidation. Stale data may be served while fresh data is fetched in the background. Use when eventual consistency is acceptable.
+
+Here's a decision guide:
+
+| Scenario                   | Use               | Why                                        |
+| -------------------------- | ----------------- | ------------------------------------------ |
+| User creates a post        | `updateTag()`     | User expects to see their post immediately |
+| User updates their profile | `updateTag()`     | Read-your-own-writes semantics             |
+| Admin publishes content    | `revalidateTag()` | Other users can see stale briefly          |
+| Analytics/view counts      | `revalidateTag()` | Freshness less critical                    |
+| Background sync job        | `revalidateTag()` | No user waiting for result                 |
+| E-commerce cart update     | `updateTag()`     | User needs accurate cart state             |
+
+### E-commerce Example
+
+```tsx
+"use server";
+import { updateTag, revalidateTag } from "next/cache";
+
+// When USER adds to cart → updateTag (they need accurate count)
+export async function addToCart(productId: string, userId: string) {
+  await db.cart.add({ productId, userId });
+  updateTag(`cart-${userId}`); // Immediate - user sees their cart
+}
+
+// When INVENTORY changes from warehouse sync → revalidateTag
+export async function syncInventory(products: Product[]) {
+  await db.inventory.bulkUpdate(products);
+  revalidateTag("inventory", "max"); // Background - eventual consistency OK
+}
+
+// When USER completes purchase → updateTag for buyer, revalidateTag for product
+export async function completePurchase(orderId: string) {
+  const order = await processOrder(orderId);
+
+  updateTag(`order-${orderId}`); // Buyer sees confirmation immediately
+  updateTag(`cart-${order.userId}`); // Buyer's cart clears immediately
+  revalidateTag(`product-${order.productId}`, "max"); // Others see updated stock eventually
+}
+```
+
+### The Rule of Thumb
+
+> **updateTag**: "The person who triggered this action is waiting to see the result"
+>
+> **revalidateTag**: "This update affects others, but they don't know to wait for it"
+
+---
+
+## Function: `revalidatePath()`
+
+Revalidates all cache entries associated with a path.
+
+### Import
+
+```tsx
+import { revalidatePath } from "next/cache";
+```
+
+### Signature
+
+```tsx
+function revalidatePath(path: string, type?: "page" | "layout"): void;
+```
+
+### Usage
+
+```tsx
+"use server";
+import { revalidatePath } from "next/cache";
+
+export async function updateBlog() {
+  await db.posts.update({
+    /* ... */
+  });
+
+  revalidatePath("/blog"); // Specific path
+  revalidatePath("/blog", "layout"); // Layout and all children
+  revalidatePath("/", "layout"); // Entire app
+}
+```
+
+---
+
+## Function: `connection()`
+
+Explicitly defers rendering to request time without accessing runtime APIs like `cookies()` or `headers()`.
+
+### Import
+
+```tsx
+import { connection } from "next/server";
+```
+
+### Signature
+
+```tsx
+function connection(): Promise<void>;
+```
+
+### Usage
+
+```tsx
+import { connection } from "next/server";
+import { Suspense } from "react";
+
+async function UniqueContent() {
+  await connection(); // Defer to request time
+
+  // Non-deterministic operations that need fresh values per request
+  const uuid = crypto.randomUUID();
+  const timestamp = Date.now();
+  const random = Math.random();
+
+  return (
+    <div>
+      <p>UUID: {uuid}</p>
+      <p>Generated: {timestamp}</p>
+      <p>Random: {random}</p>
+    </div>
+  );
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <UniqueContent />
+    </Suspense>
+  );
+}
+```
+
+### When to Use `connection()`
+
+| Scenario                                               | Use `connection()`?       |
+| ------------------------------------------------------ | ------------------------- |
+| Need unique values per request (`crypto.randomUUID()`) | ✅ Yes                    |
+| Using `Math.random()`, `Date.now()`                    | ✅ Yes                    |
+| Non-deterministic operations that shouldn't be cached  | ✅ Yes                    |
+| Already using `cookies()` or `headers()`               | ❌ No (not needed)        |
+| Data is cacheable (same for all users)                 | ❌ No (use `'use cache'`) |
+
+### Why `connection()` Exists
+
+Without `connection()`, non-deterministic operations in Server Components might execute at build time and get baked into the static shell:
+
+```tsx
+// ❌ Problem: UUID generated once at build time
+async function BadExample() {
+  const uuid = crypto.randomUUID(); // Same value for all users!
+  return <div>{uuid}</div>;
+}
+
+// ✅ Solution: UUID generated per request
+async function GoodExample() {
+  await connection();
+  const uuid = crypto.randomUUID(); // Unique per request
+  return <div>{uuid}</div>;
+}
+```
+
+### `connection()` vs Runtime APIs
+
+If you're already accessing `cookies()` or `headers()`, you don't need `connection()`:
+
+```tsx
+// No need for connection() - cookies() already makes this dynamic
+async function UserContent() {
+  const session = (await cookies()).get("session");
+  const timestamp = Date.now(); // Already dynamic due to cookies()
+  return <div>{timestamp}</div>;
+}
+
+// Need connection() - no other dynamic API used
+async function AnonymousContent() {
+  await connection(); // Explicit dynamic
+  const timestamp = Date.now();
+  return <div>{timestamp}</div>;
+}
+```
+
+---
+
+## Configuration: `next.config.ts`
+
+### Enable Cache Components
+
+```typescript
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+};
+
+export default nextConfig;
+```
+
+### Configure Cache Handlers
+
+```typescript
+const nextConfig: NextConfig = {
+  cacheHandlers: {
+    default: {
+      maxMemorySize: 52428800, // 50MB
+    },
+    // Platform-specific remote handler
+    remote: CustomRemoteHandler,
+  },
+};
+```
+
+### Define Cache Profiles
+
+```typescript
+const nextConfig: NextConfig = {
+  cacheLife: {
+    default: {
+      stale: 60,
+      revalidate: 3600,
+      expire: 86400,
+    },
+    posts: {
+      stale: 300,
+      revalidate: 3600,
+      expire: 604800,
+    },
+  },
+};
+```
+
+---
+
+## `generateStaticParams` with Cache Components
+
+When Cache Components is enabled, `generateStaticParams` behavior changes significantly.
+
+### Parameter Permutation Rendering
+
+Next.js renders ALL permutations of provided parameters to create reusable subshells:
+
+```tsx
+// app/products/[category]/[slug]/page.tsx
+export async function generateStaticParams() {
+  return [
+    { category: "jackets", slug: "bomber" },
+    { category: "jackets", slug: "parka" },
+    { category: "shoes", slug: "sneakers" },
+  ];
+}
+```
+
+**Rendered routes:**
+
+| Route                         | Params Known       | Shell Type        |
+| ----------------------------- | ------------------ | ----------------- |
+| `/products/jackets/bomber`    | category ✓, slug ✓ | Complete page     |
+| `/products/jackets/parka`     | category ✓, slug ✓ | Complete page     |
+| `/products/shoes/sneakers`    | category ✓, slug ✓ | Complete page     |
+| `/products/jackets/[slug]`    | category ✓, slug ✗ | Category subshell |
+| `/products/shoes/[slug]`      | category ✓, slug ✗ | Category subshell |
+| `/products/[category]/[slug]` | category ✗, slug ✗ | Fallback shell    |
+
+### Requirements
+
+1. **Must return at least one parameter set** - Empty arrays cause build errors
+2. **Params validate static safety** - Next.js uses provided params to verify no dynamic APIs are accessed
+3. **Subshells require Suspense** - If accessing unknown params without Suspense, no subshell is generated
+
+```tsx
+// ❌ BUILD ERROR: Empty array not allowed
+export function generateStaticParams() {
+  return [];
+}
+
+// ✅ CORRECT: Provide at least one param set
+export async function generateStaticParams() {
+  const products = await getProducts({ limit: 100 });
+  return products.map((p) => ({ category: p.category, slug: p.slug }));
+}
+```
+
+### Subshell Generation with Layouts
+
+Create category-level subshells by adding Suspense in layouts:
+
+```tsx
+// app/products/[category]/layout.tsx
+export default async function CategoryLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ category: string }>;
+}) {
+  const { category } = await params;
+
+  return (
+    <>
+      <h2>{category}</h2>
+      <Suspense>{children}</Suspense> {/* Creates subshell boundary */}
+    </>
+  );
+}
+```
+
+Now `/products/jackets/[slug]` generates a reusable shell with the category header, streaming product details when visited.
+
+### Why Subshells Matter
+
+Without `generateStaticParams`, visiting `/products/jackets/unknown-product`:
+
+- **Before**: Full dynamic render, user waits for everything
+- **After**: Cached category subshell served instantly, product details stream in
+
+---
+
+## GET Route Handlers with Cache Components
+
+GET Route Handlers follow the same prerendering model as pages. When `cacheComponents: true`, a GET handler without dynamic APIs is prerendered at build time:
+
+```tsx
+// app/api/products/route.ts
+import { cacheLife, cacheTag } from "next/cache";
+
+export async function GET() {
+  "use cache";
+  cacheTag("products");
+  cacheLife("hours");
+
+  const products = await db.products.findMany();
+  return Response.json(products);
+}
+```
+
+**Key behaviors:**
+
+- GET handlers with `'use cache'` are prerendered at build time (included in static output)
+- GET handlers that call `cookies()`, `headers()`, or other dynamic APIs are rendered at request time
+- `cacheTag()` and `cacheLife()` work identically to page components
+- Non-GET methods (POST, PUT, DELETE) are always dynamic and cannot use `'use cache'`
+
+```tsx
+// Dynamic GET handler (reads request headers)
+export async function GET(request: Request) {
+  const authHeader = request.headers.get("authorization");
+  const data = await fetchProtectedData(authHeader);
+  return Response.json(data);
+}
+
+// Static GET handler with cache (no dynamic APIs)
+export async function GET() {
+  "use cache";
+  cacheLife("days");
+  const sitemap = await generateSitemapData();
+  return Response.json(sitemap);
+}
+```
+
+---
+
+## Deprecated Segment Configurations
+
+These exports are **deprecated** when `cacheComponents: true`:
+
+### `export const revalidate` (Deprecated)
+
+**Before:**
+
+```tsx
+// app/products/page.tsx
+export const revalidate = 3600; // 1 hour
+
+export default async function ProductsPage() {
+  const products = await db.products.findMany();
+  return <ProductList products={products} />;
+}
+```
+
+**Problems with this approach:**
+
+- Revalidation time lived at segment level, not with the data
+- Couldn't vary revalidation based on fetched data
+- No control over client-side caching (`stale`) or expiration
+
+**After (Cache Components):**
+
+```tsx
+// app/products/page.tsx
+import { cacheLife } from "next/cache";
+
+async function getProducts() {
+  "use cache";
+  cacheLife("hours"); // Co-located with the data
+
+  return await db.products.findMany();
+}
+
+export default async function ProductsPage() {
+  const products = await getProducts();
+  return <ProductList products={products} />;
+}
+```
+
+**Benefits:**
+
+- Cache lifetime co-located with data fetching
+- Granular control: `stale`, `revalidate`, and `expire`
+- Different functions can have different lifetimes
+- Can conditionally set cache life based on data
+
+### `export const dynamic` (Deprecated)
+
+**Before:**
+
+```tsx
+// app/products/page.tsx
+export const dynamic = "force-static";
+
+export default async function ProductsPage() {
+  // Headers would return empty, silently breaking components
+  const headers = await getHeaders();
+  return <ProductList />;
+}
+```
+
+**Problems:**
+
+- All-or-nothing approach
+- `force-static` silently broke dynamic APIs (cookies, headers return empty)
+- `force-dynamic` prevented any static optimization
+- Hidden bugs when dynamic components received empty data
+
+**After (Cache Components):**
+
+```tsx
+// app/products/page.tsx
+export default async function ProductsPage() {
+  return (
+    <>
+      <CachedProductList /> {/* Static via 'use cache' */}
+      <Suspense fallback={<Skeleton />}>
+        <DynamicUserRecommendations /> {/* Dynamic via Suspense */}
+      </Suspense>
+    </>
+  );
+}
+```
+
+**Benefits:**
+
+- No silent API failures
+- Granular static/dynamic at component level
+- Build errors guide you to correct patterns
+- Pages can be BOTH static AND dynamic
+
+### Migration Guide
+
+| Old Pattern                              | New Pattern                                            |
+| ---------------------------------------- | ------------------------------------------------------ |
+| `export const revalidate = 60`           | `cacheLife({ revalidate: 60 })` inside `'use cache'`   |
+| `export const revalidate = 0`            | Remove cache or use `cacheLife('seconds')`             |
+| `export const revalidate = false`        | `cacheLife('max')` for long-term caching               |
+| `export const dynamic = 'force-static'`  | Use `'use cache'` on data fetching                     |
+| `export const dynamic = 'force-dynamic'` | Wrap in `<Suspense>` without cache                     |
+| `export const dynamic = 'auto'`          | Default behavior - not needed                          |
+| `export const dynamic = 'error'`         | Default with Cache Components (build errors guide you) |
+| `export const fetchCache`                | Not needed — `'use cache'` replaces fetch-level config |
+| `export const runtime = 'edge'`          | Not supported with Cache Components                    |
+
+---
+
+## Migration Scenarios
+
+### Scenario 1: Page with `revalidate` Export
+
+**Before:**
+
+```tsx
+// app/products/page.tsx
+export const revalidate = 3600;
+
+export default async function ProductsPage() {
+  const products = await db.products.findMany();
+  return <ProductGrid products={products} />;
+}
+```
+
+**After:**
+
+```tsx
+// app/products/page.tsx
+import { cacheLife } from "next/cache";
+
+async function getProducts() {
+  "use cache";
+  cacheLife("hours"); // Roughly equivalent to revalidate = 3600
+
+  return db.products.findMany();
+}
+
+export default async function ProductsPage() {
+  const products = await getProducts();
+  return <ProductGrid products={products} />;
+}
+```
+
+### Scenario 2: Page with `dynamic = 'force-dynamic'`
+
+**Before:**
+
+```tsx
+// app/dashboard/page.tsx
+export const dynamic = "force-dynamic";
+
+export default async function Dashboard() {
+  const user = await getCurrentUser();
+  const stats = await getStats();
+  const notifications = await getNotifications(user.id);
+
+  return (
+    <div>
+      <UserHeader user={user} />
+      <Stats data={stats} />
+      <Notifications items={notifications} />
+    </div>
+  );
+}
+```
+
+**After:**
+
+```tsx
+// app/dashboard/page.tsx
+import { Suspense } from "react";
+
+// All data is dynamic - fetches user-specific content
+async function DashboardContent() {
+  const user = await getCurrentUser();
+  const stats = await getStats();
+  const notifications = await getNotifications(user.id);
+
+  return (
+    <>
+      <UserHeader user={user} />
+      <Stats data={stats} />
+      <Notifications items={notifications} />
+    </>
+  );
+}
+
+export default function Dashboard() {
+  return (
+    <div>
+      <Suspense fallback={<DashboardSkeleton />}>
+        <DashboardContent /> {/* Streams dynamically */}
+      </Suspense>
+    </div>
+  );
+}
+```
+
+**Key difference:** No `export const dynamic` needed. Components are dynamic by default - just wrap in Suspense to enable streaming.
+
+### Scenario 3: ISR with `revalidate` + On-Demand Revalidation
+
+**Before:**
+
+```tsx
+// app/blog/[slug]/page.tsx
+export const revalidate = 3600;
+
+export async function generateStaticParams() {
+  const posts = await getAllPosts();
+  return posts.map((post) => ({ slug: post.slug }));
+}
+
+export default async function BlogPost({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const post = await getPost(slug);
+  return <Article post={post} />;
+}
+
+// api/revalidate/route.ts
+export async function POST(request: Request) {
+  const { slug } = await request.json();
+  revalidatePath(`/blog/${slug}`);
+  return Response.json({ revalidated: true });
+}
+```
+
+**After:**
+
+```tsx
+// lib/posts.ts
+import { cacheTag, cacheLife } from "next/cache";
+
+export async function getPost(slug: string) {
+  "use cache";
+  cacheTag("posts", `post-${slug}`);
+  cacheLife("hours");
+
+  return db.posts.findUnique({ where: { slug } });
+}
+
+// app/blog/[slug]/page.tsx
+export default async function BlogPost({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const post = await getPost(slug);
+  return <Article post={post} />;
+}
+
+// app/api/revalidate/route.ts
+import { revalidatePath } from "next/cache";
+
+export async function POST(request: Request) {
+  const { slug } = await request.json();
+  revalidatePath(`/blog/${slug}`);
+  return Response.json({ revalidated: true });
+}
+```
+
+**Key improvements:**
+
+- Cache configuration co-located with data fetching via `'use cache'`
+- Explicit cache tags enable targeted invalidation
+- Route Handler pattern preserved for external webhook integration
+
+### Scenario 4: Page with `fetchCache` Export
+
+**Before:**
+
+```tsx
+// app/products/page.tsx
+export const fetchCache = "force-cache"; // All fetches cached
+
+export default async function ProductsPage() {
+  const products = await fetch("/api/products").then((r) => r.json());
+  const categories = await fetch("/api/categories").then((r) => r.json());
+  return <ProductGrid products={products} categories={categories} />;
+}
+```
+
+**After:**
+
+```tsx
+// app/products/page.tsx
+import { cacheLife, cacheTag } from "next/cache";
+
+async function getProducts() {
+  "use cache";
+  cacheTag("products");
+  cacheLife("hours");
+
+  return fetch("/api/products").then((r) => r.json());
+}
+
+async function getCategories() {
+  "use cache";
+  cacheTag("categories");
+  cacheLife("days");
+
+  return fetch("/api/categories").then((r) => r.json());
+}
+
+export default async function ProductsPage() {
+  const [products, categories] = await Promise.all([
+    getProducts(),
+    getCategories(),
+  ]);
+  return <ProductGrid products={products} categories={categories} />;
+}
+```
+
+**Key improvement:** Each data source has independent cache lifetime and tags, replacing the blanket `fetchCache` that applied the same policy to all fetches.
+
+---
+
+## Runtime Behaviors
+
+### Draft Mode
+
+When [Draft Mode](https://nextjs.org/docs/app/building-your-application/configuring/draft-mode) is enabled, cache entries are **not saved**:
+
+```tsx
+import { draftMode } from "next/headers";
+
+export default async function PreviewPage() {
+  const { isEnabled } = await draftMode();
+
+  // When isEnabled is true:
+  // - 'use cache' functions still execute
+  // - But results are NOT stored in cache
+  // - Ensures preview content is always fresh
+}
+```
+
+This prevents stale preview content from being cached and served to production users.
+
+### Cache Bypass Conditions
+
+Cache is bypassed (not read from) when:
+
+| Condition              | Description                                        |
+| ---------------------- | -------------------------------------------------- |
+| Draft Mode enabled     | `draftMode().isEnabled === true`                   |
+| On-demand revalidation | `revalidateTag()` or `revalidatePath()` was called |
+| Dev mode + no-cache    | Request includes `Cache-Control: no-cache` header  |
+
+### Metadata and Viewport
+
+`generateMetadata()` and `generateViewport()` are tracked **separately** from the page's cache. Even if a page uses `'use cache'`, these functions have their own caching behavior:
+
+```tsx
+// app/products/[id]/page.tsx
+
+// Metadata is cached independently from the page
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  const product = await getProduct(id); // May use its own 'use cache'
+  return { title: product.name, description: product.summary };
+}
+
+// Viewport follows the same independent tracking
+export async function generateViewport() {
+  return { themeColor: "#000000" };
+}
+
+// Page cache is separate from metadata cache
+export default async function ProductPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  return <ProductDetails productId={id} />;
+}
+```
+
+**Implication**: Invalidating a page's cache tags does not automatically invalidate its metadata. If metadata depends on cached data, ensure the relevant tags cover both.
+
+### Prerender Timeout
+
+During static prerendering (build time), cached functions have a **50-second timeout**:
+
+- If a cached function doesn't complete within 50 seconds, it becomes a dynamic hole
+- At request time, there is **no timeout** - background revalidation can take as long as needed
+- Timeout errors throw `UseCacheTimeoutError` with code `'USE_CACHE_TIMEOUT'`
+
+```tsx
+// If this takes >50s during build, it becomes dynamic
+async function SlowData() {
+  "use cache";
+  return await verySlowApiCall(); // May timeout during prerender
+}
+```
+
+### Development Mode: HMR Cache Invalidation
+
+In development, cache keys include an **HMR refresh hash**:
+
+- When you edit a file containing a cached function, the cache automatically invalidates
+- No manual cache clearing needed during development
+- This hash is not included in production builds
+
+### Cache Propagation (Nested Caches)
+
+When cached functions call other cached functions, cache metadata propagates **upward**:
+
+```tsx
+async function Inner() {
+  "use cache";
+  cacheLife("seconds"); // expire=60
+  cacheTag("inner");
+  return await fetchData();
+}
+
+async function Outer() {
+  "use cache";
+  cacheLife("hours"); // expire=86400
+  cacheTag("outer");
+
+  const data = await Inner(); // Calls inner cached function
+  return process(data);
+}
+
+// Outer's effective cache:
+// - expire = min(86400, 60) = 60 (inherits Inner's shorter expiration)
+// - tags = ['outer', 'inner'] (tags merge)
+```
+
+This ensures parent caches don't outlive their dependencies.
+
+### Runtime Environment Considerations
+
+Cache behavior varies depending on your deployment target:
+
+| Environment     | Cache Persistence                          | Configuration                              |
+| --------------- | ------------------------------------------ | ------------------------------------------ |
+| **Serverless**  | Cache does NOT persist between invocations | Use `'use cache: remote'` for shared state |
+| **Self-hosted** | In-memory cache persists across requests   | Configure `cacheMaxMemorySize`             |
+
+**Serverless (Vercel, AWS Lambda, etc.)**: Each function invocation starts with a cold cache. The default handler's in-memory cache is lost between invocations. Use `'use cache: remote'` or a platform-specific remote cache handler for data that must persist.
+
+**Self-hosted (Node.js server)**: The default cache handler uses in-memory storage that persists across requests for the lifetime of the process. Configure the maximum memory size:
+
+```typescript
+// next.config.ts
+const nextConfig: NextConfig = {
+  cacheHandlers: {
+    default: {
+      maxMemorySize: 52428800, // 50MB (default)
+    },
+  },
+};
+```
+
+Setting `maxMemorySize: 0` disables in-memory caching entirely, which can be useful when using an external cache handler exclusively.
+
+---
+
+## Type Definitions
+
+### CacheLife
+
+```typescript
+type CacheLife = {
+  stale?: number; // Default: 300 (from staleTimes.static)
+  revalidate?: number; // Default: profile-dependent
+  expire?: number; // Default: profile-dependent
+};
+```
+
+### CacheLifeProfile
+
+```typescript
+type CacheLifeProfile =
+  | "default"
+  | "seconds"
+  | "minutes"
+  | "hours"
+  | "days"
+  | "weeks"
+  | "max"
+  | string; // Custom profiles
+```
diff --git a/.claude/skills/cache-components/SKILL.md b/.claude/skills/cache-components/SKILL.md
new file mode 100644
index 000000000..1f4ab7fa2
--- /dev/null
+++ b/.claude/skills/cache-components/SKILL.md
@@ -0,0 +1,447 @@
+---
+name: cache-components
+description: "Expert guidance for Next.js Cache Components and Partial Prerendering (PPR). Use when implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, managing 'use cache: private' for compliance scenarios, pass-through/interleaving patterns, GET Route Handler caching, debugging cache issues, and reviewing Cache Component implementations."
+argument-hint: "[pattern or question]"
+metadata:
+  version: "1.0"
+---
+
+# Next.js Cache Components
+
+> **Auto-activation**: Activate this skill automatically in Next.js projects that have
+> `cacheComponents: true` in `next.config.ts`/`next.config.js`. When detected, apply Cache
+> Components patterns to all Server Component authoring, data fetching, and caching decisions.
+
+## Project Detection
+
+When starting work in a Next.js project, check if Cache Components are enabled:
+
+```bash
+# Check next.config.ts or next.config.js for cacheComponents
+grep -r "cacheComponents" next.config.* 2>/dev/null
+```
+
+If `cacheComponents: true` is found, apply this skill's patterns proactively when:
+
+- Writing React Server Components
+- Implementing data fetching
+- Creating Server Actions with mutations
+- Optimizing page performance
+- Reviewing existing component code
+
+Cache Components enable **Partial Prerendering (PPR)** - mixing static HTML shells with dynamic streaming content for optimal performance. Cache Components also enable state preservation during navigation with React's `<Activity>` component, which can keep cached component trees mounted but hidden.
+
+## Philosophy: Code Over Configuration
+
+Cache Components represents a shift from **segment configuration** to **compositional code**:
+
+| Before (Deprecated)                     | After (Cache Components)                  |
+| --------------------------------------- | ----------------------------------------- |
+| `export const revalidate = 3600`        | `cacheLife('hours')` inside `'use cache'` |
+| `export const dynamic = 'force-static'` | Use `'use cache'` and Suspense boundaries |
+| All-or-nothing static/dynamic           | Granular: static shell + cached + dynamic |
+
+**Key Principle**: Components co-locate their caching, not just their data. Next.js provides build-time feedback to guide you toward optimal patterns.
+
+## Core Concept
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Static Shell                       │
+│  (Sent immediately to browser)                       │
+│                                                      │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
+│  │   Header    │  │  Cached     │  │  Suspense   │  │
+│  │  (static)   │  │  Content    │  │  Fallback   │  │
+│  └─────────────┘  └─────────────┘  └──────┬──────┘  │
+│                                           │         │
+│                                    ┌──────▼──────┐  │
+│                                    │  Dynamic    │  │
+│                                    │  (streams)  │  │
+│                                    └─────────────┘  │
+└─────────────────────────────────────────────────────┘
+```
+
+## Mental Model: The Caching Decision Steps
+
+When writing a React Server Component, walk through these steps in order:
+
+1. **Does the component fetch data or perform I/O?**
+   - No → pure component, nothing to decide.
+   - Yes → continue.
+
+2. **Does it depend on request context** (`cookies()`, `headers()`, `searchParams`)?
+   - No → continue to step 3.
+   - Yes → continue to step 4.
+
+3. **(No request context) Is the data the same across users?**
+   - Yes → add `'use cache'` with `cacheTag()` and `cacheLife()`.
+   - No → wrap rendering in `<Suspense>` so the dynamic part streams at request time.
+
+4. **(Has request context) Can you extract the runtime data as function arguments?**
+   - Yes → read `cookies()`/`headers()` outside the cached scope, pass values
+     into a `'use cache'` function, and wrap the dynamic caller in `<Suspense>`.
+   - No (compliance prevents cross-request sharing) → use `'use cache: private'`
+     (experimental — not recommended for production) as a last resort, still
+     wrapped in `<Suspense>`.
+
+**Key insight**: `'use cache'` is for data that is the _same across users_. User-specific
+data stays dynamic and streams through `<Suspense>`. Reach for `'use cache: private'` only
+when you cannot refactor runtime data into arguments.
+
+## Quick Start
+
+### Enable Cache Components
+
+```typescript
+// next.config.ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+};
+
+export default nextConfig;
+```
+
+### Basic Usage
+
+```tsx
+// Cached component - output included in static shell
+async function CachedPosts() {
+  "use cache";
+  const posts = await db.posts.findMany();
+  return <PostList posts={posts} />;
+}
+
+// Page with static + cached + dynamic content
+export default async function BlogPage() {
+  return (
+    <>
+      <Header /> {/* Static */}
+      <CachedPosts /> {/* Cached */}
+      <Suspense fallback={<Skeleton />}>
+        <DynamicComments /> {/* Dynamic - streams */}
+      </Suspense>
+    </>
+  );
+}
+```
+
+## Server Actions vs Data Fetching (Critical Rule)
+
+**Server Actions are for MUTATIONS ONLY** - never for data fetching:
+
+| Purpose        | Use                              | Example Functions                                 |
+| -------------- | -------------------------------- | ------------------------------------------------- |
+| **Data fetch** | Server Component / `'use cache'` | `getProducts()`, `getUser(id)`                    |
+| **Mutation**   | Server Action (`'use server'`)   | `createProduct()`, `updateUser()`, `deletePost()` |
+
+### ❌ WRONG: Server Action for Data Fetching
+
+```tsx
+"use server";
+export async function getProducts() {
+  return await db.products.findMany(); // NO! This is not a mutation
+}
+
+("use server");
+export async function getTheme() {
+  return (await cookies()).get("theme")?.value; // NO! Just reading data
+}
+```
+
+### ✅ CORRECT: Data Function + Server Component
+
+```tsx
+// data/products.ts - Cached data function
+export async function getProducts() {
+  "use cache";
+  cacheTag("products");
+  cacheLife("hours");
+  return await db.products.findMany();
+}
+
+// page.tsx - Server Component reads data directly
+import { cookies } from "next/headers";
+
+export default async function Page() {
+  const products = await getProducts();
+  const theme = (await cookies()).get("theme")?.value ?? "light";
+  return <ProductList products={products} theme={theme} />;
+}
+```
+
+### ✅ CORRECT: Server Action for Mutation
+
+```tsx
+"use server";
+import { updateTag } from "next/cache";
+
+export async function createProduct(formData: FormData) {
+  await db.products.create({ data: formData });
+  updateTag("products"); // Invalidate cache after mutation
+}
+```
+
+## Core APIs
+
+### 1. `'use cache'` Directive
+
+Marks code as cacheable. Can be applied at three levels:
+
+```tsx
+// File-level: All exports are cached
+"use cache";
+export async function getData() {
+  /* ... */
+}
+export async function Component() {
+  /* ... */
+}
+
+// Component-level
+async function UserCard({ id }: { id: string }) {
+  "use cache";
+  const user = await fetchUser(id);
+  return <Card>{user.name}</Card>;
+}
+
+// Function-level
+async function fetchWithCache(url: string) {
+  "use cache";
+  return fetch(url).then((r) => r.json());
+}
+```
+
+**Important**: All cached functions must be `async`.
+
+### 2. `cacheLife()` - Control Cache Duration
+
+```tsx
+import { cacheLife } from "next/cache";
+
+async function Posts() {
+  "use cache";
+  cacheLife("hours"); // Use a predefined profile
+
+  // Or custom configuration:
+  cacheLife({
+    stale: 60, // 1 min - client cache validity
+    revalidate: 3600, // 1 hr - start background refresh
+    expire: 86400, // 1 day - absolute expiration
+  });
+
+  return await db.posts.findMany();
+}
+```
+
+**Predefined profiles**: `'default'`, `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`
+
+### 3. `cacheTag()` - Tag for Invalidation
+
+```tsx
+import { cacheTag } from "next/cache";
+
+async function BlogPosts() {
+  "use cache";
+  cacheTag("posts");
+  cacheLife("days");
+
+  return await db.posts.findMany();
+}
+
+async function UserProfile({ userId }: { userId: string }) {
+  "use cache";
+  cacheTag("users", `user-${userId}`); // Multiple tags
+
+  return await db.users.findUnique({ where: { id: userId } });
+}
+```
+
+### 4. `updateTag()` - Immediate Invalidation
+
+For **read-your-own-writes** semantics:
+
+```tsx
+"use server";
+import { updateTag } from "next/cache";
+
+export async function createPost(formData: FormData) {
+  await db.posts.create({ data: formData });
+
+  updateTag("posts"); // Client immediately sees fresh data
+}
+```
+
+### 5. `revalidateTag()` - Background Revalidation
+
+For stale-while-revalidate pattern:
+
+```tsx
+"use server";
+import { revalidateTag } from "next/cache";
+
+export async function updatePost(id: string, data: FormData) {
+  await db.posts.update({ where: { id }, data });
+
+  revalidateTag("posts", "max"); // Serve stale, refresh in background
+}
+```
+
+> **⚠️ Deprecated**: The single-argument form `revalidateTag('posts')` is deprecated.
+> Always pass a profile (`'max'` is recommended for stale-while-revalidate) or
+> `{ expire: <seconds> }` as the second argument. For webhooks that require immediate
+> expiration, use `revalidateTag(tag, { expire: 0 })`. For immediate read-your-own-writes
+> in Server Actions, prefer [`updateTag()`](#4-updatetag---immediate-invalidation) instead.
+
+## When to Use Each Pattern
+
+| Content Type | API                 | Behavior                              |
+| ------------ | ------------------- | ------------------------------------- |
+| **Static**   | No directive        | Rendered at build time                |
+| **Cached**   | `'use cache'`       | Included in static shell, revalidates |
+| **Dynamic**  | Inside `<Suspense>` | Streams at request time               |
+
+## Parameter Permutations & Subshells
+
+**Critical Concept**: With Cache Components, Next.js renders ALL permutations of provided parameters to create reusable subshells.
+
+```tsx
+// app/products/[category]/[slug]/page.tsx
+export async function generateStaticParams() {
+  return [
+    { category: "jackets", slug: "classic-bomber" },
+    { category: "jackets", slug: "essential-windbreaker" },
+    { category: "accessories", slug: "thermal-fleece-gloves" },
+  ];
+}
+```
+
+Next.js renders these routes:
+
+```
+/products/jackets/classic-bomber        ← Full params (complete page)
+/products/jackets/essential-windbreaker ← Full params (complete page)
+/products/accessories/thermal-fleece-gloves ← Full params (complete page)
+/products/jackets/[slug]                ← Partial params (category subshell)
+/products/accessories/[slug]            ← Partial params (category subshell)
+/products/[category]/[slug]             ← No params (fallback shell)
+```
+
+**Why this matters**: The category subshell (`/products/jackets/[slug]`) can be reused for ANY jacket product, even ones not in `generateStaticParams`. Users navigating to an unlisted jacket get the cached category shell immediately, with product details streaming in.
+
+### `generateStaticParams` Requirements
+
+With Cache Components enabled:
+
+1. **Must provide at least one parameter** - Empty arrays now cause build errors (prevents silent production failures)
+2. **Params prove static safety** - Providing params lets Next.js verify no dynamic APIs are called
+3. **Partial params create subshells** - Each unique permutation generates a reusable shell
+
+```tsx
+// ❌ ERROR with Cache Components
+export function generateStaticParams() {
+  return []; // Build error: must provide at least one param
+}
+
+// ✅ CORRECT: Provide real params
+export async function generateStaticParams() {
+  const products = await getPopularProducts();
+  return products.map(({ category, slug }) => ({ category, slug }));
+}
+```
+
+## Cache Key = Arguments
+
+Arguments become part of the cache key:
+
+```tsx
+// Different userId = different cache entry
+async function UserData({ userId }: { userId: string }) {
+  "use cache";
+  cacheTag(`user-${userId}`);
+
+  return await fetchUser(userId);
+}
+```
+
+## Build-Time Feedback
+
+Cache Components provides early feedback during development. These build errors **guide you toward optimal patterns**:
+
+### Error: Dynamic data outside Suspense
+
+```
+Error: Accessing cookies/headers/searchParams outside a Suspense boundary
+```
+
+**Solution**: Wrap dynamic components in `<Suspense>`:
+
+```tsx
+<Suspense fallback={<Skeleton />}>
+  <ComponentThatUsesCookies />
+</Suspense>
+```
+
+### Error: Uncached data outside Suspense
+
+```
+Error: Accessing uncached data outside Suspense
+```
+
+**Solution**: Either cache the data or wrap in Suspense:
+
+```tsx
+// Option 1: Cache it
+async function ProductData({ id }: { id: string }) {
+  "use cache";
+  return await db.products.findUnique({ where: { id } });
+}
+
+// Option 2: Make it dynamic with Suspense
+<Suspense fallback={<Loading />}>
+  <DynamicProductData id={id} />
+</Suspense>;
+```
+
+### Error: Request data inside cache
+
+```
+Error: Cannot access cookies/headers inside 'use cache'
+```
+
+**Solution**: Extract runtime data outside cache boundary (see "Handling Runtime Data" above).
+
+## Additional Resources
+
+- For complete API reference, see [REFERENCE.md](REFERENCE.md)
+- For common patterns and recipes, see [PATTERNS.md](PATTERNS.md)
+- For debugging and troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+
+## Code Generation Guidelines
+
+When generating Cache Component code:
+
+1. **Always use `async`** - All cached functions must be async
+2. **Place `'use cache'` first** - Must be first statement in function body
+3. **Call `cacheLife()` early** - Should follow `'use cache'` directive
+4. **Tag meaningfully** - Use semantic tags that match your invalidation needs
+5. **Extract runtime data** - Move `cookies()`/`headers()` outside cached scope
+6. **Wrap dynamic content** - Use `<Suspense>` for non-cached async components
+7. **Use `'use cache: private'` as last resort** - Experimental (not recommended for production). Only when runtime data cannot be extracted as params AND compliance requires no cross-request sharing
+
+## Review Checklist
+
+When reviewing code in Cache Components projects, flag these issues:
+
+- [ ] Data fetching without `'use cache'` where caching would benefit
+- [ ] Missing `cacheTag()` calls (makes invalidation impossible)
+- [ ] Missing `cacheLife()` (relies on defaults which may not be appropriate)
+- [ ] Server Actions without `updateTag()`/`revalidateTag()` after mutations
+- [ ] `cookies()`/`headers()` called inside `'use cache'` scope
+- [ ] Dynamic components without `<Suspense>` boundaries
+- [ ] **DEPRECATED**: `export const revalidate` - replace with `cacheLife()` in `'use cache'`
+- [ ] **DEPRECATED**: `export const dynamic` - replace with Suspense + cache boundaries
+- [ ] Empty `generateStaticParams()` return - must provide at least one param
+- [ ] Single-argument `revalidateTag('tag')` - use two-argument form with profile or `{ expire }`
diff --git a/.claude/skills/cache-components/TROUBLESHOOTING.md b/.claude/skills/cache-components/TROUBLESHOOTING.md
new file mode 100644
index 000000000..0de5a6aa1
--- /dev/null
+++ b/.claude/skills/cache-components/TROUBLESHOOTING.md
@@ -0,0 +1,875 @@
+# Cache Components Troubleshooting
+
+Common issues, debugging techniques, and solutions for Cache Components.
+
+## Contents
+
+- [Live error inspection via next-devtools-mcp](#live-error-inspection-via-next-devtools-mcp)
+- [Build-Time Feedback Philosophy](#build-time-feedback-philosophy)
+- [Quick Debugging Checklist](#quick-debugging-checklist)
+- [Error: UseCacheTimeoutError](#error-usecachetimeouterror)
+- [Error: Cannot use 'use cache' with sync function](#error-cannot-use-use-cache-with-sync-function)
+- [Error: Dynamic Data Outside Suspense](#error-dynamic-data-outside-suspense)
+- [Error: Uncached Data Outside Suspense](#error-uncached-data-outside-suspense)
+- [Error: Empty generateStaticParams](#error-empty-generatestaticparams)
+- [Error: Request Data Inside Cache](#error-request-data-inside-cache)
+- [Issue: Cache Not Being Used](#issue-cache-not-being-used)
+- [Issue: Stale Data After Mutation](#issue-stale-data-after-mutation)
+- [Issue: Different Cache Values for Same Key](#issue-different-cache-values-for-same-key)
+- [Issue: React.cache Deduplication Not Working Inside 'use cache'](#issue-reactcache-deduplication-not-working-inside-use-cache)
+- [Issue: Cache Too Aggressive (Stale Data)](#issue-cache-too-aggressive-stale-data)
+- [Issue: Build Takes Too Long](#issue-build-takes-too-long)
+- [Debugging Techniques](#debugging-techniques)
+- [Common Mistakes Checklist](#common-mistakes-checklist)
+- [Performance Optimization Tips](#performance-optimization-tips)
+
+## Live error inspection via next-devtools-mcp
+
+Next.js 16+ ships an MCP endpoint at `/_next/mcp`. When `next-devtools-mcp` is
+configured in `.mcp.json`, use these tools BEFORE asking the user to copy-paste
+errors:
+
+- `get_errors` — current build/runtime/type errors from the running dev server
+  (hydration mismatches, `'use cache'` violations, type errors all surface here)
+- `get_logs` — path to dev log file (browser console + server output)
+- `get_page_metadata` — for a specific page, shows route, components, rendering details
+
+Setup is one-line in `.mcp.json` — see
+[nextjs.org/docs/app/guides/mcp](https://nextjs.org/docs/app/guides/mcp).
+
+## Build-Time Feedback Philosophy
+
+Cache Components introduces **early feedback** during development. Unlike before where errors might only appear in production, Cache Components produces build errors that **guide you toward optimal patterns**.
+
+Key principle: **If it builds, it's correct.** The build process validates that:
+
+- Dynamic data isn't accessed outside Suspense boundaries
+- Cached data doesn't depend on request-specific APIs
+- `generateStaticParams` provides valid parameters to test rendering
+
+---
+
+## Quick Debugging Checklist
+
+Copy this checklist when debugging cache issues:
+
+### Cache Not Working
+
+- [ ] `cacheComponents: true` in next.config?
+- [ ] Function is `async`?
+- [ ] `'use cache'` is FIRST statement in function body?
+- [ ] All arguments are serializable (no functions, class instances)?
+- [ ] Not accessing `cookies()`/`headers()` inside cache?
+
+### Stale Data After Mutation
+
+- [ ] Called `updateTag()` or `revalidateTag()` after mutation?
+- [ ] Tag in invalidation matches tag in `cacheTag()`?
+- [ ] Using `updateTag()` (not `revalidateTag()`) for immediate updates?
+
+### Build Errors
+
+- [ ] Dynamic data wrapped in `<Suspense>`?
+- [ ] `generateStaticParams` returns at least one param?
+- [ ] Not mixing `'use cache'` with `cookies()`/`headers()`?
+
+### Performance Issues
+
+- [ ] Cache granularity appropriate? (not too coarse/fine)
+- [ ] `cacheLife` set appropriately for data volatility?
+- [ ] Using hierarchical tags for targeted invalidation?
+
+---
+
+## Error: UseCacheTimeoutError
+
+### Symptoms
+
+```
+Error: A component used 'use cache' but didn't complete within 50 seconds.
+```
+
+### Cause
+
+The cached function is accessing request-specific data (cookies, headers, searchParams) or making requests that depend on runtime context.
+
+### Solution
+
+User-specific content that depends on runtime data (cookies, headers, searchParams) should **not be cached**. Instead, stream it dynamically:
+
+```tsx
+// ❌ WRONG: Trying to cache user-specific content
+async function UserContent() {
+  "use cache";
+  const session = await cookies(); // Causes timeout!
+  return await fetchContent(session.userId);
+}
+
+// ✅ CORRECT: Don't cache user-specific content, stream it instead
+async function UserContent() {
+  const session = await cookies();
+  return await fetchContent(session.get("userId")?.value);
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <UserContent /> {/* No 'use cache' - streams dynamically */}
+    </Suspense>
+  );
+}
+```
+
+**Key insight**: Cache Components are for content that can be shared across users (e.g., product details, blog posts). User-specific content should stream at request time.
+
+---
+
+## Error: Cannot use 'use cache' with sync function
+
+### Symptoms
+
+```
+Error: 'use cache' can only be used in async functions
+```
+
+### Cause
+
+Cache Components require async functions because cached outputs are streamed.
+
+### Solution
+
+```tsx
+// ❌ WRONG: Synchronous function
+function CachedComponent() {
+  "use cache";
+  return <div>Hello</div>;
+}
+
+// ✅ CORRECT: Async function
+async function CachedComponent() {
+  "use cache";
+  return <div>Hello</div>;
+}
+```
+
+---
+
+## Error: Dynamic Data Outside Suspense
+
+### Symptoms
+
+```
+Error: Accessing cookies/headers/searchParams outside a Suspense boundary
+```
+
+### Cause
+
+With Cache Components, accessing request-specific APIs (cookies, headers, searchParams, connection) requires a Suspense boundary so Next.js can provide a static fallback.
+
+### Why This Changed
+
+**Before Cache Components**: The page silently became fully dynamic - no static content served.
+
+**After Cache Components**: Build error ensures you explicitly handle the dynamic boundary.
+
+### Solution
+
+Wrap dynamic content in Suspense:
+
+```tsx
+// ❌ ERROR: No Suspense boundary
+export default async function Page() {
+  return (
+    <>
+      <Header />
+      <UserDeals /> {/* Uses cookies() */}
+    </>
+  );
+}
+
+// ✅ CORRECT: Suspense provides static fallback
+export default async function Page() {
+  return (
+    <>
+      <Header />
+      <Suspense fallback={<DealsSkeleton />}>
+        <UserDeals />
+      </Suspense>
+    </>
+  );
+}
+```
+
+> **See also**: Pattern 1 (Static + Cached + Dynamic Page) in PATTERNS.md shows the foundational Suspense boundary pattern.
+
+---
+
+## Error: Uncached Data Outside Suspense
+
+### Symptoms
+
+```
+Error: Accessing uncached data outside Suspense
+```
+
+### Cause
+
+With Cache Components, ALL **async** I/O is considered dynamic by default. Database queries, fetch calls, and file reads must either be cached or wrapped in Suspense.
+
+> **Note on synchronous databases**: Libraries with synchronous APIs (e.g., `better-sqlite3`) don't trigger this error because they don't involve async I/O. Synchronous operations complete during render and are included in the static shell. However, this also means they block the render thread - use judiciously for small, fast queries only.
+
+### Solution
+
+Either cache the data or wrap in Suspense:
+
+```tsx
+// ❌ ERROR: Uncached database query without Suspense
+export default async function ProductPage({ params }) {
+  const product = await db.products.findUnique({ where: { id: params.id } });
+  return <ProductCard product={product} />;
+}
+
+// ✅ OPTION 1: Cache the data
+async function getProduct(id: string) {
+  "use cache";
+  cacheTag(`product-${id}`);
+  cacheLife("hours");
+
+  return await db.products.findUnique({ where: { id } });
+}
+
+export default async function ProductPage({ params }) {
+  const product = await getProduct(params.id);
+  return <ProductCard product={product} />;
+}
+
+// ✅ OPTION 2: Wrap in Suspense (streams dynamically)
+export default async function ProductPage({ params }) {
+  return (
+    <Suspense fallback={<ProductSkeleton />}>
+      <ProductContent id={params.id} />
+    </Suspense>
+  );
+}
+```
+
+> **See also**: Pattern 5 (Cached Data Fetching Functions) in PATTERNS.md shows reusable cached data fetcher patterns.
+
+---
+
+## Error: Empty generateStaticParams
+
+### Symptoms
+
+```
+Error: generateStaticParams must return at least one parameter set
+```
+
+### Cause
+
+With Cache Components, empty `generateStaticParams` is no longer allowed. This prevents a class of bugs where dynamic API usage in components would only error in production.
+
+### Why This Changed
+
+**Before**: Empty array = "trust me, this is static". Dynamic API usage in production caused runtime errors.
+
+**After**: Must provide at least one param set so Next.js can validate the page actually renders statically.
+
+### Solution
+
+```tsx
+// ❌ ERROR: Empty array
+export function generateStaticParams() {
+  return [];
+}
+
+// ✅ CORRECT: Provide at least one param
+export async function generateStaticParams() {
+  const products = await getPopularProducts();
+  return products.map(({ category, slug }) => ({ category, slug }));
+}
+
+// ✅ ALSO CORRECT: Hardcoded for known routes
+export function generateStaticParams() {
+  return [{ slug: "about" }, { slug: "contact" }, { slug: "pricing" }];
+}
+```
+
+---
+
+## Error: Request Data Inside Cache
+
+### Symptoms
+
+```
+Error: Cannot access cookies/headers inside 'use cache'
+```
+
+### Cause
+
+Cache contexts cannot depend on request-specific data because the cached result would be shared across all users.
+
+### Solution
+
+User-specific content should **not be cached**. Remove `'use cache'` and stream the content dynamically:
+
+```tsx
+// ❌ ERROR: Cookies inside cache
+async function UserDashboard() {
+  "use cache";
+  const session = await cookies(); // Error!
+  return await fetchDashboard(session.get("userId"));
+}
+
+// ✅ CORRECT: Don't cache user-specific content
+async function UserDashboard() {
+  const session = await cookies();
+  return await fetchDashboard(session.get("userId")?.value);
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<DashboardSkeleton />}>
+      <UserDashboard /> {/* Streams at request time */}
+    </Suspense>
+  );
+}
+```
+
+**Key insight**: Cache Components are for content that can be shared across users. User-specific dashboards should stream dynamically.
+
+---
+
+## Issue: Cache Not Being Used
+
+### Symptoms
+
+- Data always fresh on every request
+- No caching behavior observed
+- Build logs don't show cached routes
+
+### Checklist
+
+**1. Is `cacheComponents` enabled?**
+
+```typescript
+// next.config.ts
+const nextConfig: NextConfig = {
+  cacheComponents: true, // Required!
+};
+```
+
+**2. Is the function async?**
+
+```tsx
+// Must be async
+async function CachedData() {
+  "use cache";
+  return await fetchData();
+}
+```
+
+**3. Is `'use cache'` the first statement?**
+
+```tsx
+// ❌ WRONG: Directive not first
+async function CachedData() {
+  const x = 1; // Something before 'use cache'
+  ("use cache");
+  return await fetchData();
+}
+
+// ✅ CORRECT: Directive first
+async function CachedData() {
+  "use cache";
+  const x = 1;
+  return await fetchData();
+}
+```
+
+**4. Are arguments serializable?**
+
+```tsx
+// ❌ WRONG: Function as argument (not serializable)
+async function CachedData({ transform }: { transform: (x: any) => any }) {
+  "use cache";
+  const data = await fetchData();
+  return transform(data);
+}
+
+// ✅ CORRECT: Only serializable arguments
+async function CachedData({ transformType }: { transformType: string }) {
+  "use cache";
+  const data = await fetchData();
+  return applyTransform(data, transformType);
+}
+```
+
+---
+
+## Issue: Stale Data After Mutation
+
+### Symptoms
+
+- Created/updated data doesn't appear immediately
+- Need to refresh page to see changes
+
+### Cause
+
+Cache not invalidated after mutation.
+
+### Solutions
+
+**1. Use `updateTag()` for immediate consistency:**
+
+```tsx
+"use server";
+import { updateTag } from "next/cache";
+
+export async function createPost(data: FormData) {
+  await db.posts.create({ data });
+  updateTag("posts"); // Immediate invalidation
+}
+```
+
+**2. Ensure tags match:**
+
+```tsx
+// Cache uses this tag
+async function Posts() {
+  "use cache";
+  cacheTag("posts"); // Must match invalidation tag
+  return await db.posts.findMany();
+}
+
+// Invalidation must use same tag
+export async function createPost(data: FormData) {
+  await db.posts.create({ data });
+  updateTag("posts"); // Same tag!
+}
+```
+
+**3. Invalidate all relevant tags:**
+
+```tsx
+export async function updatePost(postId: string, data: FormData) {
+  const post = await db.posts.update({
+    where: { id: postId },
+    data,
+  });
+
+  // Invalidate all affected caches
+  updateTag("posts"); // All posts list
+  updateTag(`post-${postId}`); // Specific post
+  updateTag(`author-${post.authorId}`); // Author's posts
+}
+```
+
+---
+
+## Issue: Different Cache Values for Same Key
+
+### Symptoms
+
+- Cache returns different values for what should be the same query
+- Inconsistent behavior across requests
+
+### Cause
+
+Arguments are part of cache key. Different argument values = different cache entries.
+
+### Solution
+
+Normalize arguments:
+
+```tsx
+// ❌ Problem: Object reference differs
+async function CachedData({ options }: { options: { limit: number } }) {
+  'use cache'
+  return await fetchData(options)
+}
+
+// Each call creates new object = new cache key
+<CachedData options={{ limit: 10 }} />
+<CachedData options={{ limit: 10 }} /> // Different cache entry!
+
+// ✅ Solution: Use primitives or stable references
+async function CachedData({ limit }: { limit: number }) {
+  'use cache'
+  return await fetchData({ limit })
+}
+
+<CachedData limit={10} />
+<CachedData limit={10} /> // Same cache entry!
+```
+
+---
+
+## Issue: React.cache Deduplication Not Working Inside 'use cache'
+
+### Symptoms
+
+- `React.cache()` wrapped function is called multiple times instead of being deduplicated
+- Duplicate database queries or API calls from within `'use cache'` functions
+- Expected deduplication behavior works outside `'use cache'` but not inside
+
+### Cause
+
+`React.cache()` uses per-request storage for deduplication. `'use cache'` functions run in an isolated scope where this request-level storage is not available. The two caching mechanisms operate independently.
+
+### Solution
+
+Do not rely on `React.cache()` for deduplication inside `'use cache'` boundaries. Instead, rely on the `'use cache'` mechanism itself:
+
+```tsx
+import { cache } from "react";
+
+const getUser = cache(async (id: string) => {
+  return await db.users.findUnique({ where: { id } });
+});
+
+// ❌ WRONG: React.cache does not deduplicate inside 'use cache'
+async function CachedProfile({ userId }: { userId: string }) {
+  "use cache";
+  const user = await getUser(userId); // React.cache is isolated here
+  const posts = await getPostsByAuthor(userId);
+  return <Profile user={user} posts={posts} />;
+}
+
+// ✅ CORRECT: Extract shared data as a separate cached function
+async function getUser(id: string) {
+  "use cache";
+  cacheTag(`user-${id}`);
+  cacheLife("hours");
+  return await db.users.findUnique({ where: { id } });
+}
+
+// Both components share the same 'use cache' entry
+async function CachedProfile({ userId }: { userId: string }) {
+  "use cache";
+  const user = await getUser(userId); // Hits 'use cache' entry
+  return <Profile user={user} />;
+}
+```
+
+> **See also**: The "React.cache Isolation" section in REFERENCE.md explains the technical reason for this behavior.
+
+---
+
+## Issue: Cache Too Aggressive (Stale Data)
+
+### Symptoms
+
+- Data doesn't update when expected
+- Users see outdated content
+
+### Solutions
+
+**1. Reduce cache lifetime:**
+
+```tsx
+async function FrequentlyUpdatedData() {
+  "use cache";
+  cacheLife("seconds"); // Short cache
+
+  // Or custom short duration
+  cacheLife({
+    stale: 0,
+    revalidate: 30,
+    expire: 60,
+  });
+
+  return await fetchData();
+}
+```
+
+**2. Don't cache volatile data:**
+
+```tsx
+// For truly real-time data, skip caching
+async function LiveData() {
+  // No 'use cache'
+  return await fetchLiveData();
+}
+
+export default function Page() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <LiveData />
+    </Suspense>
+  );
+}
+```
+
+---
+
+## Issue: Build Takes Too Long
+
+### Symptoms
+
+- Build hangs during prerendering
+- Timeout errors during `next build`
+
+### Cause
+
+Cached functions making slow network requests or accessing unavailable services during build.
+
+### Solutions
+
+**1. Use fallback data for build:**
+
+```tsx
+async function CachedData() {
+  "use cache";
+
+  try {
+    return await fetchFromAPI();
+  } catch (error) {
+    // Return fallback during build if API unavailable
+    return getFallbackData();
+  }
+}
+```
+
+**2. Limit static generation scope:**
+
+```tsx
+// app/[slug]/page.tsx
+export function generateStaticParams() {
+  // Only prerender most important pages at build time
+  // Other pages will be generated on-demand at request time
+  return [{ slug: "home" }, { slug: "about" }];
+}
+```
+
+**3. Use Suspense for truly dynamic content:**
+
+```tsx
+// app/[slug]/page.tsx
+import { Suspense } from "react";
+
+export default function Page({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  return (
+    <Suspense fallback={<PageSkeleton />}>
+      <DynamicContent params={params} />
+    </Suspense>
+  );
+}
+```
+
+> **Note:** Avoid using `export const dynamic = 'force-dynamic'` as this segment config is deprecated with Cache Components. Use Suspense boundaries and `'use cache'` for granular control instead.
+
+### Avoid Passing Runtime Data Promises as Props to Cached Components
+
+**Symptoms**: Build hangs indefinitely during prerendering, eventually timing out.
+
+**Cause**: Passing a Promise that depends on runtime data (like `params` or `searchParams`) as a prop to a `'use cache'` component. During build, the Promise never resolves because no actual request exists.
+
+```tsx
+// ❌ WRONG: Passing params Promise into cached component
+async function CachedContent({
+  paramsPromise,
+}: {
+  paramsPromise: Promise<{ id: string }>;
+}) {
+  "use cache";
+  const { id } = await paramsPromise; // Hangs at build time!
+  return await fetchData(id);
+}
+
+export default function Page({ params }: { params: Promise<{ id: string }> }) {
+  return <CachedContent paramsPromise={params} />;
+}
+
+// ✅ CORRECT: Resolve params outside cache, pass primitives
+async function CachedContent({ id }: { id: string }) {
+  "use cache";
+  cacheTag(`content-${id}`);
+  return await fetchData(id);
+}
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  return <CachedContent id={id} />;
+}
+```
+
+**Rule**: Always resolve runtime Promises before passing their values into `'use cache'` functions. Pass resolved primitives, not Promises.
+
+### Avoid Shared Deduplication Storage Accessed by Cached Code
+
+**Symptoms**: Build hangs or produces inconsistent results. `React.cache()` calls inside `'use cache'` never complete.
+
+**Cause**: Code inside `'use cache'` tries to read from `React.cache()` or other per-request shared storage that doesn't exist during build-time prerendering. The deduplication mechanism waits for a request context that never arrives.
+
+```tsx
+import { cache } from "react";
+
+const getData = cache(async () => {
+  return await db.data.findMany();
+});
+
+// ❌ WRONG: React.cache inside 'use cache' may hang during build
+async function CachedWidget() {
+  "use cache";
+  const data = await getData(); // Deduplication storage not available
+  return <Widget data={data} />;
+}
+
+// ✅ CORRECT: Fetch directly or use a separate 'use cache' function
+async function CachedWidget() {
+  "use cache";
+  cacheTag("widget");
+  const data = await db.data.findMany(); // Direct fetch inside cache scope
+  return <Widget data={data} />;
+}
+```
+
+---
+
+## Debugging Techniques
+
+### 1. Check Cache Headers
+
+In development, inspect response headers:
+
+```bash
+curl -I http://localhost:3000/your-page
+```
+
+Look for:
+
+- `x-nextjs-cache: HIT` - Served from cache
+- `x-nextjs-cache: MISS` - Cache miss, recomputed
+- `x-nextjs-cache: STALE` - Stale content, revalidating
+
+### 2. Enable Verbose Logging
+
+```bash
+# Environment variable for cache debugging
+NEXT_PRIVATE_DEBUG_CACHE=1 npm run dev
+```
+
+### 3. Check Build Output
+
+```bash
+npm run build
+
+# Look for:
+# ○ (Static) - Fully static
+# ◐ (Partial) - Partial prerender with cache
+# λ (Dynamic) - Server-rendered
+```
+
+### 4. Inspect Cache Tags
+
+Add logging to verify tags:
+
+```tsx
+async function CachedData({ id }: { id: string }) {
+  "use cache";
+
+  const tags = ["data", `item-${id}`];
+  console.log("Cache tags:", tags); // Check during build
+
+  tags.forEach((tag) => cacheTag(tag));
+  cacheLife("hours");
+
+  return await fetchData(id);
+}
+```
+
+---
+
+## Common Mistakes Checklist
+
+| Mistake                            | Symptom            | Fix                   |
+| ---------------------------------- | ------------------ | --------------------- |
+| Missing `cacheComponents: true`    | No caching         | Add to next.config.ts |
+| Sync function with `'use cache'`   | Build error        | Make function async   |
+| `'use cache'` not first statement  | Cache ignored      | Move to first line    |
+| Accessing cookies/headers in cache | Timeout error      | Extract to wrapper    |
+| Non-serializable arguments         | Inconsistent cache | Use primitives        |
+| Missing Suspense for dynamic       | Streaming broken   | Wrap in Suspense      |
+| Wrong tag in invalidation          | Stale data         | Match cache tags      |
+| Over-caching volatile data         | Stale data         | Reduce cacheLife      |
+
+---
+
+## Performance Optimization Tips
+
+### 1. Profile Cache Hit Rates
+
+Monitor cache effectiveness:
+
+```tsx
+async function CachedData() {
+  "use cache";
+
+  const start = performance.now();
+  const data = await fetchData();
+  const duration = performance.now() - start;
+
+  // Log for analysis
+  console.log(`Cache execution: ${duration}ms`);
+
+  return data;
+}
+```
+
+### 2. Optimize Cache Granularity
+
+```tsx
+// ❌ Coarse: One big cached component
+async function PageContent() {
+  "use cache";
+  const header = await fetchHeader();
+  const posts = await fetchPosts();
+  const sidebar = await fetchSidebar();
+  return <>{/* everything */}</>;
+}
+
+// ✅ Fine-grained: Independent cached components
+async function Header() {
+  "use cache";
+  cacheLife("days");
+  return await fetchHeader();
+}
+
+async function Posts() {
+  "use cache";
+  cacheLife("hours");
+  return await fetchPosts();
+}
+
+async function Sidebar() {
+  "use cache";
+  cacheLife("minutes");
+  return await fetchSidebar();
+}
+```
+
+### 3. Strategic Tag Design
+
+```tsx
+// Hierarchical tags for targeted invalidation
+cacheTag(
+  "posts", // All posts
+  `category-${category}`, // Posts in category
+  `post-${id}`, // Specific post
+  `author-${authorId}`, // Author's posts
+);
+
+// Invalidate at appropriate level
+updateTag(`post-${id}`); // Single post changed
+updateTag(`author-${author}`); // Author updated all posts
+updateTag("posts"); // Nuclear option
+```
diff --git a/.claude/skills/frontend-design/SKILL.md b/.claude/skills/frontend-design/SKILL.md
new file mode 100644
index 000000000..0064574bb
--- /dev/null
+++ b/.claude/skills/frontend-design/SKILL.md
@@ -0,0 +1,46 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+argument-hint: "[description or file]"
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
diff --git a/.claude/skills/next-best-practices/SKILL.md b/.claude/skills/next-best-practices/SKILL.md
new file mode 100644
index 000000000..bd967fecd
--- /dev/null
+++ b/.claude/skills/next-best-practices/SKILL.md
@@ -0,0 +1,175 @@
+---
+name: next-best-practices
+description: Next.js App Router best practices covering file conventions, RSC boundaries, async APIs, data patterns, hydration errors, metadata, route handlers, image/font optimization, and bundling. Use when writing or reviewing Next.js code to prevent hydration errors, RSC violations, data waterfalls, and configuration mistakes.
+argument-hint: "[question or file]"
+---
+
+# Next.js Best Practices
+
+Apply these rules when writing or reviewing Next.js code.
+
+> **Cache Components patterns**: When the project has `cacheComponents: true` in `next.config.ts`,
+> use the separate `cache-components` skill for `'use cache'`, `cacheLife()`, `cacheTag()`,
+> `updateTag()`, and `revalidateTag()` guidance.
+
+## 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` (only this hook requires a boundary)
+- Forcing dynamic rendering with `connection()` instead
+
+## 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`
diff --git a/.claude/skills/next-best-practices/async-patterns.md b/.claude/skills/next-best-practices/async-patterns.md
new file mode 100644
index 000000000..0d5f91494
--- /dev/null
+++ b/.claude/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 .
+```
diff --git a/.claude/skills/next-best-practices/bundling.md b/.claude/skills/next-best-practices/bundling.md
new file mode 100644
index 000000000..4d09f56be
--- /dev/null
+++ b/.claude/skills/next-best-practices/bundling.md
@@ -0,0 +1,182 @@
+# 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
diff --git a/.claude/skills/next-best-practices/data-patterns.md b/.claude/skills/next-best-practices/data-patterns.md
new file mode 100644
index 000000000..ae8c7376e
--- /dev/null
+++ b/.claude/skills/next-best-practices/data-patterns.md
@@ -0,0 +1,314 @@
+# 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, updateTag } 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 } });
+
+  // In a Server Action, prefer updateTag (read-your-writes: expires the tag
+  // AND refreshes immediately so the user sees the change right away).
+  updateTag("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>
+  );
+}
+```
+
+> **Next.js 16 cache invalidation:** `revalidateTag(tag)` with a single argument
+> is **deprecated**. Either pass a `cacheLife` profile for stale-while-revalidate
+> (`revalidateTag('posts', 'max')`), or in a Server Action use `updateTag('posts')`
+> for read-your-writes semantics. There's also `refresh()` for refreshing only
+> uncached data. See the `cache-components` skill.
+
+**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   |
diff --git a/.claude/skills/next-best-practices/debug-tricks.md b/.claude/skills/next-best-practices/debug-tricks.md
new file mode 100644
index 000000000..a5a37b6b5
--- /dev/null
+++ b/.claude/skills/next-best-practices/debug-tricks.md
@@ -0,0 +1,146 @@
+# Debug Tricks
+
+Tricks to speed up debugging Next.js applications.
+
+## Next.js DevTools MCP (Dev Server)
+
+Next.js 16+ ships a built-in MCP endpoint at `/_next/mcp` in the dev server for
+AI-assisted debugging. **Requires Next.js 16 or above.**
+
+### Recommended setup: `next-devtools-mcp`
+
+The official, documented way is to add the `next-devtools-mcp` package to your
+project's `.mcp.json`. It auto-discovers and forwards to the running dev server
+(works across multiple instances/ports):
+
+```json
+// .mcp.json (project root)
+{
+  "mcpServers": {
+    "next-devtools": {
+      "command": "npx",
+      "args": ["-y", "next-devtools-mcp@latest"]
+    }
+  }
+}
+```
+
+Then `npm run dev` and your coding agent connects automatically.
+
+Reference: https://nextjs.org/docs/app/guides/mcp
+
+### Calling the raw endpoint directly (advanced)
+
+You can also hit the underlying `/_next/mcp` endpoint yourself. This is not the
+documented path but is useful for scripting.
+
+**Important**: Find the actual port of the running Next.js dev server (check terminal output or `package.json` scripts). Don't assume port 3000.
+
+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
diff --git a/.claude/skills/next-best-practices/directives.md b/.claude/skills/next-best-practices/directives.md
new file mode 100644
index 000000000..af4a6cd12
--- /dev/null
+++ b/.claude/skills/next-best-practices/directives.md
@@ -0,0 +1,74 @@
+# 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 `cache-components` skill.
+
+Reference: https://nextjs.org/docs/app/api-reference/directives/use-cache
diff --git a/.claude/skills/next-best-practices/error-handling.md b/.claude/skills/next-best-practices/error-handling.md
new file mode 100644
index 000000000..294b35461
--- /dev/null
+++ b/.claude/skills/next-best-practices/error-handling.md
@@ -0,0 +1,243 @@
+# 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
+
+> **Experimental (Next.js 16):** `forbidden()` and `unauthorized()` (and their
+> `forbidden.tsx` / `unauthorized.tsx` files) are **experimental and not
+> recommended for production**. They require enabling the flag in config:
+>
+> ```ts
+> // next.config.ts
+> const nextConfig = { experimental: { authInterrupts: true } };
+> ```
+>
+> `redirect`, `permanentRedirect`, and `notFound` are stable and need no flag.
+
+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
+```
diff --git a/.claude/skills/next-best-practices/file-conventions.md b/.claude/skills/next-best-practices/file-conventions.md
new file mode 100644
index 000000000..1ba2b839a
--- /dev/null
+++ b/.claude/skills/next-best-practices/file-conventions.md
@@ -0,0 +1,154 @@
+# 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` |
+
+**Key v16 differences:**
+
+- `proxy.ts` runs on the **Node.js runtime only**. The `runtime` config option is
+  **not allowed** in a proxy file — setting it throws an error.
+- `middleware.ts` is **deprecated** but still available for **Edge runtime** use
+  cases. It will be removed in a future version.
+- Without a `matcher`, proxy runs on **every** request (including `_next/static`,
+  `_next/image`, and `public/` assets) — add a negative matcher to exclude them.
+
+**Migration**: Run the dedicated codemod to rename the file and export:
+
+```bash
+npx @next/codemod@canary middleware-to-proxy .
+```
+
+## File Conventions Reference
+
+Reference: https://nextjs.org/docs/app/api-reference/file-conventions
diff --git a/.claude/skills/next-best-practices/font.md b/.claude/skills/next-best-practices/font.md
new file mode 100644
index 000000000..88362e6b0
--- /dev/null
+++ b/.claude/skills/next-best-practices/font.md
@@ -0,0 +1,257 @@
+# 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>;
+}
+```
diff --git a/.claude/skills/next-best-practices/functions.md b/.claude/skills/next-best-practices/functions.md
new file mode 100644
index 000000000..1feb0a3cb
--- /dev/null
+++ b/.claude/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 });
+}
+```
diff --git a/.claude/skills/next-best-practices/hydration-error.md b/.claude/skills/next-best-practices/hydration-error.md
new file mode 100644
index 000000000..988fe5dd8
--- /dev/null
+++ b/.claude/skills/next-best-practices/hydration-error.md
@@ -0,0 +1,88 @@
+# 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" />
+  );
+}
+```
diff --git a/.claude/skills/next-best-practices/image.md b/.claude/skills/next-best-practices/image.md
new file mode 100644
index 000000000..a5220bb7b
--- /dev/null
+++ b/.claude/skills/next-best-practices/image.md
@@ -0,0 +1,206 @@
+# 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
+      },
+    ],
+  },
+};
+```
+
+## Next.js 16 Config Changes
+
+Several `images` defaults changed in v16 — be aware when reviewing/upgrading:
+
+```js
+// next.config.ts
+const nextConfig = {
+  images: {
+    // quality is now coerced to the closest value in this list.
+    // Default changed from [1..100] to [75]. Add any other quality you use:
+    qualities: [50, 75, 90],
+
+    // Required to optimize LOCAL images whose `src` has a query string
+    // (v16 security change to prevent enumeration attacks).
+    localPatterns: [{ pathname: "/assets/**", search: "" }],
+
+    // Default changed from 60s to 4 hours (14400). Tune as needed.
+    minimumCacheTTL: 14400,
+  },
+};
+```
+
+- `images.domains` is **deprecated** — always use `remotePatterns` (below).
+- `next/legacy/image` is deprecated — use `next/image`.
+- `<Image quality={90} />` requires `90` to be present in `images.qualities`,
+  otherwise it is coerced to the nearest configured value.
+
+## 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}
+/>;
+```
diff --git a/.claude/skills/next-best-practices/metadata.md b/.claude/skills/next-best-practices/metadata.md
new file mode 100644
index 000000000..eb5755418
--- /dev/null
+++ b/.claude/skills/next-best-practices/metadata.md
@@ -0,0 +1,307 @@
+# 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:
+
+In Next.js 16, `params` is a `Promise` and the `id` passed to the default
+`Image` export is a `Promise<string>` — `await` both:
+
+```tsx
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from "next/og";
+
+type Props = { params: Promise<{ slug: string }> };
+
+export async function generateImageMetadata({ params }: Props) {
+  const { slug } = await params;
+  const images = await getPostImages(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,
+}: Props & { id: Promise<string> }) {
+  const { slug } = await params;
+  const imageId = await id;
+  const images = await getPostImages(slug);
+  const image = images[Number(imageId)];
+  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.
diff --git a/.claude/skills/next-best-practices/parallel-routes.md b/.claude/skills/next-best-practices/parallel-routes.md
new file mode 100644
index 000000000..f96682c6d
--- /dev/null
+++ b/.claude/skills/next-best-practices/parallel-routes.md
@@ -0,0 +1,302 @@
+# 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`.** In Next.js 16 this is
+enforced at build time: a missing `default.js` now **fails the build** (in
+earlier versions it produced a runtime 404 on hard navigation).
+
+```tsx
+// app/@modal/default.tsx
+export default function Default() {
+  return null; // or call notFound() to render the 404 UI
+}
+```
+
+Without this file, Next.js can't determine what to render in the `@modal` slot
+on hard navigation, so the build errors out.
+
+## 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 z-50 flex items-center justify-center bg-black/50"
+    >
+      <div className="mx-4 w-full max-w-2xl rounded-lg bg-white p-6">
+        <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` → Build Failure (v16)
+
+Every `@slot` folder needs a `default.tsx` that returns `null` (or calls
+`notFound()`). In Next.js 16 a missing `default.js` fails the build.
+
+### 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
diff --git a/.claude/skills/next-best-practices/route-handlers.md b/.claude/skills/next-best-practices/route-handlers.md
new file mode 100644
index 000000000..2b9a55070
--- /dev/null
+++ b/.claude/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.
diff --git a/.claude/skills/next-best-practices/rsc-boundaries.md b/.claude/skills/next-best-practices/rsc-boundaries.md
new file mode 100644
index 000000000..24fabe551
--- /dev/null
+++ b/.claude/skills/next-best-practices/rsc-boundaries.md
@@ -0,0 +1,158 @@
+# 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 serializable by React's Server
+Components serialization (this is **broader than JSON** — see the
+[`'use client'` reference](https://react.dev/reference/rsc/use-client#serializable-types)).
+
+**Serializable (safe to pass):** `string`, `number`, `bigint`, `boolean`,
+`undefined`, `null`, globally-registered symbols (`Symbol.for`), `Array`,
+`Map`, `Set`, `TypedArray`, `ArrayBuffer`, **`Date`**, plain objects,
+Promises, JSX elements, and Server Functions (`'use server'`).
+
+**Detect (NOT serializable):** Server component passes these to a client component:
+
+- Functions that are not Server Actions and not exported from a client module
+- Class instances (and objects with a `null` prototype)
+- `WeakMap`, `WeakSet`
+- Non-global symbols (e.g. `Symbol('x')`)
+
+> **Note:** `Date`, `Map`, and `Set` **are** serializable across the boundary —
+> you do not need to convert them. The only common footguns are functions and
+> class instances.
+
+```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
+// OK: Date is serializable - pass it directly, it arrives as a Date
+// page.tsx (server)
+export default async function Page() {
+  const post = await getPost();
+  return <PostCard createdAt={post.createdAt} />; // Date object - fine
+}
+
+// PostCard.tsx (client) - receives a real Date
+("use client");
+export function PostCard({ createdAt }: { createdAt: Date }) {
+  return <span>{createdAt.getFullYear()}</span>; // Works
+}
+```
+
+```tsx
+// OK: Map/Set are serializable too - no conversion needed
+<ClientComponent items={new Map([['a', 1]])} />
+<ClientComponent tags={new Set(['a', 'b'])} />
+```
+
+```tsx
+// Bad: Class instance (methods/prototype are lost)
+const user = new UserModel(data)
+<ClientProfile user={user} /> // Not serializable
+
+// Good: Pass plain object
+const user = await getUser()
+<ClientProfile user={{ id: user.id, name: user.name }} />
+```
+
+### 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 class instance to client       | No     | Pass plain object                     |
+| Pass `new WeakMap()`/`WeakSet()`    | No     | Convert to array/object               |
+| Pass `Symbol('x')` (non-global)     | No     | Use `Symbol.for('x')` or a string     |
+| Pass `new Date()` to client         | Yes    | - (serializable, arrives as `Date`)   |
+| Pass `new Map()`/`new Set()`        | Yes    | - (serializable)                      |
+| Pass server action to client        | Yes    | -                                     |
+| Pass `string/number/bigint/boolean` | Yes    | -                                     |
+| Pass plain object/array/Promise     | Yes    | -                                     |
diff --git a/.claude/skills/next-best-practices/runtime-selection.md b/.claude/skills/next-best-practices/runtime-selection.md
new file mode 100644
index 000000000..ac8db62af
--- /dev/null
+++ b/.claude/skills/next-best-practices/runtime-selection.md
@@ -0,0 +1,40 @@
+# 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/.claude/skills/next-best-practices/scripts.md b/.claude/skills/next-best-practices/scripts.md
new file mode 100644
index 000000000..df3bde500
--- /dev/null
+++ b/.claude/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   |
diff --git a/.claude/skills/next-best-practices/self-hosting.md b/.claude/skills/next-best-practices/self-hosting.md
new file mode 100644
index 000000000..de765d6d1
--- /dev/null
+++ b/.claude/skills/next-best-practices/self-hosting.md
@@ -0,0 +1,384 @@
+# 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
+```
diff --git a/.claude/skills/next-best-practices/suspense-boundaries.md b/.claude/skills/next-best-practices/suspense-boundaries.md
new file mode 100644
index 000000000..d1ed739e2
--- /dev/null
+++ b/.claude/skills/next-best-practices/suspense-boundaries.md
@@ -0,0 +1,69 @@
+# Suspense Boundaries
+
+`useSearchParams` is the one client hook that causes a CSR bailout without a
+Suspense boundary. Other navigation hooks (`usePathname`, `useParams`,
+`useRouter`) do **not** require one.
+
+## useSearchParams
+
+In a prerendered (static) route, calling `useSearchParams` makes the Client
+Component tree up to the nearest Suspense boundary client-side rendered. Without
+a boundary, a **production build fails** with the
+[Missing Suspense boundary with useSearchParams](https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout)
+error.
+
+> **Dev caveat:** routes render on-demand in dev, so `useSearchParams` doesn't
+> suspend and may appear to work without `Suspense` — the failure only shows up
+> in a production build.
+
+```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>
+  );
+}
+```
+
+## Forcing dynamic rendering instead
+
+If you intend the route to be dynamic anyway, call
+[`connection()`](https://nextjs.org/docs/app/api-reference/functions/connection)
+in a Server Component before rendering the hook's consumer. This opts the
+subtree out of prerendering, so no Suspense boundary is needed:
+
+```tsx
+import { connection } from "next/server";
+import SearchBar from "./search-bar";
+
+export default async function Page() {
+  await connection(); // route is now dynamic
+  return <SearchBar />;
+}
+```
+
+## Quick Reference
+
+| Hook                | Suspense Required   |
+| ------------------- | ------------------- |
+| `useSearchParams()` | Yes (static routes) |
+| `usePathname()`     | No                  |
+| `useParams()`       | No                  |
+| `useRouter()`       | No                  |
diff --git a/.claude/skills/react-best-practices/AGENTS.md b/.claude/skills/react-best-practices/AGENTS.md
new file mode 100644
index 000000000..55f642017
--- /dev/null
+++ b/.claude/skills/react-best-practices/AGENTS.md
@@ -0,0 +1,3784 @@
+# React Best Practices
+
+**Version 1.0.0**  
+Vercel Engineering  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring React and Next.js codebases. Humans  
+> may also find it useful, but guidance here is optimized for automation  
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
+   - 1.1 [Check Cheap Conditions Before Async Flags](#11-check-cheap-conditions-before-async-flags)
+   - 1.2 [Defer Await Until Needed](#12-defer-await-until-needed)
+   - 1.3 [Dependency-Based Parallelization](#13-dependency-based-parallelization)
+   - 1.4 [Prevent Waterfall Chains in API Routes](#14-prevent-waterfall-chains-in-api-routes)
+   - 1.5 [Promise.all() for Independent Operations](#15-promiseall-for-independent-operations)
+   - 1.6 [Strategic Suspense Boundaries](#16-strategic-suspense-boundaries)
+2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
+   - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports)
+   - 2.2 [Conditional Module Loading](#22-conditional-module-loading)
+   - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)
+   - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)
+   - 2.5 [Prefer Statically Analyzable Paths](#25-prefer-statically-analyzable-paths)
+   - 2.6 [Preload Based on User Intent](#26-preload-based-on-user-intent)
+3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
+   - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)
+   - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)
+   - 3.3 [Avoid Shared Module State for Request Data](#33-avoid-shared-module-state-for-request-data)
+   - 3.4 [Cross-Request LRU Caching](#34-cross-request-lru-caching)
+   - 3.5 [Hoist Static I/O to Module Level](#35-hoist-static-io-to-module-level)
+   - 3.6 [Minimize Serialization at RSC Boundaries](#36-minimize-serialization-at-rsc-boundaries)
+   - 3.7 [Parallel Data Fetching with Component Composition](#37-parallel-data-fetching-with-component-composition)
+   - 3.8 [Parallel Nested Data Fetching](#38-parallel-nested-data-fetching)
+   - 3.9 [Per-Request Deduplication with React.cache()](#39-per-request-deduplication-with-reactcache)
+   - 3.10 [Use after() for Non-Blocking Operations](#310-use-after-for-non-blocking-operations)
+4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**
+   - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners)
+   - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance)
+   - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication)
+   - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data)
+5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**
+   - 5.1 [Calculate Derived State During Rendering](#51-calculate-derived-state-during-rendering)
+   - 5.2 [Defer State Reads to Usage Point](#52-defer-state-reads-to-usage-point)
+   - 5.3 [Do not wrap a simple expression with a primitive result type in useMemo](#53-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo)
+   - 5.4 [Don't Define Components Inside Components](#54-dont-define-components-inside-components)
+   - 5.5 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#55-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant)
+   - 5.6 [Extract to Memoized Components](#56-extract-to-memoized-components)
+   - 5.7 [Narrow Effect Dependencies](#57-narrow-effect-dependencies)
+   - 5.8 [Put Interaction Logic in Event Handlers](#58-put-interaction-logic-in-event-handlers)
+   - 5.9 [Split Combined Hook Computations](#59-split-combined-hook-computations)
+   - 5.10 [Subscribe to Derived State](#510-subscribe-to-derived-state)
+   - 5.11 [Use Functional setState Updates](#511-use-functional-setstate-updates)
+   - 5.12 [Use Lazy State Initialization](#512-use-lazy-state-initialization)
+   - 5.13 [Use Transitions for Non-Urgent Updates](#513-use-transitions-for-non-urgent-updates)
+   - 5.14 [Use useDeferredValue for Expensive Derived Renders](#514-use-usedeferredvalue-for-expensive-derived-renders)
+   - 5.15 [Use useRef for Transient Values](#515-use-useref-for-transient-values)
+6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**
+   - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element)
+   - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists)
+   - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements)
+   - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision)
+   - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering)
+   - 6.6 [Suppress Expected Hydration Mismatches](#66-suppress-expected-hydration-mismatches)
+   - 6.7 [Use Activity Component for Show/Hide](#67-use-activity-component-for-showhide)
+   - 6.8 [Use defer or async on Script Tags](#68-use-defer-or-async-on-script-tags)
+   - 6.9 [Use Explicit Conditional Rendering](#69-use-explicit-conditional-rendering)
+   - 6.10 [Use React DOM Resource Hints](#610-use-react-dom-resource-hints)
+   - 6.11 [Use useTransition Over Manual Loading States](#611-use-usetransition-over-manual-loading-states)
+7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**
+   - 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing)
+   - 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups)
+   - 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops)
+   - 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls)
+   - 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls)
+   - 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations)
+   - 7.7 [Defer Non-Critical Work with requestIdleCallback](#77-defer-non-critical-work-with-requestidlecallback)
+   - 7.8 [Early Length Check for Array Comparisons](#78-early-length-check-for-array-comparisons)
+   - 7.9 [Early Return from Functions](#79-early-return-from-functions)
+   - 7.10 [Hoist RegExp Creation](#710-hoist-regexp-creation)
+   - 7.11 [Use flatMap to Map and Filter in One Pass](#711-use-flatmap-to-map-and-filter-in-one-pass)
+   - 7.12 [Use Loop for Min/Max Instead of Sort](#712-use-loop-for-minmax-instead-of-sort)
+   - 7.13 [Use Set/Map for O(1) Lookups](#713-use-setmap-for-o1-lookups)
+   - 7.14 [Use toSorted() Instead of sort() for Immutability](#714-use-tosorted-instead-of-sort-for-immutability)
+8. [Advanced Patterns](#8-advanced-patterns) — **LOW**
+   - 8.1 [Do Not Put Effect Events in Dependency Arrays](#81-do-not-put-effect-events-in-dependency-arrays)
+   - 8.2 [Initialize App Once, Not Per Mount](#82-initialize-app-once-not-per-mount)
+   - 8.3 [Store Event Handlers in Refs](#83-store-event-handlers-in-refs)
+   - 8.4 [useEffectEvent for Stable Callback Refs](#84-useeffectevent-for-stable-callback-refs)
+
+---
+
+## 1. Eliminating Waterfalls
+
+**Impact: CRITICAL**
+
+Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+### 1.1 Check Cheap Conditions Before Async Flags
+
+**Impact: HIGH (avoids unnecessary async work when a synchronous guard already fails)**
+
+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.
+
+### 1.2 Defer Await Until Needed
+
+**Impact: HIGH (avoids blocking unused code paths)**
+
+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).
+
+### 1.3 Dependency-Based Parallelization
+
+**Impact: CRITICAL (2-10× improvement)**
+
+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:**
+
+```typescript
+const userPromise = fetchUser();
+const profilePromise = userPromise.then((user) => fetchProfile(user.id));
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise,
+]);
+```
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+
+### 1.4 Prevent Waterfall Chains in API Routes
+
+**Impact: CRITICAL (2-10× improvement)**
+
+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).
+
+### 1.5 Promise.all() for Independent Operations
+
+**Impact: CRITICAL (2-10× improvement)**
+
+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(),
+]);
+```
+
+### 1.6 Strategic Suspense Boundaries
+
+**Impact: HIGH (faster initial paint)**
+
+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.
+
+---
+
+## 2. Bundle Size Optimization
+
+**Impact: CRITICAL**
+
+Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+### 2.1 Avoid Barrel File Imports
+
+**Impact: CRITICAL (200-800ms import cost, slow builds)**
+
+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):**
+
+```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: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+
+### 2.2 Conditional Module Loading
+
+**Impact: HIGH (loads large data only when needed)**
+
+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.
+
+### 2.3 Defer Non-Critical Third-Party Libraries
+
+**Impact: MEDIUM (loads after hydration)**
+
+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>
+  );
+}
+```
+
+### 2.4 Dynamic Imports for Heavy Components
+
+**Impact: CRITICAL (directly affects TTI and LCP)**
+
+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} />;
+}
+```
+
+### 2.5 Prefer Statically Analyzable Paths
+
+**Impact: HIGH (avoids accidental broad bundles and file traces)**
+
+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
+
+**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]();
+```
+
+**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: [https://nextjs.org/docs/app/api-reference/config/next-config-js/output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [https://nextjs.org/learn/seo/dynamic-imports](https://nextjs.org/learn/seo/dynamic-imports), [https://vite.dev/guide/features.html](https://vite.dev/guide/features.html), [https://esbuild.github.io/api/](https://esbuild.github.io/api/), [https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [https://webpack.js.org/guides/dependency-management/](https://webpack.js.org/guides/dependency-management/)
+
+### 2.6 Preload Based on User Intent
+
+**Impact: MEDIUM (reduces perceived latency)**
+
+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.
+
+---
+
+## 3. Server-Side Performance
+
+**Impact: HIGH**
+
+Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+### 3.1 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)
+
+### 3.2 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:**
+
+```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)
+```
+
+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
+
+**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.
+
+### 3.3 Avoid Shared Module State for Request Data
+
+**Impact: HIGH (prevents concurrency bugs and request data leaks)**
+
+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).
+
+### 3.4 Cross-Request LRU Caching
+
+**Impact: HIGH (caches across requests)**
+
+`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)
+
+### 3.5 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.
+
+### 3.6 Minimize Serialization at RSC Boundaries
+
+**Impact: HIGH (reduces data transfer size)**
+
+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>;
+}
+```
+
+### 3.7 Parallel Data Fetching with Component Composition
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+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>
+  );
+}
+```
+
+### 3.8 Parallel Nested Data Fetching
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+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.
+
+### 3.9 Per-Request Deduplication with React.cache()
+
+**Impact: MEDIUM (deduplicates within request)**
+
+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 params = { uid: 1 };
+getUser(params); // Query runs
+getUser(params); // Cache hit (same reference)
+```
+
+If you must pass objects, pass the 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: [https://react.dev/reference/react/cache](https://react.dev/reference/react/cache)
+
+### 3.10 Use after() for Non-Blocking Operations
+
+**Impact: MEDIUM (faster response times)**
+
+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)
+
+---
+
+## 4. Client-Side Data Fetching
+
+**Impact: MEDIUM-HIGH**
+
+Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+### 4.1 Deduplicate Global Event Listeners
+
+**Impact: LOW (single listener for N components)**
+
+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", () => {
+    /* ... */
+  });
+  // ...
+}
+```
+
+### 4.2 Use Passive Event Listeners for Scrolling Performance
+
+**Impact: MEDIUM (eliminates scroll delay caused by event listeners)**
+
+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()`.
+
+### 4.3 Use SWR for Automatic Deduplication
+
+**Impact: MEDIUM-HIGH (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)
+
+### 4.4 Version and Minimize localStorage Data
+
+**Impact: MEDIUM (prevents schema conflicts, reduces storage size)**
+
+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.
+
+---
+
+## 5. Re-render Optimization
+
+**Impact: MEDIUM**
+
+Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+### 5.1 Calculate Derived State During Rendering
+
+**Impact: MEDIUM (avoids redundant renders and state drift)**
+
+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>;
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect](https://react.dev/learn/you-might-not-need-an-effect)
+
+### 5.2 Defer State Reads to Usage Point
+
+**Impact: MEDIUM (avoids unnecessary subscriptions)**
+
+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>;
+}
+```
+
+### 5.3 Do not wrap a simple expression with a primitive result type in useMemo
+
+**Impact: LOW-MEDIUM (wasted computation on every render)**
+
+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
+}
+```
+
+### 5.4 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
+
+### 5.5 Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+**Impact: MEDIUM (restores memoization by using a constant for default value)**
+
+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 />
+```
+
+### 5.6 Extract to Memoized Components
+
+**Impact: MEDIUM (enables early returns)**
+
+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.
+
+### 5.7 Narrow Effect Dependencies
+
+**Impact: LOW (minimizes effect re-runs)**
+
+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]);
+```
+
+### 5.8 Put Interaction Logic in Event Handlers
+
+**Impact: MEDIUM (avoids effect re-runs and duplicate side effects)**
+
+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: [https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
+
+### 5.9 Split Combined Hook Computations
+
+**Impact: MEDIUM (avoids recomputing independent steps)**
+
+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.
+
+### 5.10 Subscribe to Derived State
+
+**Impact: MEDIUM (reduces re-render frequency)**
+
+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"} />;
+}
+```
+
+### 5.11 Use Functional setState Updates
+
+**Impact: MEDIUM (prevents stale closures and unnecessary callback recreations)**
+
+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.
+
+### 5.12 Use Lazy State Initialization
+
+**Impact: MEDIUM (wasted computation on every render)**
+
+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.
+
+### 5.13 Use Transitions for Non-Urgent Updates
+
+**Impact: MEDIUM (maintains UI responsiveness)**
+
+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);
+  }, []);
+}
+```
+
+### 5.14 Use useDeferredValue for Expensive Derived Renders
+
+**Impact: MEDIUM (keeps input responsive during heavy computation)**
+
+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: [https://react.dev/reference/react/useDeferredValue](https://react.dev/reference/react/useDeferredValue)
+
+### 5.15 Use useRef for Transient Values
+
+**Impact: MEDIUM (avoids unnecessary re-renders on frequent updates)**
+
+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)",
+      }}
+    />
+  );
+}
+```
+
+---
+
+## 6. Rendering Performance
+
+**Impact: MEDIUM**
+
+Optimizing the rendering process reduces the work the browser needs to do.
+
+### 6.1 Animate SVG Wrapper Instead of SVG Element
+
+**Impact: LOW (enables hardware acceleration)**
+
+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.
+
+### 6.2 CSS content-visibility for Long Lists
+
+**Impact: HIGH (faster initial render)**
+
+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="h-screen overflow-y-auto">
+      {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).
+
+### 6.3 Hoist Static JSX Elements
+
+**Impact: LOW (avoids re-creation)**
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect: recreates element every render**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="h-20 animate-pulse bg-gray-200" />;
+}
+
+function Container() {
+  return <div>{loading && <LoadingSkeleton />}</div>;
+}
+```
+
+**Correct: reuses same element**
+
+```tsx
+const loadingSkeleton = <div className="h-20 animate-pulse 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.
+
+### 6.4 Optimize SVG Precision
+
+**Impact: LOW (reduces file size)**
+
+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
+```
+
+### 6.5 Prevent Hydration Mismatch Without Flickering
+
+**Impact: MEDIUM (avoids visual flicker and hydration errors)**
+
+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.
+
+### 6.6 Suppress Expected Hydration Mismatches
+
+**Impact: LOW-MEDIUM (avoids noisy hydration warnings for known differences)**
+
+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>;
+}
+```
+
+### 6.7 Use Activity Component for Show/Hide
+
+**Impact: MEDIUM (preserves state/DOM)**
+
+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.
+
+### 6.8 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
+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" />
+    </>
+  );
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+Reference: [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
+
+### 6.9 Use Explicit Conditional Rendering
+
+**Impact: LOW (prevents rendering 0 or NaN)**
+
+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>
+```
+
+### 6.10 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: [https://react.dev/reference/react-dom#resource-preloading-apis](https://react.dev/reference/react-dom#resource-preloading-apis)
+
+### 6.11 Use useTransition Over Manual Loading States
+
+**Impact: LOW (reduces re-renders and improves code clarity)**
+
+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: [https://react.dev/reference/react/useTransition](https://react.dev/reference/react/useTransition)
+
+---
+
+## 7. JavaScript Performance
+
+**Impact: LOW-MEDIUM**
+
+Micro-optimizations for hot paths can add up to meaningful improvements.
+
+### 7.1 Avoid Layout Thrashing
+
+**Impact: MEDIUM (prevents forced synchronous layouts and reduces performance bottlenecks)**
+
+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 updateElementStyles(element: HTMLElement) {
+  element.classList.add("highlighted-box");
+
+  const { width, height } = element.getBoundingClientRect();
+}
+```
+
+**Better: use CSS classes**
+
+**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.
+
+### 7.2 Build Index Maps for Repeated Lookups
+
+**Impact: LOW-MEDIUM (1M ops to 2K ops)**
+
+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.
+
+### 7.3 Cache Property Access in Loops
+
+**Impact: LOW-MEDIUM (reduces lookups)**
+
+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);
+}
+```
+
+### 7.4 Cache Repeated Function Calls
+
+**Impact: MEDIUM (avoid redundant computation)**
+
+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: [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+
+### 7.5 Cache Storage API Calls
+
+**Impact: LOW-MEDIUM (reduces expensive I/O)**
+
+`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**
+
+```typescript
+window.addEventListener("storage", (e) => {
+  if (e.key) storageCache.delete(e.key);
+});
+
+document.addEventListener("visibilitychange", () => {
+  if (document.visibilityState === "visible") {
+    storageCache.clear();
+  }
+});
+```
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+### 7.6 Combine Multiple Array Iterations
+
+**Impact: LOW-MEDIUM (reduces 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);
+}
+```
+
+### 7.7 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
+
+### 7.8 Early Length Check for Array Comparisons
+
+**Impact: MEDIUM-HIGH (avoids expensive operations when lengths differ)**
+
+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
+
+### 7.9 Early Return from Functions
+
+**Impact: LOW-MEDIUM (avoids unnecessary computation)**
+
+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 };
+}
+```
+
+### 7.10 Hoist RegExp Creation
+
+**Impact: LOW-MEDIUM (avoids recreation)**
+
+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**
+
+```typescript
+const regex = /foo/g;
+regex.test("foo"); // true, lastIndex = 3
+regex.test("foo"); // false, lastIndex = 0
+```
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+### 7.11 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
+
+### 7.12 Use Loop for Min/Max Instead of Sort
+
+**Impact: LOW (O(n) instead of O(n log n))**
+
+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.
+
+### 7.13 Use Set/Map for O(1) Lookups
+
+**Impact: LOW-MEDIUM (O(n) to O(1))**
+
+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))
+```
+
+### 7.14 Use toSorted() Instead of sort() for Immutability
+
+**Impact: MEDIUM-HIGH (prevents mutation bugs in React state)**
+
+`.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**
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value);
+```
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+
+- `.toReversed()` - immutable reverse
+
+- `.toSpliced()` - immutable splice
+
+- `.with()` - immutable element replacement
+
+---
+
+## 8. Advanced Patterns
+
+**Impact: LOW**
+
+Advanced patterns for specific cases that require careful implementation.
+
+### 8.1 Do Not Put Effect Events in Dependency Arrays
+
+**Impact: LOW (avoids unnecessary effect re-runs and lint errors)**
+
+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: [https://react.dev/reference/react/useEffectEvent#effect-event-in-deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)
+
+### 8.2 Initialize App Once, Not Per Mount
+
+**Impact: LOW-MEDIUM (avoids duplicate init in development)**
+
+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: [https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+### 8.3 Store Event Handlers in Refs
+
+**Impact: LOW (stable subscriptions)**
+
+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
+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]);
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+### 8.4 useEffectEvent for Stable Callback Refs
+
+**Impact: LOW (prevents effect re-runs)**
+
+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]);
+}
+```
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://nextjs.org](https://nextjs.org)
+3. [https://swr.vercel.app](https://swr.vercel.app)
+4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/.claude/skills/react-best-practices/README.md b/.claude/skills/react-best-practices/README.md
new file mode 100644
index 000000000..e48a52cd0
--- /dev/null
+++ b/.claude/skills/react-best-practices/README.md
@@ -0,0 +1,127 @@
+# 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).
diff --git a/.claude/skills/react-best-practices/SKILL.md b/.claude/skills/react-best-practices/SKILL.md
new file mode 100644
index 000000000..fed667cbc
--- /dev/null
+++ b/.claude/skills/react-best-practices/SKILL.md
@@ -0,0 +1,161 @@
+---
+name: react-best-practices
+description: React and Next.js performance optimization guide from Vercel Engineering (70 rules in 8 categories). Use when writing, reviewing, or refactoring React/Next.js code to eliminate waterfalls, reduce bundle size, prevent re-renders, optimize Server Components, or fix performance bottlenecks. Triggers on data fetching, Promise.all, Suspense, useMemo, dynamic imports, bundle analysis, code-splitting, and rendering performance tasks.
+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.
+
+## Version Compatibility
+
+| Feature                                              | Minimum version       |
+| ---------------------------------------------------- | --------------------- |
+| Core performance rules (async, bundle, js)           | React 18 + Next.js 14 |
+| `React.cache()` (`server-cache-react`)               | React 19              |
+| `<Activity>` (`rendering-activity`)                  | React 19.2            |
+| React Compiler (affects `rerender-*` rules)          | React 19              |
+| `use cache` directive (see `cache-components` skill) | Next.js 16            |
+
+## 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`
diff --git a/.claude/skills/react-best-practices/metadata.json b/.claude/skills/react-best-practices/metadata.json
new file mode 100644
index 000000000..f859e2abf
--- /dev/null
+++ b/.claude/skills/react-best-practices/metadata.json
@@ -0,0 +1,15 @@
+{
+  "version": "1.0.0",
+  "organization": "Vercel Engineering",
+  "date": "January 2026",
+  "abstract": "Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 70 rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.",
+  "references": [
+    "https://react.dev",
+    "https://nextjs.org",
+    "https://swr.vercel.app",
+    "https://github.com/shuding/better-all",
+    "https://github.com/isaacs/node-lru-cache",
+    "https://vercel.com/blog/how-we-optimized-package-imports-in-next-js",
+    "https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast"
+  ]
+}
diff --git a/.claude/skills/react-best-practices/rules/_sections.md b/.claude/skills/react-best-practices/rules/_sections.md
new file mode 100644
index 000000000..4d20c144b
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/_template.md b/.claude/skills/react-best-practices/rules/_template.md
new file mode 100644
index 000000000..77535dc9b
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/advanced-effect-event-deps.md b/.claude/skills/react-best-practices/rules/advanced-effect-event-deps.md
new file mode 100644
index 000000000..8bea3b8f2
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/advanced-effect-event-deps.md
@@ -0,0 +1,62 @@
+---
+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)
diff --git a/.claude/skills/react-best-practices/rules/advanced-event-handler-refs.md b/.claude/skills/react-best-practices/rules/advanced-event-handler-refs.md
new file mode 100644
index 000000000..435261a66
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/advanced-init-once.md b/.claude/skills/react-best-practices/rules/advanced-init-once.md
new file mode 100644
index 000000000..1cf8de795
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/advanced-use-latest.md b/.claude/skills/react-best-practices/rules/advanced-use-latest.md
new file mode 100644
index 000000000..45e2842da
--- /dev/null
+++ b/.claude/skills/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]);
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/async-api-routes.md b/.claude/skills/react-best-practices/rules/async-api-routes.md
new file mode 100644
index 000000000..833833183
--- /dev/null
+++ b/.claude/skills/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).
diff --git a/.claude/skills/react-best-practices/rules/async-cheap-condition-before-await.md b/.claude/skills/react-best-practices/rules/async-cheap-condition-before-await.md
new file mode 100644
index 000000000..d9491a559
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/async-defer-await.md b/.claude/skills/react-best-practices/rules/async-defer-await.md
new file mode 100644
index 000000000..2b4d821db
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/async-defer-await.md
@@ -0,0 +1,80 @@
+---
+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.
diff --git a/.claude/skills/react-best-practices/rules/async-dependencies.md b/.claude/skills/react-best-practices/rules/async-dependencies.md
new file mode 100644
index 000000000..405074d9f
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/async-dependencies.md
@@ -0,0 +1,52 @@
+---
+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)
diff --git a/.claude/skills/react-best-practices/rules/async-parallel.md b/.claude/skills/react-best-practices/rules/async-parallel.md
new file mode 100644
index 000000000..91102101e
--- /dev/null
+++ b/.claude/skills/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(),
+]);
+```
diff --git a/.claude/skills/react-best-practices/rules/async-suspense-boundaries.md b/.claude/skills/react-best-practices/rules/async-suspense-boundaries.md
new file mode 100644
index 000000000..790027e5d
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/bundle-analyzable-paths.md b/.claude/skills/react-best-practices/rules/bundle-analyzable-paths.md
new file mode 100644
index 000000000..ad78bcca3
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/bundle-analyzable-paths.md
@@ -0,0 +1,64 @@
+---
+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/)
diff --git a/.claude/skills/react-best-practices/rules/bundle-barrel-imports.md b/.claude/skills/react-best-practices/rules/bundle-barrel-imports.md
new file mode 100644
index 000000000..93f7660a2
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/bundle-conditional.md b/.claude/skills/react-best-practices/rules/bundle-conditional.md
new file mode 100644
index 000000000..a541a0208
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/bundle-conditional.md
@@ -0,0 +1,37 @@
+---
+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.
diff --git a/.claude/skills/react-best-practices/rules/bundle-defer-third-party.md b/.claude/skills/react-best-practices/rules/bundle-defer-third-party.md
new file mode 100644
index 000000000..b65b097d1
--- /dev/null
+++ b/.claude/skills/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>
+  );
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/bundle-dynamic-imports.md b/.claude/skills/react-best-practices/rules/bundle-dynamic-imports.md
new file mode 100644
index 000000000..4fbd3d937
--- /dev/null
+++ b/.claude/skills/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} />;
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/bundle-preload.md b/.claude/skills/react-best-practices/rules/bundle-preload.md
new file mode 100644
index 000000000..d38946dc7
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/bundle-preload.md
@@ -0,0 +1,46 @@
+---
+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.
diff --git a/.claude/skills/react-best-practices/rules/client-event-listeners.md b/.claude/skills/react-best-practices/rules/client-event-listeners.md
new file mode 100644
index 000000000..a40d82ae0
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/client-event-listeners.md
@@ -0,0 +1,78 @@
+---
+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", () => {
+    /* ... */
+  });
+  // ...
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/client-localstorage-schema.md b/.claude/skills/react-best-practices/rules/client-localstorage-schema.md
new file mode 100644
index 000000000..7c4d8c957
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/client-localstorage-schema.md
@@ -0,0 +1,77 @@
+---
+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.
diff --git a/.claude/skills/react-best-practices/rules/client-passive-event-listeners.md b/.claude/skills/react-best-practices/rules/client-passive-event-listeners.md
new file mode 100644
index 000000000..63da92631
--- /dev/null
+++ b/.claude/skills/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()`.
diff --git a/.claude/skills/react-best-practices/rules/client-swr-dedup.md b/.claude/skills/react-best-practices/rules/client-swr-dedup.md
new file mode 100644
index 000000000..13e04c9b6
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/client-swr-dedup.md
@@ -0,0 +1,59 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+Deduplicate client-side fetches across component instances. SWR is shown
+below, but any hook with built-in deduplication works (React Query,
+RTK Query, Apollo's `useQuery`, etc.) — pick whatever the project already
+uses rather than adding a new library.
+
+**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)
diff --git a/.claude/skills/react-best-practices/rules/js-batch-dom-css.md b/.claude/skills/react-best-practices/rules/js-batch-dom-css.md
new file mode 100644
index 000000000..5a7fc2b0d
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/js-batch-dom-css.md
@@ -0,0 +1,110 @@
+---
+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.
diff --git a/.claude/skills/react-best-practices/rules/js-cache-function-results.md b/.claude/skills/react-best-practices/rules/js-cache-function-results.md
new file mode 100644
index 000000000..91a6985be
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/js-cache-property-access.md b/.claude/skills/react-best-practices/rules/js-cache-property-access.md
new file mode 100644
index 000000000..291f109b0
--- /dev/null
+++ b/.claude/skills/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);
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/js-cache-storage.md b/.claude/skills/react-best-practices/rules/js-cache-storage.md
new file mode 100644
index 000000000..363becba1
--- /dev/null
+++ b/.claude/skills/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();
+  }
+});
+```
diff --git a/.claude/skills/react-best-practices/rules/js-combine-iterations.md b/.claude/skills/react-best-practices/rules/js-combine-iterations.md
new file mode 100644
index 000000000..f1e2518b7
--- /dev/null
+++ b/.claude/skills/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);
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/js-early-exit.md b/.claude/skills/react-best-practices/rules/js-early-exit.md
new file mode 100644
index 000000000..992181ac1
--- /dev/null
+++ b/.claude/skills/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 };
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/js-flatmap-filter.md b/.claude/skills/react-best-practices/rules/js-flatmap-filter.md
new file mode 100644
index 000000000..64533c4c7
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/js-flatmap-filter.md
@@ -0,0 +1,55 @@
+---
+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
diff --git a/.claude/skills/react-best-practices/rules/js-hoist-regexp.md b/.claude/skills/react-best-practices/rules/js-hoist-regexp.md
new file mode 100644
index 000000000..2d2256d3d
--- /dev/null
+++ b/.claude/skills/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
+```
diff --git a/.claude/skills/react-best-practices/rules/js-index-maps.md b/.claude/skills/react-best-practices/rules/js-index-maps.md
new file mode 100644
index 000000000..1fbaeda70
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/js-length-check-first.md b/.claude/skills/react-best-practices/rules/js-length-check-first.md
new file mode 100644
index 000000000..8bb79734d
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/js-length-check-first.md
@@ -0,0 +1,50 @@
+---
+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
diff --git a/.claude/skills/react-best-practices/rules/js-min-max-loop.md b/.claude/skills/react-best-practices/rules/js-min-max-loop.md
new file mode 100644
index 000000000..a83a760b7
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/js-request-idle-callback.md b/.claude/skills/react-best-practices/rules/js-request-idle-callback.md
new file mode 100644
index 000000000..0337fd765
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/js-request-idle-callback.md
@@ -0,0 +1,106 @@
+---
+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
diff --git a/.claude/skills/react-best-practices/rules/js-set-map-lookups.md b/.claude/skills/react-best-practices/rules/js-set-map-lookups.md
new file mode 100644
index 000000000..680a4892e
--- /dev/null
+++ b/.claude/skills/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))
+```
diff --git a/.claude/skills/react-best-practices/rules/js-tosorted-immutable.md b/.claude/skills/react-best-practices/rules/js-tosorted-immutable.md
new file mode 100644
index 000000000..e6d5df3af
--- /dev/null
+++ b/.claude/skills/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
diff --git a/.claude/skills/react-best-practices/rules/rendering-activity.md b/.claude/skills/react-best-practices/rules/rendering-activity.md
new file mode 100644
index 000000000..72b13bc7a
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rendering-activity.md
@@ -0,0 +1,75 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM without re-mount cost
+tags: rendering, activity, visibility, state-preservation
+requires: React 19.2+
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that
+frequently toggle visibility. `<Activity>` is stable since React 19.2.
+
+**Why not `{show && <Component />}`?**
+
+- Unmounts the subtree → loses component state
+- Re-runs effects on every mount
+- Rebuilds DOM on every show
+
+**Why not `display: none`?**
+
+- Effects still run (setInterval, fetch, subscriptions waste resources)
+- Doesn't signal React that the subtree is inactive
+
+**Incorrect (loses state and re-runs effects):**
+
+```tsx
+function App() {
+  const [tab, setTab] = useState<"a" | "b">("a");
+  return tab === "a" ? <ExpensiveChartA /> : <ExpensiveChartB />;
+  // Switching tabs unmounts — scroll position, form state, subscriptions all reset
+}
+```
+
+**Correct (preserves state, pauses effects when hidden):**
+
+```tsx
+import { Activity } from "react";
+
+function App() {
+  const [tab, setTab] = useState<"a" | "b">("a");
+  return (
+    <>
+      <Activity mode={tab === "a" ? "visible" : "hidden"}>
+        <ExpensiveChartA />
+      </Activity>
+      <Activity mode={tab === "b" ? "visible" : "hidden"}>
+        <ExpensiveChartB />
+      </Activity>
+    </>
+  );
+}
+```
+
+**Behavior of `hidden` mode:**
+
+- Children render to DOM but are not displayed
+- Effects cleanup when mode switches to `'hidden'`
+- Effects re-run when mode switches back to `'visible'`
+- State (`useState`, refs, uncontrolled inputs) is preserved across toggles
+
+**When to use:**
+
+- Tab panels where users return to the same tab
+- Modal/drawer content that's expensive to mount
+- Off-screen navigation views in mobile apps
+- Any subtree where you want to pay mount cost once
+
+**When NOT to use:**
+
+- Single-use content (e.g. one-time tooltips)
+- Very large subtrees where accumulated DOM becomes a memory problem
+- Lists where entries come and go permanently
+
+Reference: [React docs: `<Activity>`](https://react.dev/reference/react/Activity)
diff --git a/.claude/skills/react-best-practices/rules/rendering-animate-svg-wrapper.md b/.claude/skills/react-best-practices/rules/rendering-animate-svg-wrapper.md
new file mode 100644
index 000000000..370730271
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rendering-animate-svg-wrapper.md
@@ -0,0 +1,38 @@
+---
+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.
diff --git a/.claude/skills/react-best-practices/rules/rendering-conditional-render.md b/.claude/skills/react-best-practices/rules/rendering-conditional-render.md
new file mode 100644
index 000000000..bbafa1427
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rendering-conditional-render.md
@@ -0,0 +1,32 @@
+---
+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>
+```
diff --git a/.claude/skills/react-best-practices/rules/rendering-content-visibility.md b/.claude/skills/react-best-practices/rules/rendering-content-visibility.md
new file mode 100644
index 000000000..1aebfab58
--- /dev/null
+++ b/.claude/skills/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="h-screen overflow-y-auto">
+      {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).
diff --git a/.claude/skills/react-best-practices/rules/rendering-hoist-jsx.md b/.claude/skills/react-best-practices/rules/rendering-hoist-jsx.md
new file mode 100644
index 000000000..fea1751ae
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rendering-hoist-jsx.md
@@ -0,0 +1,36 @@
+---
+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="h-20 animate-pulse bg-gray-200" />;
+}
+
+function Container() {
+  return <div>{loading && <LoadingSkeleton />}</div>;
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = <div className="h-20 animate-pulse 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.
diff --git a/.claude/skills/react-best-practices/rules/rendering-hydration-no-flicker.md b/.claude/skills/react-best-practices/rules/rendering-hydration-no-flicker.md
new file mode 100644
index 000000000..971c5cc99
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rendering-hydration-no-flicker.md
@@ -0,0 +1,72 @@
+---
+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.
diff --git a/.claude/skills/react-best-practices/rules/rendering-hydration-suppress-warning.md b/.claude/skills/react-best-practices/rules/rendering-hydration-suppress-warning.md
new file mode 100644
index 000000000..86c1a33ea
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rendering-hydration-suppress-warning.md
@@ -0,0 +1,26 @@
+---
+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>;
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/rendering-resource-hints.md b/.claude/skills/react-best-practices/rules/rendering-resource-hints.md
new file mode 100644
index 000000000..b020f2cce
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rendering-resource-hints.md
@@ -0,0 +1,89 @@
+---
+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)
diff --git a/.claude/skills/react-best-practices/rules/rendering-script-defer-async.md b/.claude/skills/react-best-practices/rules/rendering-script-defer-async.md
new file mode 100644
index 000000000..5111f35a9
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rendering-script-defer-async.md
@@ -0,0 +1,71 @@
+---
+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)
diff --git a/.claude/skills/react-best-practices/rules/rendering-svg-precision.md b/.claude/skills/react-best-practices/rules/rendering-svg-precision.md
new file mode 100644
index 000000000..6d7712860
--- /dev/null
+++ b/.claude/skills/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
+```
diff --git a/.claude/skills/react-best-practices/rules/rendering-usetransition-loading.md b/.claude/skills/react-best-practices/rules/rendering-usetransition-loading.md
new file mode 100644
index 000000000..bf9f1e851
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/rerender-defer-reads.md b/.claude/skills/react-best-practices/rules/rerender-defer-reads.md
new file mode 100644
index 000000000..bd4919402
--- /dev/null
+++ b/.claude/skills/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>;
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/rerender-dependencies.md b/.claude/skills/react-best-practices/rules/rerender-dependencies.md
new file mode 100644
index 000000000..bd7795edf
--- /dev/null
+++ b/.claude/skills/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]);
+```
diff --git a/.claude/skills/react-best-practices/rules/rerender-derived-state-no-effect.md b/.claude/skills/react-best-practices/rules/rerender-derived-state-no-effect.md
new file mode 100644
index 000000000..b1514c987
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/rerender-derived-state.md b/.claude/skills/react-best-practices/rules/rerender-derived-state.md
new file mode 100644
index 000000000..08ab84a80
--- /dev/null
+++ b/.claude/skills/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"} />;
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/rerender-functional-setstate.md b/.claude/skills/react-best-practices/rules/rerender-functional-setstate.md
new file mode 100644
index 000000000..fe55b02cf
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rerender-functional-setstate.md
@@ -0,0 +1,77 @@
+---
+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.
diff --git a/.claude/skills/react-best-practices/rules/rerender-lazy-state-init.md b/.claude/skills/react-best-practices/rules/rerender-lazy-state-init.md
new file mode 100644
index 000000000..4ead79f11
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/rerender-memo-with-default-value.md b/.claude/skills/react-best-practices/rules/rerender-memo-with-default-value.md
new file mode 100644
index 000000000..c250ebaa7
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rerender-memo-with-default-value.md
@@ -0,0 +1,36 @@
+---
+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 />
+```
diff --git a/.claude/skills/react-best-practices/rules/rerender-memo.md b/.claude/skills/react-best-practices/rules/rerender-memo.md
new file mode 100644
index 000000000..0de3aa3b9
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/rerender-move-effect-to-event.md b/.claude/skills/react-best-practices/rules/rerender-move-effect-to-event.md
new file mode 100644
index 000000000..08c5aa966
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/rerender-no-inline-components.md b/.claude/skills/react-best-practices/rules/rerender-no-inline-components.md
new file mode 100644
index 000000000..682a7a814
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/rerender-no-inline-components.md
@@ -0,0 +1,83 @@
+---
+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
diff --git a/.claude/skills/react-best-practices/rules/rerender-simple-expression-in-memo.md b/.claude/skills/react-best-practices/rules/rerender-simple-expression-in-memo.md
new file mode 100644
index 000000000..9c49b6fe7
--- /dev/null
+++ b/.claude/skills/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
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/rerender-split-combined-hooks.md b/.claude/skills/react-best-practices/rules/rerender-split-combined-hooks.md
new file mode 100644
index 000000000..bc19644dc
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/rerender-transitions.md b/.claude/skills/react-best-practices/rules/rerender-transitions.md
new file mode 100644
index 000000000..1d0bb4321
--- /dev/null
+++ b/.claude/skills/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);
+  }, []);
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/rerender-use-deferred-value.md b/.claude/skills/react-best-practices/rules/rerender-use-deferred-value.md
new file mode 100644
index 000000000..bac40fe12
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/rerender-use-ref-transient-values.md b/.claude/skills/react-best-practices/rules/rerender-use-ref-transient-values.md
new file mode 100644
index 000000000..ee771fac0
--- /dev/null
+++ b/.claude/skills/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)",
+      }}
+    />
+  );
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/server-after-nonblocking.md b/.claude/skills/react-best-practices/rules/server-after-nonblocking.md
new file mode 100644
index 000000000..7415fe181
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/server-after-nonblocking.md
@@ -0,0 +1,74 @@
+---
+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)
diff --git a/.claude/skills/react-best-practices/rules/server-auth-actions.md b/.claude/skills/react-best-practices/rules/server-auth-actions.md
new file mode 100644
index 000000000..44ecf30f6
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/server-cache-lru.md b/.claude/skills/react-best-practices/rules/server-cache-lru.md
new file mode 100644
index 000000000..884630824
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/server-cache-react.md b/.claude/skills/react-best-practices/rules/server-cache-react.md
new file mode 100644
index 000000000..0643ef7c7
--- /dev/null
+++ b/.claude/skills/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)
diff --git a/.claude/skills/react-best-practices/rules/server-dedup-props.md b/.claude/skills/react-best-practices/rules/server-dedup-props.md
new file mode 100644
index 000000000..677086968
--- /dev/null
+++ b/.claude/skills/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.
diff --git a/.claude/skills/react-best-practices/rules/server-hoist-static-io.md b/.claude/skills/react-best-practices/rules/server-hoist-static-io.md
new file mode 100644
index 000000000..892eab35c
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/server-hoist-static-io.md
@@ -0,0 +1,139 @@
+---
+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 }] }
+  )
+}
+```
+
+**Alternative: synchronous file reads with Node.js fs**
+
+```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 }] }
+  )
+}
+```
+
+**General Node.js example: loading config or templates**
+
+```typescript
+// Incorrect: reads config on every call
+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: loads once at module level
+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.
diff --git a/.claude/skills/react-best-practices/rules/server-no-shared-module-state.md b/.claude/skills/react-best-practices/rules/server-no-shared-module-state.md
new file mode 100644
index 000000000..3c20ef98a
--- /dev/null
+++ b/.claude/skills/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).
diff --git a/.claude/skills/react-best-practices/rules/server-parallel-fetching.md b/.claude/skills/react-best-practices/rules/server-parallel-fetching.md
new file mode 100644
index 000000000..8d78b54b2
--- /dev/null
+++ b/.claude/skills/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>
+  );
+}
+```
diff --git a/.claude/skills/react-best-practices/rules/server-parallel-nested-fetching.md b/.claude/skills/react-best-practices/rules/server-parallel-nested-fetching.md
new file mode 100644
index 000000000..2e2a0fd48
--- /dev/null
+++ b/.claude/skills/react-best-practices/rules/server-parallel-nested-fetching.md
@@ -0,0 +1,32 @@
+---
+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.
diff --git a/.claude/skills/react-best-practices/rules/server-serialization.md b/.claude/skills/react-best-practices/rules/server-serialization.md
new file mode 100644
index 000000000..3fe071545
--- /dev/null
+++ b/.claude/skills/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>;
+}
+```
diff --git a/.claude/skills/web-design-guidelines/SKILL.md b/.claude/skills/web-design-guidelines/SKILL.md
new file mode 100644
index 000000000..80e1ad6ad
--- /dev/null
+++ b/.claude/skills/web-design-guidelines/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+argument-hint: "[file or pattern]"
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.
diff --git a/apps/admin/app/layout.tsx b/apps/admin/app/layout.tsx
index 27a5a43df..724900b7a 100644
--- a/apps/admin/app/layout.tsx
+++ b/apps/admin/app/layout.tsx
@@ -1,5 +1,5 @@
 import type { Metadata } from "next";
-import type { ReactNode } from "react";
+import { Suspense, type ReactNode } from "react";
 import { Inter, JetBrains_Mono } from "next/font/google";
 import { AppToaster } from "@/components/app-toaster";
 import { AppFrame } from "@/components/app-frame";
@@ -9,8 +9,11 @@ import { DashboardRoleProvider } from "@/components/role-gate";
 import { SkipNav } from "@/components/skip-nav";
 import { ThemeProvider } from "@/components/theme-provider";
 import { TRPCProvider } from "@/components/trpc-provider";
+import { SessionGuard } from "@/components/session-guard";
 import { DialogProvider } from "@/components/ui/use-dialog";
 import { getDashboardRole } from "@/lib/auth-context";
+import { computeAuthFingerprint } from "@/lib/request-auth";
+import { getServerAuth } from "@/lib/server-auth";
 import { cn } from "@/lib/utils";
 import "./globals.css";
 
@@ -25,6 +28,12 @@ const mono = JetBrains_Mono({
   display: "swap",
 });
 
+// Force dynamic rendering for the whole app. Every route is already dynamic
+// because this root layout reads request-time auth (cookies()/headers() via
+// getDashboardRole below), but we keep this explicit as defense-in-depth: it
+// guarantees no route is ever statically prerendered with a per-user shell
+// (e.g. body[data-dashboard-role]) if that auth read is later moved, removed, or
+// wrapped in Suspense. Do not remove without auditing every route's dynamism.
 export const dynamic = "force-dynamic";
 
 export const metadata: Metadata = {
@@ -59,6 +68,12 @@ export default async function RootLayout({
   children: ReactNode;
 }>): Promise<ReactNode> {
   const dashboardRole = await getDashboardRole();
+  // Fingerprint of the viewer's auth (org roles + group/team memberships) so
+  // <SessionGuard> can detect access changes and bust the client Router Cache.
+  // getServerAuth() is React.cache()-deduped with the call inside
+  // getDashboardRole(), so this does not add a round-trip.
+  const auth = await getServerAuth();
+  const authFingerprint = auth ? computeAuthFingerprint(auth) : null;
 
   return (
     <html
@@ -70,6 +85,12 @@ export default async function RootLayout({
         <SkipNav />
         <ThemeProvider>
           <TRPCProvider>
+            <Suspense fallback={null}>
+              <SessionGuard
+                authenticated={dashboardRole !== "unauthenticated"}
+                serverAuthFingerprint={authFingerprint}
+              />
+            </Suspense>
             <DialogProvider>
               <DashboardRoleProvider role={dashboardRole}>
                 <ErrorBoundary>
diff --git a/apps/admin/app/my-connections/table-experience.tsx b/apps/admin/app/my-connections/table-experience.tsx
index 73ecd0342..5e62ac468 100644
--- a/apps/admin/app/my-connections/table-experience.tsx
+++ b/apps/admin/app/my-connections/table-experience.tsx
@@ -3,10 +3,12 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { useRouter } from "next/navigation";
 import { Search, X, CheckCircle2, AlertTriangle } from "lucide-react";
 import { toast } from "sonner";
+import { keepPreviousData } from "@tanstack/react-query";
 import { VirtualizedPicker } from "@/components/base/virtualized-picker";
 import type { VirtualizedPickerOption } from "@/components/base/virtualized-picker.helpers";
 import { ManagementTable } from "@/components/base/management-table";
 import { ToolkitLogo } from "@/components/toolkit-logo";
+import { ConnectionsPageSkeleton } from "@/components/loading-skeleton";
 import { trpc } from "@/components/trpc-provider";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -114,6 +116,11 @@ export function MyConnectionsTableExperience({
     },
     {
       getNextPageParam: (lastPage) => lastPage.nextCursor,
+      // Keep the previous team's results mounted while switching teams: the
+      // team switcher, counts and header stay interactive instead of being
+      // replaced by a full-page skeleton. `isLoading` then only fires on the
+      // very first load (no data yet), which is where the full skeleton shows.
+      placeholderData: keepPreviousData,
       retry: 1,
       staleTime: 2 * 60_000,
       refetchOnWindowFocus: false,
@@ -212,6 +219,10 @@ export function MyConnectionsTableExperience({
     [confirmDialog, disconnectMutation],
   );
 
+  if (toolkitsQuery.isLoading) {
+    return <ConnectionsPageSkeleton />;
+  }
+
   return (
     <div className="mx-auto flex w-full max-w-7xl flex-col gap-5 px-4 py-7 sm:py-9">
       <header className="flex flex-col gap-3 px-1 sm:px-0">
@@ -316,38 +327,29 @@ export function MyConnectionsTableExperience({
         >
           <span translate="no">{selectedTeamName}</span> connections
         </h2>
-        {toolkitsQuery.isLoading ? (
-          <div className="flex items-center gap-3">
-            <div className="bg-muted h-3.5 w-32 animate-pulse rounded" />
-            <div className="bg-muted h-3.5 w-36 animate-pulse rounded" />
-          </div>
-        ) : (
-          <div
-            className="text-muted-foreground flex flex-wrap items-center gap-x-4 gap-y-1 text-sm tabular-nums"
-            aria-label={`${String(connectedCount)} connected, ${String(readyCount)} ready to connect`}
-          >
-            <span className="inline-flex items-center gap-1.5">
-              <span
-                aria-hidden="true"
-                className="bg-success inline-block size-1.5 rounded-full"
-              />
-              <span className="text-foreground font-semibold">
-                {connectedCount}
-              </span>
-              connected
-            </span>
-            <span className="inline-flex items-center gap-1.5">
-              <span
-                aria-hidden="true"
-                className="bg-primary inline-block size-1.5 rounded-full"
-              />
-              <span className="text-foreground font-semibold">
-                {readyCount}
-              </span>
-              ready to connect
+        <div
+          className="text-muted-foreground flex flex-wrap items-center gap-x-4 gap-y-1 text-sm tabular-nums"
+          aria-label={`${String(connectedCount)} connected, ${String(readyCount)} ready to connect`}
+        >
+          <span className="inline-flex items-center gap-1.5">
+            <span
+              aria-hidden="true"
+              className="bg-success inline-block size-1.5 rounded-full"
+            />
+            <span className="text-foreground font-semibold">
+              {connectedCount}
             </span>
-          </div>
-        )}
+            connected
+          </span>
+          <span className="inline-flex items-center gap-1.5">
+            <span
+              aria-hidden="true"
+              className="bg-primary inline-block size-1.5 rounded-full"
+            />
+            <span className="text-foreground font-semibold">{readyCount}</span>
+            ready to connect
+          </span>
+        </div>
       </section>
 
       {showBanner && callbackResult ? (
@@ -387,97 +389,70 @@ export function MyConnectionsTableExperience({
         </div>
       ) : null}
 
-      {toolkitsQuery.isLoading ? null : (
-        <section className="border-border bg-card rounded-2xl border px-4 py-4 shadow-sm sm:px-5">
-          <div className="flex flex-col gap-3 lg:flex-row lg:items-center lg:justify-between">
-            <div className="flex min-w-0 flex-1 flex-col gap-3 sm:flex-row sm:items-center">
-              <div className="relative min-w-[240px] flex-1">
-                <Search className="text-muted-foreground pointer-events-none absolute top-1/2 left-3 size-4 -translate-y-1/2" />
-                <Input
-                  value={search}
-                  onChange={(event) => {
-                    setSearch(event.target.value);
-                  }}
-                  aria-label="Search toolkits"
-                  placeholder="Search toolkits"
-                  className="border-border bg-background h-10 rounded-xl pl-9"
-                />
-              </div>
-              <div className="bg-muted inline-flex items-center gap-1 rounded-xl p-1">
-                <Button
-                  type="button"
-                  size="sm"
-                  variant={view === "all" ? "default" : "ghost"}
-                  aria-pressed={view === "all"}
-                  onClick={() => {
-                    triggerHaptic("light");
-                    setView(parseToolkitView("all"));
-                  }}
-                  className="h-8 rounded-lg px-3 text-xs"
-                >
-                  All
-                </Button>
-                <Button
-                  type="button"
-                  size="sm"
-                  variant={view === "connected" ? "default" : "ghost"}
-                  aria-pressed={view === "connected"}
-                  onClick={() => {
-                    triggerHaptic("light");
-                    setView(parseToolkitView("connected"));
-                  }}
-                  className="h-8 rounded-lg px-3 text-xs"
-                >
-                  Connected
-                </Button>
-                <Button
-                  type="button"
-                  size="sm"
-                  variant={view === "ready" ? "default" : "ghost"}
-                  aria-pressed={view === "ready"}
-                  onClick={() => {
-                    triggerHaptic("light");
-                    setView(parseToolkitView("ready"));
-                  }}
-                  className="h-8 rounded-lg px-3 text-xs"
-                >
-                  Ready
-                </Button>
-              </div>
+      <section className="border-border bg-card rounded-2xl border px-4 py-4 shadow-sm sm:px-5">
+        <div className="flex flex-col gap-3 lg:flex-row lg:items-center lg:justify-between">
+          <div className="flex min-w-0 flex-1 flex-col gap-3 sm:flex-row sm:items-center">
+            <div className="relative min-w-[240px] flex-1">
+              <Search className="text-muted-foreground pointer-events-none absolute top-1/2 left-3 size-4 -translate-y-1/2" />
+              <Input
+                value={search}
+                onChange={(event) => {
+                  setSearch(event.target.value);
+                }}
+                aria-label="Search toolkits"
+                placeholder="Search toolkits"
+                className="border-border bg-background h-10 rounded-xl pl-9"
+              />
             </div>
-            <p className="text-muted-foreground text-xs tabular-nums sm:text-sm">
-              Showing {String(total)} toolkits
-            </p>
-          </div>
-        </section>
-      )}
-
-      {toolkitsQuery.isLoading ? (
-        <section
-          aria-busy="true"
-          aria-live="polite"
-          className="border-border bg-card flex flex-col gap-4 rounded-2xl border px-5 py-6 shadow-sm"
-        >
-          <span className="sr-only">Loading toolkits</span>
-          {Array.from({ length: 5 }, (_, index) => (
-            <div
-              key={index}
-              className="flex items-center justify-between gap-4"
-            >
-              <div className="flex items-center gap-3">
-                <div className="bg-muted size-8 animate-pulse rounded-lg" />
-                <div className="flex flex-col gap-1.5">
-                  <div className="bg-muted h-3.5 w-28 animate-pulse rounded" />
-                  <div className="bg-muted h-2.5 w-20 animate-pulse rounded" />
-                </div>
-              </div>
-              <div className="bg-muted h-6 w-24 animate-pulse rounded-full" />
+            <div className="bg-muted inline-flex items-center gap-1 rounded-xl p-1">
+              <Button
+                type="button"
+                size="sm"
+                variant={view === "all" ? "default" : "ghost"}
+                aria-pressed={view === "all"}
+                onClick={() => {
+                  triggerHaptic("light");
+                  setView(parseToolkitView("all"));
+                }}
+                className="h-8 rounded-lg px-3 text-xs"
+              >
+                All
+              </Button>
+              <Button
+                type="button"
+                size="sm"
+                variant={view === "connected" ? "default" : "ghost"}
+                aria-pressed={view === "connected"}
+                onClick={() => {
+                  triggerHaptic("light");
+                  setView(parseToolkitView("connected"));
+                }}
+                className="h-8 rounded-lg px-3 text-xs"
+              >
+                Connected
+              </Button>
+              <Button
+                type="button"
+                size="sm"
+                variant={view === "ready" ? "default" : "ghost"}
+                aria-pressed={view === "ready"}
+                onClick={() => {
+                  triggerHaptic("light");
+                  setView(parseToolkitView("ready"));
+                }}
+                className="h-8 rounded-lg px-3 text-xs"
+              >
+                Ready
+              </Button>
             </div>
-          ))}
-        </section>
-      ) : null}
+          </div>
+          <p className="text-muted-foreground text-xs tabular-nums sm:text-sm">
+            Showing {String(total)} toolkits
+          </p>
+        </div>
+      </section>
 
-      {!toolkitsQuery.isLoading && catalogUnavailable ? (
+      {catalogUnavailable ? (
         <section className="border-warning/30 bg-warning/5 rounded-xl border px-4 py-3">
           <div className="flex flex-wrap items-center justify-between gap-2">
             <div className="flex items-start gap-2">
@@ -502,7 +477,7 @@ export function MyConnectionsTableExperience({
         </section>
       ) : null}
 
-      {!toolkitsQuery.isLoading && hasToolkitQueryError ? (
+      {hasToolkitQueryError ? (
         <section className="border-destructive/25 bg-destructive/5 rounded-xl border px-4 py-3">
           <div className="flex flex-wrap items-center justify-between gap-2">
             <p className="text-sm">
@@ -523,165 +498,174 @@ export function MyConnectionsTableExperience({
         </section>
       ) : null}
 
-      {toolkitsQuery.isLoading ? null : (
-        <ManagementTable
-          sectionClassName="rounded-2xl"
-          headerClassName="bg-muted/55"
-          bodyRowClassName="border-border/70 hover:bg-muted/20"
-          cellClassName="py-3.5 lg:py-3"
-          footerClassName="bg-muted/20"
-          columns={[
-            { key: "toolkit", label: "Toolkit" },
-            {
-              key: "status",
-              label: "Status",
-              className: "w-[148px] text-foreground/85 sm:w-[160px]",
-            },
-            {
-              key: "source",
-              label: "Source",
-              className: "w-[130px] text-foreground/85 lg:w-[150px]",
-            },
-            {
-              key: "action",
-              label: "Action",
-              className:
-                "w-[120px] pr-4 text-right text-foreground/85 sm:w-[132px] sm:pr-6",
-            },
-          ]}
-          rows={pagedToolkits.map((toolkit) => ({
-            key: toolkit.slug,
-            cells: [
-              <div key={`${toolkit.slug}-toolkit`} className="min-w-0">
-                <div className="flex items-center gap-2">
-                  <ToolkitLogo
-                    logoUrl={toolkit.logo}
-                    name={toolkit.name}
-                    className="size-5"
-                  />
-                  <span className="text-[14px] font-medium lg:text-[15px]">
-                    {toolkit.name}
-                  </span>
-                </div>
-                <p className="text-muted-foreground mt-1 font-mono text-[10px] opacity-75 lg:text-[11px]">
-                  {toolkit.slug}
-                </p>
-              </div>,
-              <Badge
-                key={`${toolkit.slug}-status`}
-                className={cn(
-                  TABLE_BADGE_CLASS,
-                  toolkit.isConnected
-                    ? "border-success/25 bg-success/10 text-success"
-                    : toolkit.isNoAuth
-                      ? "border-border/90 bg-muted/50 text-muted-foreground"
-                      : "border-primary/25 bg-primary/10 text-primary",
-                )}
-              >
-                {toolkit.isConnected
-                  ? "Connected"
+      <ManagementTable
+        sectionClassName={cn(
+          "rounded-2xl transition-opacity",
+          // While switching teams keepPreviousData shows the prior team's rows;
+          // dim them so it reads as "updating" rather than stale content.
+          toolkitsQuery.isPlaceholderData && "opacity-60",
+        )}
+        headerClassName="bg-muted/55"
+        bodyRowClassName="border-border/70 hover:bg-muted/20"
+        cellClassName="py-3.5 lg:py-3"
+        footerClassName="bg-muted/20"
+        columns={[
+          { key: "toolkit", label: "Toolkit" },
+          {
+            key: "status",
+            label: "Status",
+            className: "w-[148px] text-foreground/85 sm:w-[160px]",
+          },
+          {
+            key: "source",
+            label: "Source",
+            className: "w-[130px] text-foreground/85 lg:w-[150px]",
+          },
+          {
+            key: "action",
+            label: "Action",
+            className:
+              "w-[120px] pr-4 text-right text-foreground/85 sm:w-[132px] sm:pr-6",
+          },
+        ]}
+        rows={pagedToolkits.map((toolkit) => ({
+          key: toolkit.slug,
+          cells: [
+            <div key={`${toolkit.slug}-toolkit`} className="min-w-0">
+              <div className="flex items-center gap-2">
+                <ToolkitLogo
+                  logoUrl={toolkit.logo}
+                  name={toolkit.name}
+                  className="size-5"
+                />
+                <span className="text-[14px] font-medium lg:text-[15px]">
+                  {toolkit.name}
+                </span>
+              </div>
+              <p className="text-muted-foreground mt-1 font-mono text-[10px] opacity-75 lg:text-[11px]">
+                {toolkit.slug}
+              </p>
+            </div>,
+            <Badge
+              key={`${toolkit.slug}-status`}
+              className={cn(
+                TABLE_BADGE_CLASS,
+                toolkit.isConnected
+                  ? "border-success/25 bg-success/10 text-success"
                   : toolkit.isNoAuth
-                    ? "No auth required"
-                    : "Ready to connect"}
-              </Badge>,
-              <span
-                key={`${toolkit.slug}-source`}
-                className="text-muted-foreground text-[11px] leading-5"
-              >
-                {toolkit.authConfigId ? "Managed auth" : "Provider OAuth"}
-              </span>,
-              <div
-                key={`${toolkit.slug}-action`}
-                className="flex justify-end text-right"
-              >
-                {toolkit.isConnected && toolkit.connectionId ? (
-                  <Button
-                    size="sm"
-                    variant="outline"
-                    className={cn(TABLE_ACTION_BUTTON_CLASS, "min-w-[104px]")}
-                    aria-label={`Disconnect ${toolkit.name}`}
-                    isLoading={
-                      disconnectMutation.isPending &&
-                      disconnectMutation.variables.connectionId ===
-                        toolkit.connectionId
-                    }
-                    onClick={() => {
-                      void handleDisconnect(toolkit);
-                    }}
-                  >
-                    Disconnect
-                  </Button>
-                ) : toolkit.isConnected ? (
-                  <span className="text-muted-foreground text-[11px]">
-                    No action
-                  </span>
-                ) : toolkit.isNoAuth ? (
-                  <span className="text-muted-foreground text-[11px]">
-                    No action
-                  </span>
-                ) : (
-                  <Button
-                    size="sm"
-                    className={cn(TABLE_ACTION_BUTTON_CLASS, "min-w-[104px]")}
-                    aria-label={`Connect ${toolkit.name}`}
-                    isLoading={
-                      initiateMutation.isPending &&
-                      initiateMutation.variables.toolkit === toolkit.slug &&
-                      initiateMutation.variables.teamSlug === selectedTeamSlug
-                    }
-                    onClick={() => {
-                      initiateMutation.mutate(
-                        { teamSlug: selectedTeamSlug, toolkit: toolkit.slug },
-                        {
-                          onSuccess: (result) => {
-                            triggerHaptic("success");
-                            toast.success(`Redirecting to ${toolkit.name}...`);
-                            if (
-                              !navigateToExternalRedirect(result.redirectUrl)
-                            ) {
-                              triggerHaptic("error");
-                              toast.error(
-                                "Received an invalid connection redirect URL",
-                              );
-                            }
-                          },
+                    ? "border-border/90 bg-muted/50 text-muted-foreground"
+                    : "border-primary/25 bg-primary/10 text-primary",
+              )}
+            >
+              {toolkit.isConnected
+                ? "Connected"
+                : toolkit.isNoAuth
+                  ? "No auth required"
+                  : "Ready to connect"}
+            </Badge>,
+            <span
+              key={`${toolkit.slug}-source`}
+              className="text-muted-foreground text-[11px] leading-5"
+            >
+              {toolkit.authConfigId ? "Managed auth" : "Provider OAuth"}
+            </span>,
+            <div
+              key={`${toolkit.slug}-action`}
+              className="flex justify-end text-right"
+            >
+              {toolkit.isConnected && toolkit.connectionId ? (
+                <Button
+                  size="sm"
+                  variant="outline"
+                  className={cn(TABLE_ACTION_BUTTON_CLASS, "min-w-[104px]")}
+                  aria-label={`Disconnect ${toolkit.name}`}
+                  // Disable while switching teams: keepPreviousData still shows
+                  // the previous team's rows, so acting on one would disconnect
+                  // a connection by its stale connectionId.
+                  disabled={toolkitsQuery.isPlaceholderData}
+                  isLoading={
+                    disconnectMutation.isPending &&
+                    disconnectMutation.variables.connectionId ===
+                      toolkit.connectionId
+                  }
+                  onClick={() => {
+                    void handleDisconnect(toolkit);
+                  }}
+                >
+                  Disconnect
+                </Button>
+              ) : toolkit.isConnected ? (
+                <span className="text-muted-foreground text-[11px]">
+                  No action
+                </span>
+              ) : toolkit.isNoAuth ? (
+                <span className="text-muted-foreground text-[11px]">
+                  No action
+                </span>
+              ) : (
+                <Button
+                  size="sm"
+                  className={cn(TABLE_ACTION_BUTTON_CLASS, "min-w-[104px]")}
+                  aria-label={`Connect ${toolkit.name}`}
+                  // Disable while switching teams: keepPreviousData still shows
+                  // the previous team's rows, so acting on one would connect the
+                  // stale toolkit under the newly-selected team.
+                  disabled={toolkitsQuery.isPlaceholderData}
+                  isLoading={
+                    initiateMutation.isPending &&
+                    initiateMutation.variables.toolkit === toolkit.slug &&
+                    initiateMutation.variables.teamSlug === selectedTeamSlug
+                  }
+                  onClick={() => {
+                    initiateMutation.mutate(
+                      { teamSlug: selectedTeamSlug, toolkit: toolkit.slug },
+                      {
+                        onSuccess: (result) => {
+                          triggerHaptic("success");
+                          toast.success(`Redirecting to ${toolkit.name}...`);
+                          if (!navigateToExternalRedirect(result.redirectUrl)) {
+                            triggerHaptic("error");
+                            toast.error(
+                              "Received an invalid connection redirect URL",
+                            );
+                          }
                         },
-                      );
-                    }}
-                  >
-                    Connect
-                  </Button>
-                )}
-              </div>,
-            ],
-          }))}
-          emptyState={
-            <div className="text-center">
-              <p className="text-sm font-medium">
-                {toolkits.length === 0
-                  ? "No toolkits available for this team yet"
-                  : "No toolkits match this view"}
-              </p>
-            </div>
-          }
-          page={safePage}
-          totalPages={totalPages}
-          onPreviousPage={() => {
-            triggerHaptic("light");
-            setTablePage(Math.max(1, safePage - 1));
-          }}
-          onNextPage={() => {
-            triggerHaptic("light");
-            setTablePage(Math.min(totalPages, safePage + 1));
-          }}
-          summary={formatRangeSummary(
-            safePage,
-            TABLE_PAGE_SIZE,
-            total,
-            "toolkit",
-          )}
-        />
-      )}
+                      },
+                    );
+                  }}
+                >
+                  Connect
+                </Button>
+              )}
+            </div>,
+          ],
+        }))}
+        emptyState={
+          <div className="text-center">
+            <p className="text-sm font-medium">
+              {toolkits.length === 0
+                ? "No toolkits available for this team yet"
+                : "No toolkits match this view"}
+            </p>
+          </div>
+        }
+        page={safePage}
+        totalPages={totalPages}
+        onPreviousPage={() => {
+          triggerHaptic("light");
+          setTablePage(Math.max(1, safePage - 1));
+        }}
+        onNextPage={() => {
+          triggerHaptic("light");
+          setTablePage(Math.min(totalPages, safePage + 1));
+        }}
+        summary={formatRangeSummary(
+          safePage,
+          TABLE_PAGE_SIZE,
+          total,
+          "toolkit",
+        )}
+      />
     </div>
   );
 }
diff --git a/apps/admin/app/settings/auth-config/loading.tsx b/apps/admin/app/settings/auth-config/loading.tsx
new file mode 100644
index 000000000..8333a8e2d
--- /dev/null
+++ b/apps/admin/app/settings/auth-config/loading.tsx
@@ -0,0 +1,6 @@
+import type { ReactElement } from "react";
+import { SettingsPageSkeleton } from "@/components/loading-skeleton";
+
+export default function Loading(): ReactElement {
+  return <SettingsPageSkeleton />;
+}
diff --git a/apps/admin/app/settings/policies/[id]/loading.tsx b/apps/admin/app/settings/policies/[id]/loading.tsx
new file mode 100644
index 000000000..8333a8e2d
--- /dev/null
+++ b/apps/admin/app/settings/policies/[id]/loading.tsx
@@ -0,0 +1,6 @@
+import type { ReactElement } from "react";
+import { SettingsPageSkeleton } from "@/components/loading-skeleton";
+
+export default function Loading(): ReactElement {
+  return <SettingsPageSkeleton />;
+}
diff --git a/apps/admin/app/settings/policies/loading.tsx b/apps/admin/app/settings/policies/loading.tsx
new file mode 100644
index 000000000..8333a8e2d
--- /dev/null
+++ b/apps/admin/app/settings/policies/loading.tsx
@@ -0,0 +1,6 @@
+import type { ReactElement } from "react";
+import { SettingsPageSkeleton } from "@/components/loading-skeleton";
+
+export default function Loading(): ReactElement {
+  return <SettingsPageSkeleton />;
+}
diff --git a/apps/admin/app/settings/policies/new/loading.tsx b/apps/admin/app/settings/policies/new/loading.tsx
new file mode 100644
index 000000000..8333a8e2d
--- /dev/null
+++ b/apps/admin/app/settings/policies/new/loading.tsx
@@ -0,0 +1,6 @@
+import type { ReactElement } from "react";
+import { SettingsPageSkeleton } from "@/components/loading-skeleton";
+
+export default function Loading(): ReactElement {
+  return <SettingsPageSkeleton />;
+}
diff --git a/apps/admin/app/settings/siem/loading.tsx b/apps/admin/app/settings/siem/loading.tsx
new file mode 100644
index 000000000..768b1a0fc
--- /dev/null
+++ b/apps/admin/app/settings/siem/loading.tsx
@@ -0,0 +1,6 @@
+import type { ReactElement } from "react";
+import { SiemSettingsSkeleton } from "./siem-settings-skeleton";
+
+export default function Loading(): ReactElement {
+  return <SiemSettingsSkeleton />;
+}
diff --git a/apps/admin/app/settings/siem/siem-settings-client.tsx b/apps/admin/app/settings/siem/siem-settings-client.tsx
index 96a4d117e..cd75cfc4e 100644
--- a/apps/admin/app/settings/siem/siem-settings-client.tsx
+++ b/apps/admin/app/settings/siem/siem-settings-client.tsx
@@ -29,6 +29,7 @@ import { DatadogFields } from "./datadog-fields";
 import { SumoLogicFields } from "./sumo-logic-fields";
 import { SplunkFields } from "./splunk-fields";
 import { PageHeader } from "./page-header";
+import { SiemSettingsSkeleton } from "./siem-settings-skeleton";
 
 export function SiemSettingsClient(): React.ReactElement {
   const utils = trpc.useUtils();
@@ -204,14 +205,7 @@ export function SiemSettingsClient(): React.ReactElement {
   // ── Loading / Error states ──────────────────────────────────────
 
   if (configQuery.isLoading) {
-    return (
-      <div className="mx-auto flex min-h-screen max-w-3xl flex-col gap-6 px-6 py-10">
-        <PageHeader />
-        <Card className="flex items-center justify-center p-12">
-          <Loader2 className="text-muted-foreground size-6 animate-spin" />
-        </Card>
-      </div>
-    );
+    return <SiemSettingsSkeleton />;
   }
 
   if (configQuery.isError) {
diff --git a/apps/admin/app/settings/siem/siem-settings-skeleton.tsx b/apps/admin/app/settings/siem/siem-settings-skeleton.tsx
new file mode 100644
index 000000000..63988dd79
--- /dev/null
+++ b/apps/admin/app/settings/siem/siem-settings-skeleton.tsx
@@ -0,0 +1,29 @@
+import type { ReactElement } from "react";
+import { Loader2 } from "lucide-react";
+import { Card } from "@/components/ui/card";
+import { PageHeader } from "./page-header";
+
+/**
+ * Shared loading skeleton for the SIEM settings page. Used by both the
+ * route-level `loading.tsx` (shown while the RSC resolves) and the client
+ * component while its config query loads, so the user sees a single,
+ * consistent skeleton instead of two different ones.
+ */
+export function SiemSettingsSkeleton(): ReactElement {
+  return (
+    <div
+      className="mx-auto flex min-h-screen max-w-3xl flex-col gap-6 px-6 py-10"
+      role="status"
+      aria-label="Loading SIEM configuration"
+    >
+      <span className="sr-only">Loading SIEM configuration</span>
+      <PageHeader />
+      <Card className="flex items-center justify-center p-12">
+        <Loader2
+          className="text-muted-foreground size-6 animate-spin"
+          aria-hidden="true"
+        />
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/admin/app/settings/sso/_components.tsx b/apps/admin/app/settings/sso/_components.tsx
index a48611d94..ecd81191c 100644
--- a/apps/admin/app/settings/sso/_components.tsx
+++ b/apps/admin/app/settings/sso/_components.tsx
@@ -26,6 +26,7 @@ import { trpc } from "@/components/trpc-provider";
 import { copyToClipboard } from "@/lib/clipboard";
 import { useUnsavedChangesWarning } from "@/lib/use-unsaved-changes-warning";
 import { cn } from "@/lib/utils";
+import { SsoSettingsSkeleton } from "./sso-settings-skeleton";
 
 const SSO_PROVIDER_LABELS: Record<"okta" | "entra" | "jumpcloud", string> = {
   okta: "Okta",
@@ -314,18 +315,7 @@ export function SsoSettingsClient(): React.ReactElement {
   }, [newCredentials]);
 
   if (ssoQuery.isLoading) {
-    return (
-      <div
-        className="mx-auto max-w-3xl space-y-6 px-6 py-10"
-        role="status"
-        aria-label="Loading SSO and SCIM configuration"
-      >
-        <span className="sr-only">Loading SSO and SCIM configuration</span>
-        <div className="bg-muted h-8 w-48 animate-pulse rounded" />
-        <div className="bg-muted h-64 animate-pulse rounded-xl" />
-        <div className="bg-muted h-64 animate-pulse rounded-xl" />
-      </div>
-    );
+    return <SsoSettingsSkeleton />;
   }
 
   if (ssoQuery.isError || !ssoQuery.data) {
diff --git a/apps/admin/app/settings/sso/loading.tsx b/apps/admin/app/settings/sso/loading.tsx
new file mode 100644
index 000000000..c6263ad7d
--- /dev/null
+++ b/apps/admin/app/settings/sso/loading.tsx
@@ -0,0 +1,6 @@
+import type { ReactElement } from "react";
+import { SsoSettingsSkeleton } from "./sso-settings-skeleton";
+
+export default function Loading(): ReactElement {
+  return <SsoSettingsSkeleton />;
+}
diff --git a/apps/admin/app/settings/sso/sso-settings-skeleton.tsx b/apps/admin/app/settings/sso/sso-settings-skeleton.tsx
new file mode 100644
index 000000000..b6c60b4a5
--- /dev/null
+++ b/apps/admin/app/settings/sso/sso-settings-skeleton.tsx
@@ -0,0 +1,22 @@
+import type { ReactElement } from "react";
+
+/**
+ * Shared loading skeleton for the SSO & SCIM settings page. Used by both the
+ * route-level `loading.tsx` (shown while the RSC resolves) and the client
+ * component while its config query loads, so the user sees a single,
+ * consistent skeleton instead of two different ones.
+ */
+export function SsoSettingsSkeleton(): ReactElement {
+  return (
+    <div
+      className="mx-auto max-w-3xl space-y-6 px-6 py-10"
+      role="status"
+      aria-label="Loading SSO and SCIM configuration"
+    >
+      <span className="sr-only">Loading SSO and SCIM configuration</span>
+      <div className="bg-muted h-8 w-48 animate-pulse rounded" />
+      <div className="bg-muted h-64 animate-pulse rounded-xl" />
+      <div className="bg-muted h-64 animate-pulse rounded-xl" />
+    </div>
+  );
+}
diff --git a/apps/admin/app/teams/[slug]/shared-connections/loading.tsx b/apps/admin/app/teams/[slug]/shared-connections/loading.tsx
new file mode 100644
index 000000000..fc612f244
--- /dev/null
+++ b/apps/admin/app/teams/[slug]/shared-connections/loading.tsx
@@ -0,0 +1,6 @@
+import type { ReactElement } from "react";
+import { TeamWorkspaceSkeleton } from "@/components/loading-skeleton";
+
+export default function Loading(): ReactElement {
+  return <TeamWorkspaceSkeleton />;
+}
diff --git a/apps/admin/components/app-sidebar-nav.tsx b/apps/admin/components/app-sidebar-nav.tsx
index 93e2bdd53..92d21caa0 100644
--- a/apps/admin/components/app-sidebar-nav.tsx
+++ b/apps/admin/components/app-sidebar-nav.tsx
@@ -28,6 +28,11 @@ export type NavItem = {
   // Hidden unless the org carries the SIEM forwarding entitlement (toggled by
   // internal staff). Role checks alone are not enough — the feature is gated.
   requiresSiemEntitlement?: boolean;
+  // Opt this route into a hover/focus-triggered full prefetch from the sidebar
+  // (see app-sidebar-sections.tsx). Use for heavy, data-driven pages whose cold
+  // server render feels slow, where eager (viewport) prefetch for every viewer
+  // would be wasteful.
+  prefetchOnHover?: boolean;
 };
 
 export const NAV_ITEMS: NavItem[] = [
@@ -58,6 +63,7 @@ export const NAV_ITEMS: NavItem[] = [
     label: "Toolkits",
     section: "access",
     allowedRoles: ["org_admin", "org_viewer"],
+    prefetchOnHover: true,
   },
   {
     href: "/settings/policies",
@@ -65,6 +71,7 @@ export const NAV_ITEMS: NavItem[] = [
     label: "Toolkit Policies",
     section: "access",
     allowedRoles: ["org_admin", "org_viewer"],
+    prefetchOnHover: true,
   },
   {
     href: "/settings/connections",
diff --git a/apps/admin/components/app-sidebar-sections.tsx b/apps/admin/components/app-sidebar-sections.tsx
index 510a6c38a..950b83d4b 100644
--- a/apps/admin/components/app-sidebar-sections.tsx
+++ b/apps/admin/components/app-sidebar-sections.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import Link from "next/link";
-import type { ReactElement } from "react";
+import { useState, type ReactElement } from "react";
 import { Badge } from "@/components/ui/badge";
 import {
   NAV_GROUPS,
@@ -10,6 +10,101 @@ import {
 } from "@/components/app-sidebar-nav";
 import { cn } from "@/lib/utils";
 
+function SidebarNavLink({
+  item,
+  pathname,
+  shouldShowExpanded,
+  unreadCount,
+  onNavigate,
+}: {
+  item: NavItem;
+  pathname: string;
+  shouldShowExpanded: boolean;
+  unreadCount: number;
+  onNavigate: () => void;
+}): ReactElement {
+  const active = isActive(pathname, item.href);
+  const Icon = item.icon;
+
+  // Heavy, data-driven routes (Toolkits, Toolkit Policies) opt into a
+  // hover/focus-triggered *full* prefetch. We start with prefetch disabled so
+  // the always-visible sidebar doesn't eagerly fetch them (hitting Composio /
+  // the DB) on every page load; flipping `prefetch` to `true` on intent makes
+  // Next prefetch the full RSC into the Router Cache (staleTimes.dynamic), so
+  // the click lands on a warm entry instead of a cold server render. Non-opted
+  // items keep Next's default ("auto") prefetch via `undefined`.
+  const [prefetchOnIntent, setPrefetchOnIntent] = useState(false);
+  const prefetch = item.prefetchOnHover ? prefetchOnIntent : undefined;
+  const handlePrefetchIntent = item.prefetchOnHover
+    ? () => {
+        setPrefetchOnIntent(true);
+      }
+    : undefined;
+
+  return (
+    <li>
+      <Link
+        href={item.href}
+        prefetch={prefetch}
+        onClick={onNavigate}
+        onMouseEnter={handlePrefetchIntent}
+        onFocus={handlePrefetchIntent}
+        className={cn(
+          "group focus-visible:ring-ring relative flex h-10 items-center gap-2.5 overflow-hidden rounded-md px-3 text-sm transition-colors focus-visible:ring-2 focus-visible:outline-none lg:h-9",
+          active
+            ? "bg-primary/10 text-foreground font-medium"
+            : "text-muted-foreground hover:bg-muted/50 hover:text-foreground",
+          !shouldShowExpanded && "justify-center px-2",
+        )}
+        aria-current={active ? "page" : undefined}
+        aria-label={
+          !shouldShowExpanded
+            ? `${item.label}${
+                item.badge === "notifications" && unreadCount > 0
+                  ? `, ${String(unreadCount)} unread`
+                  : ""
+              }`
+            : undefined
+        }
+      >
+        {active && shouldShowExpanded ? (
+          <span
+            className="bg-primary absolute top-1.5 bottom-1.5 left-0 w-1 rounded-r-full"
+            aria-hidden="true"
+          />
+        ) : null}
+        <Icon className="size-3.5 shrink-0" aria-hidden="true" />
+        {shouldShowExpanded ? (
+          <>
+            <span className="truncate">{item.label}</span>
+            {item.badge === "notifications" && unreadCount > 0 ? (
+              <Badge
+                variant="default"
+                className="ml-auto min-w-5 rounded-full px-1.5 text-[10px] leading-4 tabular-nums"
+                title={
+                  unreadCount > 99
+                    ? `${String(unreadCount)} unread notifications`
+                    : undefined
+                }
+              >
+                {unreadCount > 99 ? "99+" : unreadCount}
+              </Badge>
+            ) : null}
+          </>
+        ) : null}
+        {!shouldShowExpanded ? (
+          <span className="bg-popover text-popover-foreground border-border pointer-events-none absolute left-full z-50 ml-3 rounded-md border px-2.5 py-1.5 text-xs font-medium whitespace-nowrap opacity-0 shadow-sm transition-opacity duration-200 group-hover:pointer-events-auto group-hover:opacity-100">
+            {item.label}
+            {item.badge === "notifications" && unreadCount > 0
+              ? ` (${String(unreadCount)})`
+              : ""}
+          </span>
+        ) : null}
+      </Link>
+    </li>
+  );
+}
+
 export function AppSidebarSections({
   items,
   pathname,
@@ -33,70 +128,16 @@ export function AppSidebarSections({
         </p>
       ) : null}
       <ul className="grid gap-1">
-        {items.map((item) => {
-          const active = isActive(pathname, item.href);
-          const Icon = item.icon;
-
-          return (
-            <li key={item.href}>
-              <Link
-                href={item.href}
-                onClick={onNavigate}
-                className={cn(
-                  "group focus-visible:ring-ring relative flex h-10 items-center gap-2.5 overflow-hidden rounded-md px-3 text-sm transition-colors focus-visible:ring-2 focus-visible:outline-none lg:h-9",
-                  active
-                    ? "bg-primary/10 text-foreground font-medium"
-                    : "text-muted-foreground hover:bg-muted/50 hover:text-foreground",
-                  !shouldShowExpanded && "justify-center px-2",
-                )}
-                aria-current={active ? "page" : undefined}
-                aria-label={
-                  !shouldShowExpanded
-                    ? `${item.label}${
-                        item.badge === "notifications" && unreadCount > 0
-                          ? `, ${String(unreadCount)} unread`
-                          : ""
-                      }`
-                    : undefined
-                }
-              >
-                {active && shouldShowExpanded ? (
-                  <span
-                    className="bg-primary absolute top-1.5 bottom-1.5 left-0 w-1 rounded-r-full"
-                    aria-hidden="true"
-                  />
-                ) : null}
-                <Icon className="size-3.5 shrink-0" aria-hidden="true" />
-                {shouldShowExpanded ? (
-                  <>
-                    <span className="truncate">{item.label}</span>
-                    {item.badge === "notifications" && unreadCount > 0 ? (
-                      <Badge
-                        variant="default"
-                        className="ml-auto min-w-5 rounded-full px-1.5 text-[10px] leading-4 tabular-nums"
-                        title={
-                          unreadCount > 99
-                            ? `${String(unreadCount)} unread notifications`
-                            : undefined
-                        }
-                      >
-                        {unreadCount > 99 ? "99+" : unreadCount}
-                      </Badge>
-                    ) : null}
-                  </>
-                ) : null}
-                {!shouldShowExpanded ? (
-                  <span className="bg-popover text-popover-foreground border-border pointer-events-none absolute left-full z-50 ml-3 rounded-md border px-2.5 py-1.5 text-xs font-medium whitespace-nowrap opacity-0 shadow-sm transition-opacity duration-200 group-hover:pointer-events-auto group-hover:opacity-100">
-                    {item.label}
-                    {item.badge === "notifications" && unreadCount > 0
-                      ? ` (${String(unreadCount)})`
-                      : ""}
-                  </span>
-                ) : null}
-              </Link>
-            </li>
-          );
-        })}
+        {items.map((item) => (
+          <SidebarNavLink
+            key={item.href}
+            item={item}
+            pathname={pathname}
+            shouldShowExpanded={shouldShowExpanded}
+            unreadCount={unreadCount}
+            onNavigate={onNavigate}
+          />
+        ))}
       </ul>
     </>
   );
diff --git a/apps/admin/components/session-guard.tsx b/apps/admin/components/session-guard.tsx
new file mode 100644
index 000000000..68a93c4f2
--- /dev/null
+++ b/apps/admin/components/session-guard.tsx
@@ -0,0 +1,117 @@
+"use client";
+
+import * as React from "react";
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { useQueryClient } from "@tanstack/react-query";
+import { trpc } from "@/components/trpc-provider";
+
+/**
+ * Keeps the client caches safe for auth-gated pages. A Router Cache hit serves a
+ * cached RSC payload without touching the server, and the client React Query
+ * cache (its keys are not user-scoped) can replay data fetched as a previous
+ * user — so on its own a cached page could keep rendering after the session
+ * ended, the user's access changed, or the cookie switched to a different
+ * account.
+ *
+ * This guard revalidates the session on every full navigation (path *or* query
+ * string) and when the tab regains focus, using `me.getSession` — an
+ * `authedProcedure` available to every role — as the heartbeat, which returns a
+ * fingerprint of the viewer's identity *and* access (userId/tenant + org roles +
+ * group/team memberships + per-group roles):
+ *
+ *   - Session gone → the request 401s and the global handler in TRPCProvider
+ *     redirects to sign-in (a full navigation that clears the Router Cache).
+ *   - Identity or access changed (still a valid session, so a 200) → the
+ *     server-resolved fingerprint no longer matches the one this cached shell
+ *     was rendered with, so we clear the React Query cache and `router.refresh()`
+ *     once — dropping any cross-user/stale client data and re-rendering
+ *     server-side. This catches account switches, role downgrades and
+ *     team-membership changes, and matters because cached payloads include
+ *     identity- and role/team-gated *data*, not just chrome (e.g. /profile,
+ *     /my-connections, the org directory on /people, a team's members).
+ *
+ * The page still renders instantly from cache; only this lightweight check runs
+ * in the background. Renders nothing.
+ */
+export function SessionGuard({
+  authenticated,
+  serverAuthFingerprint,
+}: {
+  authenticated: boolean;
+  serverAuthFingerprint: string | null;
+}): null {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const router = useRouter();
+  const utils = trpc.useUtils();
+  const queryClient = useQueryClient();
+
+  const sessionQuery = trpc.me.getSession.useQuery(undefined, {
+    enabled: authenticated,
+    staleTime: 30_000,
+  });
+
+  const revalidateSession = React.useCallback(() => {
+    if (!authenticated) {
+      return;
+    }
+
+    void utils.me.getSession.refetch();
+  }, [authenticated, utils]);
+
+  // Revalidate on every client-side navigation, including query-string-only
+  // changes (e.g. table pagination pushes `?page=…` on the same path).
+  React.useEffect(() => {
+    revalidateSession();
+  }, [pathname, searchParams, revalidateSession]);
+
+  // Revalidate when the user returns to a backgrounded tab.
+  React.useEffect(() => {
+    const onVisibilityChange = (): void => {
+      if (document.visibilityState === "visible") {
+        revalidateSession();
+      }
+    };
+
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [revalidateSession]);
+
+  // When the server-resolved fingerprint diverges from the one this cached shell
+  // was rendered with, drop stale client state and re-render server-side. We
+  // clear the React Query cache first (its keys aren't user-scoped, so
+  // router.refresh alone would let a client query replay the previous user's /
+  // previous-access data), then router.refresh() to bust the Router Cache.
+  // Refresh once per new fingerprint (the ref guards against re-firing until
+  // `serverAuthFingerprint` catches up after the refresh).
+  const refreshedForFingerprintRef = React.useRef<string | null>(null);
+  React.useEffect(() => {
+    const currentFingerprint = sessionQuery.data?.fingerprint;
+
+    if (currentFingerprint === undefined) {
+      return;
+    }
+
+    if (currentFingerprint === serverAuthFingerprint) {
+      refreshedForFingerprintRef.current = null;
+      return;
+    }
+
+    if (refreshedForFingerprintRef.current === currentFingerprint) {
+      return;
+    }
+
+    refreshedForFingerprintRef.current = currentFingerprint;
+    queryClient.clear();
+    router.refresh();
+  }, [
+    sessionQuery.data?.fingerprint,
+    serverAuthFingerprint,
+    queryClient,
+    router,
+  ]);
+
+  return null;
+}
diff --git a/apps/admin/components/trpc-provider.tsx b/apps/admin/components/trpc-provider.tsx
index ad90d13e2..636756063 100644
--- a/apps/admin/components/trpc-provider.tsx
+++ b/apps/admin/components/trpc-provider.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import React from "react";
-import { usePathname } from "next/navigation";
+import { usePathname, useRouter } from "next/navigation";
 import * as Sentry from "@sentry/nextjs";
 import {
   MutationCache,
@@ -52,6 +52,7 @@ export function TRPCProvider({
   children: ReactNode;
 }>): ReactNode {
   const pathname = usePathname();
+  const router = useRouter();
   const [queryClient] = useState(
     () =>
       new QueryClient({
@@ -59,7 +60,7 @@ export function TRPCProvider({
           queries: {
             refetchOnWindowFocus: false,
             retry: 1,
-            staleTime: 30_000,
+            staleTime: 60_000,
           },
         },
         mutationCache: new MutationCache({
@@ -109,6 +110,20 @@ export function TRPCProvider({
 
     return unsubscribe;
   }, [pathname, queryClient]);
+  // After any mutation settles successfully, refresh the Router Cache. A
+  // mutation can change server-rendered (RSC) data, but with the client Router
+  // Cache (next.config staleTimes) a later navigation back to an affected page
+  // would otherwise replay the stale pre-mutation payload — and SessionGuard's
+  // fingerprint check won't catch it (the acting user's own auth is unchanged).
+  React.useEffect(() => {
+    const unsubscribe = queryClient.getMutationCache().subscribe((event) => {
+      if (event.type === "updated" && event.action.type === "success") {
+        router.refresh();
+      }
+    });
+
+    return unsubscribe;
+  }, [queryClient, router]);
   const [trpcClient] = useState(() =>
     trpc.createClient({
       links: [
diff --git a/apps/admin/lib/request-auth.ts b/apps/admin/lib/request-auth.ts
index 0af82713a..e01d2c736 100644
--- a/apps/admin/lib/request-auth.ts
+++ b/apps/admin/lib/request-auth.ts
@@ -92,6 +92,32 @@ export function stripTrustedAuthHeaders(source: Headers): Headers {
   return sanitized;
 }
 
+/**
+ * Deterministic fingerprint of who the viewer is and everything that governs
+ * what they can access: their identity (userId + tenant), org roles, and every
+ * group membership with that group's roles. Used by <SessionGuard> to decide
+ * whether a cached RSC payload is still valid.
+ *
+ * Identity is included because the session cookie can switch to a *different*
+ * user (e.g. sign-in in another tab) who happens to have identical roles/groups
+ * — without userId the fingerprint would still match and user-scoped cached
+ * pages (/profile, /my-connections) would keep showing the previous user's
+ * data. Roles/groups are included because the coarse dashboard role is not
+ * enough — e.g. a team admin removed from one team keeps the same role but loses
+ * access to that team's pages.
+ */
+export function computeAuthFingerprint(
+  auth: Pick<AuthContext, "groups" | "orgRoles" | "tenantId" | "userId">,
+): string {
+  const orgRoles = [...auth.orgRoles].sort().join(",");
+  const groups = auth.groups
+    .map((group) => `${group.id}:${[...group.roles].sort().join("|")}`)
+    .sort()
+    .join(",");
+
+  return `${auth.userId}@${auth.tenantId}#${orgRoles}#${groups}`;
+}
+
 export function getDashboardRoleFromAuth(
   auth: Pick<AuthContext, "groups" | "orgRoles">,
 ): "member" | "org_admin" | "org_viewer" | "team_admin" {
diff --git a/apps/admin/next.config.ts b/apps/admin/next.config.ts
index 7d3bd1f3f..9d28aff48 100644
--- a/apps/admin/next.config.ts
+++ b/apps/admin/next.config.ts
@@ -5,6 +5,28 @@ const isDev = process.env.NODE_ENV === "development";
 
 const nextConfig: NextConfig = {
   experimental: {
+    // Client Router Cache TTLs (seconds) so navigating between recently-visited
+    // pages reuses the RSC payload instead of re-rendering on the server every
+    // time. Both buckets are pinned to the same window:
+    //   - `dynamic`: dynamic routes reached via navigation / default ("auto")
+    //     prefetch.
+    //   - `static`: routes fully prefetched via <Link prefetch={true}> — the
+    //     sidebar hover-prefetch (app-sidebar-sections.tsx) uses this for the
+    //     heavy /apps and /settings/policies pages. Full prefetches land in the
+    //     `static` bucket regardless of force-dynamic, and without an explicit
+    //     value it would default to 300s, letting those pages serve stale
+    //     toolkit/policy data far longer than the rest of the app.
+    //
+    // Every route is auth-gated and a Router Cache hit skips the server, so
+    // <SessionGuard> (components/session-guard.tsx) revalidates on navigation /
+    // refocus: a dead session 401s and TRPCProvider full-redirects to sign-in
+    // (clearing this cache), and an auth-fingerprint change (role or team
+    // membership) triggers router.refresh() to bust it. Plain data staleness
+    // within the window (auth unchanged) is the accepted tradeoff.
+    staleTimes: {
+      dynamic: 60,
+      static: 60,
+    },
     optimizePackageImports: [
       "lucide-react",
       "@radix-ui/react-checkbox",
@@ -16,6 +38,9 @@ const nextConfig: NextConfig = {
       "@radix-ui/react-tabs",
       "@radix-ui/react-tooltip",
       "recharts",
+      "@tanstack/react-query",
+      "@tanstack/react-table",
+      "@tanstack/react-virtual",
     ],
   },
   images: {
diff --git a/apps/admin/server/auth-broker-validation.ts b/apps/admin/server/auth-broker-validation.ts
index 68fe2f8b0..1060c135c 100644
--- a/apps/admin/server/auth-broker-validation.ts
+++ b/apps/admin/server/auth-broker-validation.ts
@@ -10,6 +10,7 @@ import {
   ADMIN_GROUP_CACHE_PREFIX,
   createAdminGroupCache,
 } from "@/server/group-cache";
+import { createTtlCache } from "@/server/ttl-cache";
 import { env } from "@/server/env";
 import {
   JwtPayloadSchema,
@@ -29,6 +30,19 @@ const middlewareByApplicationId = new Map<
   ReturnType<typeof createFusionAuthMiddleware>
 >();
 
+const TENANT_APPLICATION_CACHE_TTL_MS = 5 * 60 * 1000;
+// Tenant -> FusionAuth application IDs are set at provisioning time and are
+// immutable at runtime: the generic org settings update strips `fusionauth`
+// (see routers/organizations/update-current-org.ts), so they cannot be changed
+// through the app. Caching them keeps token validation (which runs on every
+// authenticated request) off Postgres. No invalidation hook is needed — the
+// only writer is out-of-process provisioning, which a per-instance cache could
+// not be signalled from anyway. Mirrors the TTL cache in fusionauth-tenant-key.ts.
+const tenantApplicationCache = createTtlCache<{
+  adminApplicationId: string;
+  mcpApplicationId: string;
+}>(TENANT_APPLICATION_CACHE_TTL_MS);
+
 async function parseVerifiedPayload(token: string): Promise<JWTPayload> {
   const { payload } = await jwtVerify(token, jwks, {
     issuer: env.FUSIONAUTH_ISSUER,
@@ -53,6 +67,12 @@ export async function resolveTenantFusionAuthApplications(
   adminApplicationId: string;
   mcpApplicationId: string;
 }> {
+  const cached = tenantApplicationCache.get(tenantId);
+
+  if (cached) {
+    return cached;
+  }
+
   const organization = await prisma.organization.findUnique({
     where: { fusionauthTenantId: tenantId },
     select: { settings: true },
@@ -81,6 +101,11 @@ export async function resolveTenantFusionAuthApplications(
     );
   }
 
+  tenantApplicationCache.set(tenantId, {
+    adminApplicationId,
+    mcpApplicationId,
+  });
+
   return { adminApplicationId, mcpApplicationId };
 }
 
diff --git a/apps/admin/server/fusionauth-tenant-key.ts b/apps/admin/server/fusionauth-tenant-key.ts
index dccb2c845..d9224a40d 100644
--- a/apps/admin/server/fusionauth-tenant-key.ts
+++ b/apps/admin/server/fusionauth-tenant-key.ts
@@ -1,10 +1,11 @@
 import { prisma } from "@repo/db";
 import { decryptComposioApiKey } from "@repo/db";
 import { AppError, AppErrorCode } from "@repo/types/errors";
+import { createTtlCache } from "@/server/ttl-cache";
 import { env } from "@/server/env";
 
-const tenantKeyCache = new Map<string, { expiresAt: number; key: string }>();
 const CACHE_TTL_MS = 5 * 60 * 1000;
+const tenantKeyCache = createTtlCache<string>(CACHE_TTL_MS);
 
 /**
  * Resolve the per-tenant FusionAuth API key from the encrypted DB column.
@@ -16,8 +17,8 @@ export async function getFusionAuthKeyForTenant(
 ): Promise<string> {
   const cached = tenantKeyCache.get(tenantId);
 
-  if (cached && cached.expiresAt > Date.now()) {
-    return cached.key;
+  if (cached !== undefined) {
+    return cached;
   }
 
   const org = await prisma.organization.findUnique({
@@ -43,14 +44,11 @@ export async function getFusionAuthKeyForTenant(
     secrets,
   );
 
-  tenantKeyCache.set(tenantId, {
-    expiresAt: Date.now() + CACHE_TTL_MS,
-    key: decrypted,
-  });
+  tenantKeyCache.set(tenantId, decrypted);
 
   return decrypted;
 }
 
 export function invalidateTenantKeyCache(tenantId: string): void {
-  tenantKeyCache.delete(tenantId);
+  tenantKeyCache.invalidate(tenantId);
 }
diff --git a/apps/admin/server/routers/me/get-session.ts b/apps/admin/server/routers/me/get-session.ts
new file mode 100644
index 000000000..1c9e8268d
--- /dev/null
+++ b/apps/admin/server/routers/me/get-session.ts
@@ -0,0 +1,19 @@
+import { computeAuthFingerprint } from "@/lib/request-auth";
+import { authedProcedure } from "@/server/trpc";
+
+/**
+ * Lightweight session probe used by <SessionGuard> as a navigation/focus
+ * heartbeat. Throws 401 (via authedProcedure) when the session is gone, and
+ * otherwise returns a fingerprint of the caller's current authorization state
+ * (org roles + group/team memberships + per-group roles).
+ *
+ * SessionGuard compares this fingerprint to the one the cached RSC shell was
+ * rendered with and busts the client Router Cache (router.refresh) when they
+ * diverge — so a role downgrade *or* a team-membership change can't keep
+ * replaying role/team-gated cached payloads.
+ */
+export const getSession = authedProcedure.query(
+  ({ ctx }): { fingerprint: string } => {
+    return { fingerprint: computeAuthFingerprint(ctx.auth) };
+  },
+);
diff --git a/apps/admin/server/routers/me/router.ts b/apps/admin/server/routers/me/router.ts
index 01a6118b3..49e796e8b 100644
--- a/apps/admin/server/routers/me/router.ts
+++ b/apps/admin/server/routers/me/router.ts
@@ -1,6 +1,7 @@
 import { router } from "@/server/trpc";
 import { getPocReminder } from "./get-poc-reminder";
 import { getProfile } from "./get-profile";
+import { getSession } from "./get-session";
 import { getSetup } from "./get-setup";
 import { getToolPreference } from "./get-tool-preference";
 import { listConnections } from "./list-connections";
@@ -11,6 +12,7 @@ import { updateToolPreference } from "./update-tool-preference";
 export const meRouter = router({
   getPocReminder,
   getProfile,
+  getSession,
   getSetup,
   getToolPreference,
   listConnections,
diff --git a/apps/admin/server/routers/organizations/update-current-org.ts b/apps/admin/server/routers/organizations/update-current-org.ts
index f2ba2834f..c198f33a4 100644
--- a/apps/admin/server/routers/organizations/update-current-org.ts
+++ b/apps/admin/server/routers/organizations/update-current-org.ts
@@ -75,6 +75,13 @@ export const updateCurrentOrg = orgAdminProcedure
         // dedicated save/disable procedures which handle validation, audit
         // metadata, credential encryption, and proxy cache invalidation.
         delete (normalized as Record<string, unknown>)["siem"];
+        // Strip `fusionauth` — the tenant's login application IDs are set at
+        // provisioning time and must stay immutable at runtime. They are read on
+        // every authenticated request and cached in-process (see
+        // auth-broker-validation.ts), so allowing this generic update to rewrite
+        // them would both invalidate that immutability assumption and let an org
+        // admin corrupt their own login applications.
+        delete (normalized as Record<string, unknown>)["fusionauth"];
         mergedSettings = { ...rawExisting, ...normalized };
       }
 
diff --git a/apps/admin/server/team-detail-snapshot.ts b/apps/admin/server/team-detail-snapshot.ts
index dcef3f3b6..ed6800cf8 100644
--- a/apps/admin/server/team-detail-snapshot.ts
+++ b/apps/admin/server/team-detail-snapshot.ts
@@ -381,12 +381,23 @@ async function buildTeamSnapshot(
     ...connectionOwnerIds,
   ];
 
-  const userMappings = await prisma.userMapping.findMany({
-    where: {
-      orgId: detail.orgId,
-      fusionauthUserId: { in: [...new Set(referencedUserIds)] },
-    },
-  });
+  const [userMappings, activeConnectionCounts] = await Promise.all([
+    prisma.userMapping.findMany({
+      where: {
+        orgId: detail.orgId,
+        fusionauthUserId: { in: [...new Set(referencedUserIds)] },
+      },
+    }),
+    prisma.personalConnectedAccount.groupBy({
+      by: ["userId"],
+      where: {
+        orgId: detail.orgId,
+        userId: { in: memberIds },
+        status: "active",
+      },
+      _count: { _all: true },
+    }),
+  ]);
 
   const mappingEmailByUserId = new Map(
     userMappings
@@ -410,15 +421,6 @@ async function buildTeamSnapshot(
     ...fusionAuthEmailByUserId.entries(),
   ]);
 
-  const activeConnectionCounts = await prisma.personalConnectedAccount.groupBy({
-    by: ["userId"],
-    where: {
-      orgId: detail.orgId,
-      userId: { in: memberIds },
-      status: "active",
-    },
-    _count: { _all: true },
-  });
   const connectionCountByUserId = new Map(
     activeConnectionCounts.map((row) => [row.userId, row._count._all]),
   );
diff --git a/apps/admin/server/ttl-cache.test.ts b/apps/admin/server/ttl-cache.test.ts
new file mode 100644
index 000000000..a231a0d3e
--- /dev/null
+++ b/apps/admin/server/ttl-cache.test.ts
@@ -0,0 +1,57 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createTtlCache } from "@/server/ttl-cache";
+
+describe("createTtlCache", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("returns undefined for an unknown key", () => {
+    const cache = createTtlCache<string>(1000);
+    expect(cache.get("missing")).toBeUndefined();
+  });
+
+  it("returns a stored value before the TTL elapses", () => {
+    const cache = createTtlCache<{ id: string }>(1000);
+    cache.set("k", { id: "abc" });
+    vi.advanceTimersByTime(999);
+    expect(cache.get("k")).toEqual({ id: "abc" });
+  });
+
+  it("expires a value once the TTL elapses", () => {
+    const cache = createTtlCache<string>(1000);
+    cache.set("k", "v");
+    vi.advanceTimersByTime(1000);
+    expect(cache.get("k")).toBeUndefined();
+  });
+
+  it("invalidate() drops a value before the TTL elapses", () => {
+    const cache = createTtlCache<string>(1000);
+    cache.set("k", "v");
+    cache.invalidate("k");
+    expect(cache.get("k")).toBeUndefined();
+  });
+
+  it("isolates entries by key", () => {
+    const cache = createTtlCache<string>(1000);
+    cache.set("a", "1");
+    cache.set("b", "2");
+    cache.invalidate("a");
+    expect(cache.get("a")).toBeUndefined();
+    expect(cache.get("b")).toBe("2");
+  });
+
+  it("refreshes the TTL when a key is overwritten", () => {
+    const cache = createTtlCache<string>(1000);
+    cache.set("k", "v1");
+    vi.advanceTimersByTime(900);
+    cache.set("k", "v2");
+    vi.advanceTimersByTime(900);
+    expect(cache.get("k")).toBe("v2");
+  });
+});
diff --git a/apps/admin/server/ttl-cache.ts b/apps/admin/server/ttl-cache.ts
new file mode 100644
index 000000000..38c7ecded
--- /dev/null
+++ b/apps/admin/server/ttl-cache.ts
@@ -0,0 +1,41 @@
+/**
+ * Minimal in-process TTL cache. Entries expire `ttlMs` after they are written
+ * and are evicted lazily on read. Intended for caching small, slow-changing
+ * per-tenant lookups (e.g. resolved FusionAuth application IDs / API keys) so
+ * that hot request paths do not hit Postgres on every authenticated request.
+ *
+ * Scope caveat: this is per-process. On serverless (Vercel) each warm instance
+ * keeps its own copy, so `invalidate()` only clears the instance that calls it.
+ * Use only for data that is safe to serve up to `ttlMs` stale.
+ */
+export type TtlCache<V> = {
+  get: (key: string) => V | undefined;
+  set: (key: string, value: V) => void;
+  invalidate: (key: string) => void;
+};
+
+export function createTtlCache<V>(ttlMs: number): TtlCache<V> {
+  const store = new Map<string, { expiresAt: number; value: V }>();
+
+  return {
+    get(key: string): V | undefined {
+      const entry = store.get(key);
+
+      if (entry && entry.expiresAt > Date.now()) {
+        return entry.value;
+      }
+
+      // Lazily evict the expired (or absent) entry so the Map can't grow
+      // unbounded across many distinct or one-off tenant IDs over the lifetime
+      // of a long-lived admin process.
+      store.delete(key);
+      return undefined;
+    },
+    set(key: string, value: V): void {
+      store.set(key, { expiresAt: Date.now() + ttlMs, value });
+    },
+    invalidate(key: string): void {
+      store.delete(key);
+    },
+  };
+}
</article></body></html>