start-vibing-stacks 2.18.0 → 2.20.0

package/stacks/frontend/react/skills/zod-validation/SKILL.md

@@ -1,42 +1,97 @@
 ---
 name: zod-validation
-version: 1.0.0
+version: 2.0.0
+description: "Zod 4 (stable Aug 2025) runtime validation for TypeScript boundaries — forms, API responses, env vars, server actions. Zod 4 brings 14× faster string parsing, 7× array, 6.5× object, 57% smaller bundle, 2× faster TS compile, 100× fewer tsc instantiations. Major API shifts: top-level format validators (`z.email()`, `z.url()`, `z.uuid()`) for tree-shaking; unified `error` parameter replaces `required_error` / `invalid_type_error` / `errorMap`. Codemod available: `npx @zod/codemod`. Covers schema design, RHF + zodResolver integration, API response validation, split server/client env schemas (security-critical for `NEXT_PUBLIC_*`), reusable schemas, transforms, and Next.js Server Actions. Mentions Valibot/ArkType when bundle/inference cost matters. Invoke at any trust boundary."
 ---
 
-# Zod Validation — Runtime Type Safety
+# Zod 4 — Runtime Type Safety (2026)
 
-**ALWAYS use Zod for form validation, API responses, and data boundaries.**
+**ALWAYS use Zod 4 for form validation, API responses, env vars, server actions.**
 
-## Why Zod
+## Why Zod 4 (stable since August 2025)
 
-- Runtime validation (TypeScript types disappear at runtime)
-- Auto-infer TypeScript types from schemas
-- Works with React Hook Form, tRPC, Next.js Server Actions
-- Single source of truth: schema → type → validation
+- **14× faster** string parsing, **7×** array, **6.5×** object
+- **57% smaller** core bundle
+- **~2× faster** TS compilation on large schemas; **100× fewer** tsc instantiations
+- Ecosystem locked in: tRPC, Drizzle, React Hook Form, OpenAPI generators
+- 15M+ weekly downloads — the de-facto standard
+
+### When to consider an alternative
+
+| Situation | Tool |
+|---|---|
+| **Bundle size** is critical (edge functions, embeds) | **Valibot** — sub-1KB simple schemas |
+| You want **faster TS check** in giant codebases | **Valibot** (~18× faster type-check vs Zod 4) |
+| You like TS-syntax string schemas | **ArkType** |
+| Mainstream ecosystem + maturity | **Zod 4** ✅ |
+
+## Migration v3 → v4
+
+```bash
+npx @zod/codemod --transform v3-to-v4 ./src
+```
+
+The two breaking changes you'll see most:
+
+### 1. Top-level format validators (tree-shaking)
+
+```tsx
+// v3 (works in v4 but not tree-shakable)
+z.string().email().min(5);
+
+// v4 — recommended
+z.email();
+z.url();
+z.uuid();
+z.iso.datetime();         // ISO-8601
+z.iso.date();
+z.cuid2();
+z.ipv4();
+z.ipv6();
+z.base64();
+z.jwt();
+```
+
+### 2. Unified `error` parameter
+
+```tsx
+// v3 — three different parameters
+z.string({
+  required_error: "Required",
+  invalid_type_error: "Must be a string",
+  errorMap: ({ code }) => ({ message: code === "too_small" ? "Too short" : "Invalid" }),
+});
+
+// v4 — one parameter, string or function
+z.string({
+  error: (issue) => issue.code === "too_small" ? "Too short" : "Required",
+});
+// Or just a string:
+z.string({ error: "Name is required" });
+```
 
 ## Core Patterns
 
-### Schema Definition
+### Schema definition
 
 ```tsx
 import { z } from 'zod';
 
-// Define schema
 const UserSchema = z.object({
-  name: z.string().min(2, 'Name must be at least 2 characters'),
-  email: z.string().email('Invalid email address'),
-  age: z.number().min(18, 'Must be 18+').max(120),
-  role: z.enum(['admin', 'user', 'moderator']),
-  bio: z.string().max(500).optional(),
-  tags: z.array(z.string()).min(1, 'At least one tag required'),
+  name:     z.string().min(2, "Name must be at least 2 characters"),
+  email:    z.email({ error: "Enter a valid email" }),       // v4 top-level
+  age:      z.number().min(18, "Must be 18+").max(120),
+  role:     z.enum(["admin", "user", "moderator"]),
+  bio:      z.string().max(500).optional(),
+  tags:     z.array(z.string()).min(1, "At least one tag required"),
   metadata: z.record(z.string(), z.unknown()).optional(),
 });
 
-// Infer type from schema (SINGLE SOURCE OF TRUTH)
+// SINGLE SOURCE OF TRUTH — schema → type
 type User = z.infer<typeof UserSchema>;
 ```
 
-### Form Validation (React Hook Form + Zod)
+### Form Validation (React Hook Form + Zod 4)
 
 ```tsx
 import { useForm } from 'react-hook-form';
@@ -44,7 +99,7 @@ import { zodResolver } from '@hookform/resolvers/zod';
 
 const CreateUserSchema = z.object({
   name: z.string().min(2),
-  email: z.string().email(),
+  email: z.email(),                                   // v4 top-level
   password: z.string().min(8, 'Password must be at least 8 characters'),
   confirmPassword: z.string(),
 }).refine((data) => data.password === data.confirmPassword, {
@@ -150,24 +205,47 @@ export const clientEnv = ClientEnvSchema.parse({
 
 **Rule:** If a variable contains a key, secret, token, or password, it MUST be in `ServerEnvSchema` without `NEXT_PUBLIC_` prefix.
 
-### Reusable Schemas
+### Reusable Schemas (Zod 4 top-level)
 
 ```tsx
-// Shared between frontend and backend
-// schemas/user.ts
-
-export const EmailSchema = z.string().email().toLowerCase().trim();
+// schemas/common.ts — shared between frontend and backend
+export const EmailSchema    = z.email().transform(v => v.toLowerCase().trim());
 export const PasswordSchema = z.string().min(8).max(128);
-export const UUIDSchema = z.string().uuid();
+export const UUIDSchema     = z.uuid();
+export const URLSchema      = z.url();
+export const ISODateSchema  = z.iso.datetime();
+
 export const PaginationSchema = z.object({
-  page: z.coerce.number().min(1).default(1),
+  page:  z.coerce.number().min(1).default(1),
   limit: z.coerce.number().min(1).max(100).default(20),
 });
 
 export const DateRangeSchema = z.object({
   from: z.coerce.date(),
-  to: z.coerce.date(),
-}).refine((d) => d.to > d.from, 'End date must be after start date');
+  to:   z.coerce.date(),
+}).refine(d => d.to > d.from, "End date must be after start date");
+```
+
+### Discriminated unions (polymorphic payloads)
+
+```tsx
+const PaymentSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("card"), last4: z.string().length(4) }),
+  z.object({ type: z.literal("pix"),  key:   z.string() }),
+  z.object({ type: z.literal("boleto"), barcode: z.string() }),
+]);
+type Payment = z.infer<typeof PaymentSchema>;
+```
+
+### Branded types — distinguish IDs at the type level
+
+```tsx
+const UserIdSchema = z.uuid().brand<"UserId">();
+type UserId = z.infer<typeof UserIdSchema>;
+
+function getUser(id: UserId) { /* … */ }
+getUser("not a uuid");                  // ❌ type error
+getUser(UserIdSchema.parse(input));     // ✅
 ```
 
 ### Transform & Preprocess
@@ -253,20 +331,64 @@ export function LeadForm() {
 }
 ```
 
+## Use with React 19 Actions + `useActionState`
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import { z } from "zod";
+
+const Schema = z.object({
+  email:    z.email(),
+  password: z.string().min(8),
+});
+
+async function loginAction(_prev: { error: string | null }, formData: FormData) {
+  const parsed = Schema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) return { error: parsed.error.issues[0].message };
+  return await loginRequest(parsed.data);
+}
+
+export function LoginForm() {
+  const [state, action, pending] = useActionState(loginAction, { error: null });
+  return (
+    <form action={action}>
+      <input name="email" type="email" />
+      <input name="password" type="password" />
+      {state.error && <p className="text-destructive">{state.error}</p>}
+      <button disabled={pending}>{pending ? "Signing in…" : "Sign in"}</button>
+    </form>
+  );
+}
+```
+
 ## FORBIDDEN
 
 | Don't | Do |
 |---|---|
-| Trust API responses blindly | `Schema.parse(response)` |
-| Manual `if/else` validation | Zod schema |
+| Trust API responses blindly | `Schema.parse(response)` (or `safeParse` for soft fail) |
+| Manual `if/else` validation | Zod schema (single source of truth) |
 | Duplicate types + validation | `z.infer<typeof Schema>` |
 | `any` or `unknown` without validation | Parse with Zod first |
-| Validate only on server | Validate on BOTH client + server |
+| Validate only on server | Validate on BOTH client and server |
+| `z.string().email()` in v4 | `z.email()` (tree-shakable, top-level) |
+| `required_error` / `invalid_type_error` / `errorMap` (v3) | Unified `error` parameter (v4) |
+| Dump secrets into `NEXT_PUBLIC_*` | Server-only `ServerEnvSchema`; client gets only public keys |
+| Re-implement common formats (URL, UUID, datetime, JWT) | `z.url()`, `z.uuid()`, `z.iso.datetime()`, `z.jwt()` |
 
 ## Rules
 
 1. **SINGLE SOURCE OF TRUTH** — schema defines type AND validation
-2. **VALIDATE AT BOUNDARIES** — forms, API responses, env vars
-3. **SAFE PARSE FOR UI** — `safeParse()` for user-facing, `parse()` for internal
-4. **SHARED SCHEMAS** — same schema on frontend and backend
-5. **TRANSFORM DATA** — clean/normalize during validation, not after
+2. **VALIDATE AT BOUNDARIES** — forms, API responses, env vars, queue messages
+3. **SAFE PARSE FOR UI** — `safeParse()` for user-facing forms, `parse()` for internal/trusted
+4. **SHARED SCHEMAS** — same schema on frontend and backend (workspace package)
+5. **TRANSFORM DURING VALIDATION** — `.toLowerCase()`, `.trim()`, `.transform(...)` happen as part of `parse`, not afterwards
+6. **PREFER TOP-LEVEL FORMAT VALIDATORS** in v4 — better tree-shaking + clearer intent
+
+## See Also
+
+- `react-patterns` v2 — `useActionState`, `useOptimistic`, `use()` hook
+- `react-ui-patterns` v2 — RHF + Zod + TanStack Query patterns
+- `shadcn-ui` v2 — `<Form>` component built on RHF + Zod
+- `_shared/skills/security-baseline` v2 — input validation as defense layer
+- `_shared/skills/openapi-design` v2 — schemas → OpenAPI 3.2

package/stacks/frontend/react-api/skills/axios-laravel-api/SKILL.md

@@ -1,11 +1,7 @@
 ---
 name: axios-laravel-api
-version: 1.0.0
-description: Axios HTTP client for Laravel 12 + Sanctum SPA — `withCredentials`,
-  `withXSRFToken`, `/sanctum/csrf-cookie` flow, and `401/403/419/422/5xx`
-  interceptors. Use when wiring a React (or any SPA) frontend to a Laravel
-  cookie-authenticated JSON API. Pairs with `laravel-api-architecture` and
-  `react-api-standards`.
+version: 2.0.0
+description: "Axios HTTP client for Laravel 12 + Sanctum SPA in React 19 (Tailwind v4) projects. `withCredentials: true` + `withXSRFToken: true` + `/sanctum/csrf-cookie` priming flow, plus a single response interceptor that handles 401 (logout), 403 (forbidden toast), 419 (CSRF stale → re-prime + retry once), 422 (validation errors surfaced to RHF), 5xx (toast + log). Pairs with `laravel-api-architecture` (backend) and `react-api-standards` (frontend conventions). 2026 polish: Zod 4 response validation at the boundary, TanStack Query v5 `signal` threading for cancellation, React 19 forms via `useActionState` for client-side mutations. Invoke when wiring or auditing the API client, login flow, or CSRF/cookie configuration."
 ---
 
 # Axios + Laravel Sanctum SPA Client

package/stacks/frontend/react-api/skills/react-api-standards/SKILL.md

@@ -1,25 +1,23 @@
 ---
 name: react-api-standards
-version: 1.0.0
-description: React 19 + Vite + Axios standards for a Laravel-backed JSON API SPA
-  — Page shell + skeleton, async data via `api.get`, form 422 binding, route
-  catch-all, no Inertia. Use for any new React page in a Laravel + Sanctum SPA
-  project. Pairs with `axios-laravel-api` and `laravel-api-architecture`.
+version: 2.0.0
+description: "React 19 + Vite 6 + Axios standards for a Laravel-backed JSON API SPA. Page shell + skeleton-first paint, async data via `api.get`, 422 validation binding to React Hook Form, protected-route + catch-all routing, NO Inertia. Pairs with `axios-laravel-api` (HTTP client) and `laravel-api-architecture` (backend). 2026 polish: TanStack Query v5 (`isPending` semantics + `signal` threading), Zod 4 (`z.email()`/`z.url()` top-level), `useOptimistic` for instant feedback, `useActionState` for form submissions, `useFormStatus` to wire Submit buttons without prop drilling. Tailwind v4 with `@theme` and OKLCH tokens. Invoke for any new page, layout, or component in a Laravel + Sanctum SPA."
 ---
 
-# React 19 API-First Standards (Laravel + Axios)
+# React 19 API-First Standards (Laravel + Axios) — 2026
 
 **ALWAYS invoke when creating React pages, components, or layouts in a project
 that uses a Laravel JSON API as backend (NOT Inertia.js).**
 
 ## Version Requirements
 
-- **React >= 19** — MANDATORY (`useActionState`, `useOptimistic`, `use`)
-- **Vite >= 5** with `@vitejs/plugin-react`
-- **TailwindCSS >= 4**
-- **Axios >= 1.6** (for `withXSRFToken` support)
-- **TanStack Query >= 5** (recommended for cached lists/details)
-- **react-router-dom >= 6** (client-side routing)
+- **React ≥ 19.0** — MANDATORY (`useActionState`, `useOptimistic`, `useFormStatus`, `use()`)
+- **Vite ≥ 6** with `@vitejs/plugin-react`
+- **TailwindCSS ≥ 4** (CSS-first `@theme`, Oxide engine)
+- **Axios ≥ 1.7** (for `withXSRFToken` and modern interceptor types)
+- **TanStack Query ≥ 5** — `isPending` (no data yet) vs `isFetching` (any in-flight); thread `signal` through `queryFn`
+- **Zod ≥ 4** — top-level `z.email()`/`z.url()` for tree-shaking
+- **react-router-dom ≥ 7** (`<RouterProvider>` + data routers)
 
 ## Folder Structure
 

package/stacks/nodejs/scripts/check-route-slugs.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * check-route-slugs.mjs
+ *
+ * Static validator for Next.js App Router dynamic-segment naming.
+ *
+ * Catches the "You cannot use different slug names for the same dynamic path"
+ * runtime error BEFORE it ships, because `next build` does not catch it.
+ *
+ * Rule: inside the same parent directory, every bracket-named child
+ * (`[id]`, `[...slug]`, `[[...slug]]`) MUST share the same inner identifier.
+ *
+ * Examples:
+ *
+ *   OK     app/users/[userId]/page.tsx
+ *          app/users/[userId]/posts/page.tsx
+ *
+ *   FAIL   app/users/[id]/page.tsx
+ *          app/users/[userId]/posts/page.tsx     <-- different slug, same parent
+ *
+ * Usage:
+ *   node scripts/check-route-slugs.mjs            # auto-detect ./app and ./src/app
+ *   node scripts/check-route-slugs.mjs ./app      # explicit root(s)
+ *
+ * Exit codes:
+ *   0  OK
+ *   1  conflicting slug names detected
+ *   2  no app directory found (skipped, not an error in non-Next.js repos)
+ */
+
+import { readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join, relative } from 'node:path';
+
+const BRACKET_RE = /^\[\[?\.\.\.?([A-Za-z0-9_]+)\]?\]$|^\[([A-Za-z0-9_]+)\]$/;
+
+function extractSlugName(dirName) {
+  const m = dirName.match(BRACKET_RE);
+  if (!m) return null;
+  return m[1] ?? m[2] ?? null;
+}
+
+async function listChildDirs(parent) {
+  const entries = await readdir(parent, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+async function walk(root, conflicts) {
+  const children = await listChildDirs(root);
+
+  const bracketChildren = children
+    .map((name) => ({ name, slug: extractSlugName(name) }))
+    .filter((c) => c.slug !== null);
+
+  if (bracketChildren.length > 1) {
+    const slugs = new Set(bracketChildren.map((c) => c.slug));
+    if (slugs.size > 1) {
+      conflicts.push({
+        parent: root,
+        children: bracketChildren.map((c) => c.name),
+      });
+    }
+  }
+
+  for (const child of children) {
+    await walk(join(root, child), conflicts);
+  }
+}
+
+async function detectRoots(args) {
+  if (args.length > 0) return args.map((p) => resolve(p));
+  const candidates = ['app', 'src/app'].map((p) => resolve(process.cwd(), p));
+  return candidates.filter((p) => existsSync(p));
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const roots = await detectRoots(args);
+
+  if (roots.length === 0) {
+    console.log('[route-slugs] no app/ or src/app/ directory found — skipped.');
+    process.exit(2);
+  }
+
+  const conflicts = [];
+  for (const root of roots) {
+    const s = await stat(root).catch(() => null);
+    if (!s?.isDirectory()) continue;
+    await walk(root, conflicts);
+  }
+
+  if (conflicts.length > 0) {
+    console.error('');
+    console.error('  ROUTE SLUG CONFLICT (next.js will crash at runtime)');
+    console.error('  ' + '─'.repeat(60));
+    console.error('');
+    console.error(
+      '  Next.js requires that every bracket-named sibling under the SAME'
+    );
+    console.error(
+      '  parent directory uses the SAME inner slug name. Mixing names'
+    );
+    console.error(
+      '  produces: "You cannot use different slug names for the same'
+    );
+    console.error('  dynamic path".');
+    console.error('');
+    for (const c of conflicts) {
+      const rel = relative(process.cwd(), c.parent) || '.';
+      console.error(`  in: ${rel}/`);
+      for (const child of c.children) {
+        console.error(`    ├── ${child}`);
+      }
+      console.error('');
+    }
+    console.error('  Fix: pick ONE slug name per resource (e.g. [userId]) and');
+    console.error('       rename every conflicting sibling to match.');
+    console.error('');
+    process.exit(1);
+  }
+
+  const scanned = roots.map((r) => relative(process.cwd(), r) || '.').join(', ');
+  console.log(`[route-slugs] OK — no slug conflicts in: ${scanned}`);
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('[route-slugs] script failed:', err);
+  process.exit(1);
+});

package/stacks/nodejs/skills/nextjs-app-router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nextjs-app-router
-version: 1.0.0
+version: 1.1.0
 ---
 
 # Next.js App Router — Modern Patterns
@@ -27,6 +27,77 @@ app/
     └── route.ts        # API route handler
 ```
 
+---
+
+## Dynamic Route Slug Consistency (CRITICAL — silent build killer)
+
+> **Next.js validates dynamic-segment slug names at REQUEST TIME, not at build time.** `next build` / `bun run build` **does not catch** this class of bug. It blows up the first time anyone hits the route in production with:
+>
+> ```
+> Error: You cannot use different slug names for the same dynamic path ('id' !== 'userId').
+> ```
+
+### The Rule
+
+Inside the **same parent directory**, every `[bracket]` child segment MUST use the **same** inner name. Pick one slug name per resource and reuse it through every nested route under it.
+
+```
+# BROKEN — same parent (app/users/), different slug names
+app/users/[id]/page.tsx
+app/users/[userId]/posts/page.tsx        ← runtime crash
+
+# CORRECT — one canonical slug per resource
+app/users/[userId]/page.tsx
+app/users/[userId]/posts/page.tsx
+app/users/[userId]/posts/[postId]/page.tsx
+```
+
+This also applies to catch-all (`[...slug]`) and optional catch-all (`[[...slug]]`) — you may not mix a `[id]` and `[...rest]` as siblings of the same parent.
+
+### Pre-Flight Check (run BEFORE creating any new dynamic route)
+
+```bash
+# Quick visual scan — list every dynamic segment with its depth
+find src/app app -type d -name '[[]*[]]' 2>/dev/null \
+  | awk -F/ '{print NF":"$0}' | sort
+```
+
+Eyeball the output: any two paths that share a prefix up to depth `N-1` and diverge into different `[name]` at depth `N` are the bug.
+
+### Programmatic Check (CI gate — mandatory)
+
+The stack ships a Bun script at `scripts/check-route-slugs.mjs`. Add it to `package.json` and wire it into the quality gate **before** `build`:
+
+```jsonc
+{
+  "scripts": {
+    "routes:check": "bun scripts/check-route-slugs.mjs",
+    "prebuild": "bun run routes:check",
+    "build": "next build"
+  }
+}
+```
+
+Why `prebuild`: makes the check unskippable for anyone running `bun run build` locally, in Vercel, or in CI. The check completes in milliseconds and exits non-zero on the first conflict, with the offending parent dir and conflicting slugs in the error message.
+
+### When to Run
+
+- ☑ **Before creating** any new `[something]/page.tsx` or `[something]/route.ts`
+- ☑ **Before any commit** touching `app/**/[*]/**`
+- ☑ **In CI** before `bun run build`
+- ☑ **As `prebuild`** in `package.json` so local builds also catch it
+
+### Convention — name your slugs by resource, not by position
+
+| Resource | Slug |
+|---|---|
+| User | `[userId]` |
+| Organization / tenant | `[orgId]` or `[tenantId]` |
+| Post / article | `[postId]` |
+| Instance ID (Evolution API, webhook key) | `[instanceKey]` (or whatever you commit to — pick once) |
+
+Generic `[id]` is acceptable only at the root of a resource (`app/users/[id]/...`) **if and only if** you stay with `[id]` through every nested segment under it. Mixing `[id]` and `[userId]` under the same parent is the bug.
+
 ## Server vs Client Components
 
 ```tsx
@@ -106,6 +177,152 @@ export async function POST(request: NextRequest) {
 }
 ```
 
+## Webhook Handler — Critical Path (avoid retry storms)
+
+> A webhook receiver is a **critical path you do not control**. The provider (Stripe, GitHub, Evolution, Meta, etc.) will retry — often aggressively, often forever — every non-`2xx`. Any error you let propagate becomes their problem AND yours.
+
+### The Three Rules
+
+1. **Verify signature with the RAW body BEFORE parsing JSON.** Parsing first leaks payload validity into your error path and can let unsigned traffic through.
+2. **Acknowledge fast (return 2xx within ≤ 5 s).** Persist the event, hand it off to a queue / `waitUntil` / background task, then return. The HTTP handler does NOT do business logic.
+3. **Idempotency by provider event ID.** Same event arriving twice (retries, replays) MUST be a no-op. Store the event ID with a unique index.
+
+### Reference Receiver (Next.js Route Handler)
+
+```ts
+// app/api/webhooks/[provider]/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import crypto from 'node:crypto';
+
+export const runtime = 'nodejs'; // crypto.timingSafeEqual + raw body
+export const dynamic = 'force-dynamic';
+
+const SECRET = process.env['WEBHOOK_SECRET']!;
+
+function verify(rawBody: string, signature: string | null): boolean {
+  if (!signature) return false;
+  const expected = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
+  const a = Buffer.from(signature);
+  const b = Buffer.from(expected);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+export async function POST(req: NextRequest) {
+  // 1) RAW body — never req.json() before signature check
+  const rawBody = await req.text();
+  const signature = req.headers.get('x-signature');
+
+  if (!verify(rawBody, signature)) {
+    // Signature failure is the ONLY 4xx we return. Provider will not retry 401.
+    return new NextResponse('invalid signature', { status: 401 });
+  }
+
+  // 2) Parse AFTER signature passes
+  let event: { id: string; type: string; data: unknown };
+  try {
+    event = JSON.parse(rawBody);
+  } catch {
+    // Malformed body from an authenticated source = log + 200.
+    // Returning 400/500 here triggers infinite retries for a payload we cannot process anyway.
+    logger.warn({ rawBody }, 'webhook.parse_failed');
+    return new NextResponse('accepted', { status: 200 });
+  }
+
+  // 3) Idempotency — store-or-skip on event.id (unique index)
+  try {
+    await db.webhookEvent.create({
+      data: { id: event.id, type: event.type, payload: event, status: 'pending' },
+    });
+  } catch (e) {
+    if (isUniqueViolation(e)) {
+      // Duplicate delivery — already accepted. Ack and move on.
+      return new NextResponse('duplicate', { status: 200 });
+    }
+    // DB down: signal the provider to retry (this IS our fault).
+    logger.error({ err: e, eventId: event.id }, 'webhook.persist_failed');
+    return new NextResponse('storage error', { status: 503 });
+  }
+
+  // 4) Hand off async. NEVER await business logic here.
+  //    Options, in order of preference:
+  //      (a) push to a queue (BullMQ, Inngest, QStash, SQS)
+  //      (b) Vercel: `waitUntil(processEvent(event))` — runs after response
+  //      (c) trigger an internal API call with `fetch(..., { keepalive: true })`
+  await queue.publish('webhook.received', { eventId: event.id });
+
+  // 5) Always 2xx if we got this far. Provider stops retrying.
+  return NextResponse.json({ received: true });
+}
+```
+
+### The Async Processor (separate from the receiver)
+
+The processor is where downstream calls happen. **It must absorb its own failures** — never let them bubble back into the HTTP receiver:
+
+```ts
+// jobs/process-webhook.ts
+import CircuitBreaker from 'opossum';
+
+const downstream = new CircuitBreaker(callDownstreamAPI, {
+  timeout: 5_000,
+  errorThresholdPercentage: 50,
+  resetTimeout: 30_000,
+});
+
+export async function processWebhook(eventId: string) {
+  const event = await db.webhookEvent.findUniqueOrThrow({ where: { id: eventId } });
+  if (event.status === 'processed') return; // re-entrancy safety
+
+  try {
+    await downstream.fire(event.payload);
+    await db.webhookEvent.update({
+      where: { id: eventId },
+      data: { status: 'processed', processedAt: new Date() },
+    });
+  } catch (err) {
+    // Mark for retry from OUR side (queue redelivery + backoff),
+    // NOT from the provider's side. Provider already got 2xx.
+    await db.webhookEvent.update({
+      where: { id: eventId },
+      data: {
+        status: 'failed',
+        attempts: { increment: 1 },
+        lastError: serializeError(err),
+      },
+    });
+    logger.error({ err, eventId }, 'webhook.process_failed');
+    throw err; // queue will backoff + retry per OUR policy
+  }
+}
+```
+
+See `error-handling` Pattern 5 for circuit breaker tuning and Pattern 4 for retry+backoff.
+
+### FORBIDDEN — Webhook Handlers
+
+| Anti-pattern | Why it's lethal |
+|---|---|
+| `await req.json()` before signature verification | Signature is computed on the raw body bytes; framework re-serialization breaks it. Also accepts unsigned traffic into your parser. |
+| Doing the business logic inline in the handler | Provider timeout (≤ 5–30 s) → they retry while you're still processing → duplicate writes. |
+| Returning `5xx` on downstream failures | Provider retries forever, queue floods, your downstream gets even more load. Ack 2xx, retry from your side. |
+| Returning `4xx` on parse / business errors | Same retry storm. Only `4xx` justified is `401` for bad signature. |
+| No idempotency key | First retry creates a duplicate user / duplicate charge / duplicate message. |
+| Logging the full payload | PII / secrets in logs. Log the event ID + type; redact `data.*`. |
+| One `/api/webhooks` for all providers | Each provider has its own signature scheme, secrets, retry policy. Isolate per-route (`/api/webhooks/[provider]`). |
+| Trusting `X-Forwarded-For` for provider IP allowlist | Use signature verification, not IP allowlisting. Provider IPs rotate. |
+
+### Pre-Commit Checklist (Webhook Routes)
+
+- [ ] Signature verified on the **raw body** before any parsing
+- [ ] `timingSafeEqual` used for signature comparison (no `===`)
+- [ ] Provider event ID stored with a unique index → idempotency
+- [ ] Handler returns 2xx within ~1 s on the success path
+- [ ] Business logic delegated to queue / `waitUntil` / background task
+- [ ] Downstream calls wrapped in circuit breaker + retry+backoff
+- [ ] Logs include `eventId` + `provider` + `type`; payload `data` redacted
+- [ ] Tested: duplicate delivery → 200 (no duplicate side-effect)
+- [ ] Tested: invalid signature → 401, never reaches the parser
+
 ## Metadata
 
 ```tsx
@@ -227,3 +444,7 @@ export async function createCheckout(priceId: string) {
 6. **`NEXT_PUBLIC_` with API keys, secrets, or tokens** — secrets leak to browser bundle
 7. **Calling external APIs from client components** — use Route Handlers as proxy
 8. **`process.env['SECRET']` in `'use client'` files** — only `NEXT_PUBLIC_*` vars work client-side
+9. **Mixing `[id]` / `[userId]` / `[someId]` as siblings of the same parent dir** — runtime crash; `next build` does NOT catch it. Run `bun run routes:check` (see "Dynamic Route Slug Consistency")
+10. **Webhook business logic inline in the Route Handler** — ack 2xx fast, process async (see "Webhook Handler — Critical Path")
+11. **Skipping signature verification or parsing JSON before verifying** — always verify the raw body first
+12. **Returning 5xx from a webhook on a downstream failure** — triggers provider retry storms; ack 2xx and retry from your side