hack/tools/scripts/llm-key-hunter/results/_cache/content/cat-hype-age_ground-wire.json

{"repo": "cat-hype-age/ground-wire", "files": {"jobs/codex-kitchen-diverse20/officeqa-uid0176__YXxZjPE/agent/.tmp/plugins/plugins/vercel/vercel.md": {"1c68cb6d2563ee5d439e4387f93da5ce8b6769c2": {"t": 1786068573.283942, "n": 51368, "h": "4fdb907f3b9bfeab", "c": "# Vercel Ecosystem — Relational Knowledge Graph (as of Mar 4, 2026)\n\n> This document is the master reference for understanding the entire Vercel ecosystem.\n> It maps every product, library, CLI, API, and service — how they relate, when to use each,\n> and which bundled skills provide deeper guidance.\n\n---\n\n## Legend\n\n- **[PRODUCT]** — A Vercel product or service\n- **→ depends on** — Runtime or build-time dependency\n- **↔ integrates with** — Bidirectional integration\n- **⇢ alternative to** — Can substitute for\n- **⊃ contains** — Parent/child relationship\n- **⤳ skill:** — Link to a bundled skill for detailed guidance\n- **📖 docs:** — Link to official documentation\n\n---\n\n## 1. Core Platform\n\n```\nVERCEL PLATFORM                            📖 docs: https://vercel.com/docs\n├── Deployment Engine (CI/CD, Preview URLs, Production)\n│   → Git Provider (GitHub, GitLab, Bitbucket)\n│   → Build System (Turbopack or framework-native)\n│   ↔ Vercel CLI\n│   ↔ Vercel REST API / @vercel/sdk\n│   ⤳ skill: vercel-cli\n│   ⤳ skill: deployments-cicd\n│\n├── Edge Network (Global CDN, ~300ms propagation)\n│   ⊃ Edge Functions (V8 isolates, Web Standard APIs)\n│   ⊃ Serverless Functions (Node.js, Python, Go, Ruby)\n│   ⊃ Fluid Compute (unified execution model)\n│   ⊃ Routing Middleware (request interception before cache, any framework)\n│   ⊃ Runtime Cache (per-region key-value, tag-based invalidation)\n│   ⊃ Cron Jobs (scheduled function invocation → see § Functions decision matrix)\n│   ⤳ skill: cron-jobs\n│   ⤳ skill: vercel-functions\n│   ⤳ skill: routing-middleware\n│   ⤳ skill: runtime-cache\n│\n├── Services API (multiple services in one project)\n│   ⊃ experimentalServices in vercel.json\n│   ⊃ Multiple backends and frontends deployed to the same domain\n│   → Deployment Engine (services deployed as one application)\n│   ↔ Vercel CLI (vercel dev auto-detects and runs all services)\n│   ⤳ skill: vercel-services  📖 docs: https://vercel.com/docs/services\n│\n├── Domains & DNS\n│   → Deployment Engine\n│   ↔ Vercel Firewall\n│   ⤳ skill: vercel-cli  (vercel domains, vercel dns, vercel certs)\n│\n├── Environment Variables                        ⤳ skill: env-vars\n│   → Deployment Engine\n│   ↔ Vercel CLI (vercel env)\n│   ↔ Marketplace Integrations (auto-provisioned)\n│   ⤳ skill:bootstrap\n│\n├── Secure Compute (isolated infrastructure for compliance workloads)\n│   → Deployment Engine (opt-in per project)\n│   ↔ Vercel Functions (dedicated execution environment)\n│   ↔ Vercel Firewall (network-level isolation)\n│\n├── OIDC Federation (deploy without long-lived tokens)\n│   → Deployment Engine (CI/CD token exchange)\n│   ↔ Teams & Access Control (identity-based auth)\n│   ↔ GitHub Actions, GitLab CI (short-lived OIDC tokens)\n│\n├── Preview Comments (collaborate on preview deployments)\n│   → Deployment Engine (preview URLs)\n│   ↔ Vercel Toolbar (embedded comment UI)\n│   ↔ Teams & Access Control (team-scoped threads)\n│\n├── Vercel Toolbar (developer toolbar for preview deployments)\n│   → Deployment Engine (preview URLs)\n│   ↔ Preview Comments (inline annotation)\n│   ↔ Vercel Analytics (performance overlay)\n│   ↔ Edge Config (feature flag toggles)\n│\n├── Vercel Templates (starter kits and example repos)\n│   → Deployment Engine (one-click deploy)\n│   ↔ Vercel Marketplace (pre-configured integrations)\n│   ↔ Next.js, AI SDK, v0 (framework starters)\n│   ⊃ next-forge (production SaaS monorepo starter)    ⤳ skill: next-forge\n│       → Turborepo, Clerk, Prisma/Neon, Stripe, Resend, shadcn/ui, Sentry, PostHog\n│       → 7 apps (app, web, api, email, docs, studio, storybook)\n│       → 20 @repo/* workspace packages\n│\n├── Vercel Queues (durable event streaming)\n│   ⊃ Topics, consumer groups, delayed delivery\n│   ⊃ At-least-once delivery, 3-AZ durability\n│   → Vercel Functions (consumers run as functions)\n│   ↔ Workflow DevKit (Queues powers WDK under the hood)\n│   ⤳ skill: vercel-queues\n│\n├── Vercel Flags (feature flags platform)\n│   ⊃ Unified dashboard, Flags Explorer\n│   ⊃ Gradual rollouts, A/B testing\n│   ⊃ Provider adapters (LaunchDarkly, Statsig, Hypertune)\n│   ↔ Edge Config (flag storage at the edge)\n│   ↔ Vercel Toolbar (flag toggles in preview)\n│   ⤳ skill: vercel-flags\n│\n└── Teams & Access Control\n    ↔ Vercel REST API\n    ↔ Vercel Dashboard\n```\n\n---\n\n## 2. Frameworks\n\n```\nNEXT.JS (v16+)                           ⤳ skill: nextjs  📖 docs: https://nextjs.org/docs\n├── App Router (file-system routing)\n│   ⊃ Server Components (default, zero client JS)\n│   ⊃ Client Components ('use client')\n│   ⊃ Server Actions / Server Functions ('use server')\n│   ⊃ Route Handlers (API endpoints)\n│   ⊃ Middleware → renamed to Proxy in v16\n│   ⊃ Cache Components ('use cache')\n│   ⊃ Layouts, Loading, Error boundaries\n│   ⊃ Parallel & Intercepting Routes\n│   ⊃ Dynamic Segments ([id], [...slug], [[...slug]])\n│\n├── Rendering Strategies\n│   ⊃ SSR (Server-Side Rendering)\n│   ⊃ SSG (Static Site Generation)\n│   ⊃ ISR (Incremental Static Regeneration)\n│   ⊃ PPR (Partial Prerendering) → evolving to Cache Components\n│   ⊃ Streaming (React Suspense boundaries)\n│\n├── Build System\n│   → Turbopack (default bundler in v16)\n│   → Webpack (legacy, still supported)\n│\n├── Key Integrations\n│   ↔ Vercel AI SDK (chat UIs, streaming, tool calling)\n│   ↔ Vercel Analytics / Speed Insights           ⤳ skill: observability\n│   ↔ Vercel Image Optimization (next/image)      ⤳ skill: nextjs\n│   ↔ Satori / @vercel/og (dynamic OG images)     ⤳ skill: satori\n│   ↔ Vercel Font Optimization (next/font)\n│   ↔ Vercel Functions (automatic from route handlers / server actions)\n│\n└── Deployment\n    → Vercel Platform (optimized, zero-config)\n    ↔ Vercel CLI (vercel dev, vercel build)\n\nSHADCN/UI                                ⤳ skill: shadcn  📖 docs: https://ui.shadcn.com\n├── CLI (npx shadcn@latest init/add/build/search)\n│   ⊃ Component source code copied to your project\n│   ⊃ Radix UI primitives + Tailwind CSS\n│   ⊃ CSS variable theming (oklch)\n│   ⊃ Custom registry system (build + host your own)\n│   ⊃ Namespaced registries (@v0, @acme, @ai-elements)\n│\n├── Key Patterns\n│   ⊃ cn() utility (clsx + tailwind-merge)\n│   ⊃ Dark mode via className=\"dark\" on <html>\n│   ⊃ TooltipProvider at layout root\n│   ⊃ Components are source code — fully customizable\n│\n└── Integrations\n    ↔ Next.js (primary framework)\n    ↔ AI Elements (AI components built on shadcn)     ⤳ skill: ai-elements\n    ↔ v0 (generates shadcn/ui components)             ⤳ skill: v0-dev\n    ↔ Vite, Remix, Astro, Laravel (all supported)\n\nOTHER SUPPORTED FRAMEWORKS\n├── Astro          ↔ Vercel Adapter\n├── SvelteKit      ↔ Vercel Adapter\n├── Nuxt           ↔ Vercel Adapter\n├── Remix          ↔ Vercel Adapter\n├── Angular        ↔ Vercel Adapter\n├── Solid          ↔ Vercel Adapter\n└── Static HTML/JS → Direct deploy\n```\n\n---\n\n## 3. AI Products\n\n```\nAI SDK (v6, TypeScript)                    ⤳ skill: ai-sdk  📖 docs: https://sdk.vercel.ai/docs\n├── Core\n│   ⊃ generateText / streamText\n│   ⊃ generateText / streamText with Output.object() (structured output)\n│   ⊃ generateImage / editImage (image-only models)\n│   ⊃ Image generation via multimodal LLMs (generateText → result.files)\n│   ⊃ embed / embedMany (vector embeddings)\n│   ⊃ rerank (relevance reordering)\n│   ⊃ Language Model Middleware (RAG, guardrails)\n│   ⊃ Tool Calling (inputSchema/outputSchema, MCP-aligned)\n│   ⊃ Dynamic Tools (runtime-defined, MCP integration)\n│   ⊃ Agent class (agent.generate / agent.stream, stopWhen, prepareStep)\n│   ⊃ Subagents\n│   ⊃ Tool Execution Approval\n│   ⊃ DevTools (npx @ai-sdk/devtools)\n│\n├── UI Layer (@ai-sdk/react, @ai-sdk/svelte, @ai-sdk/vue)\n│   ⊃ useChat (chat interface hook)\n│   ⊃ useCompletion (text completion hook)\n│   ⊃ useObject (structured streaming hook)\n│   ⊃ UIMessage / ModelMessage types\n│   ↔ AI Elements (pre-built chat UI components)       ⤳ skill: ai-elements\n│\n├── AI Elements (ai-elements) — MANDATORY UI FOR ALL AI TEXT  ⤳ skill: ai-elements\n│   ⊃ 40+ React components for AI interfaces\n│   ⊃ Message (chat with useChat), MessageResponse (any AI markdown)\n│   ⊃ Conversation, Tool, Reasoning, CodeBlock\n│   ⊃ Built on shadcn/ui (custom registry)\n│   ⊃ Handles UIMessage parts, streaming, markdown\n│   ⊃ MessageResponse = universal renderer for AI text (chat, workflows, reports, notifications)\n│   ⊃ Never render AI text as raw {text} or <p>{content}</p> — use AI Elements\n│   → AI SDK UI hooks (useChat, useCompletion)\n│   → shadcn/ui (component primitives)                 ⤳ skill: shadcn\n│\n│\n├── MCP Integration (@ai-sdk/mcp)\n│   ⊃ MCP Client (connect to any MCP server)\n│   ⊃ OAuth authentication for remote MCP servers\n│   ⊃ Resources, Prompts, Elicitation\n│   ⊃ mcp-to-ai-sdk CLI (static tool generation for security)\n│\n├── Providers (Global Provider System: \"provider/model\")\n│   ⊃ @ai-sdk/openai (GPT-5.x, o-series)\n│   ⊃ @ai-sdk/anthropic (Claude 4.x)\n│   ⊃ @ai-sdk/google (Gemini)\n│   ⊃ @ai-sdk/amazon-bedrock\n│   ⊃ @ai-sdk/azure\n│   ⊃ @ai-sdk/mistral\n│   ⊃ @ai-sdk/cohere\n│   ⊃ @ai-sdk/xai (Grok)\n│   ⊃ @ai-sdk/deepseek\n│   ⊃ @ai-sdk/gateway (Vercel AI Gateway routing)\n│   └── ... 20+ providers\n│\n├── Streaming Protocol\n│   ⊃ SSE-based (Server-Sent Events)\n│   → Vercel Functions (streaming support)\n│   ↔ Next.js Route Handlers / Server Actions\n│   ↔ AI Elements (render streaming responses)          ⤳ skill: ai-elements\n│\n└── Key Patterns\n    ↔ Next.js (chat apps, AI features in web apps)\n    ↔ Workflow DevKit (durable agents)\n    ↔ AI Gateway (model routing, cost tracking)\n    ↔ Generation Persistence (IDs, URLs, cost tracking) ⤳ skill: ai-generation-persistence\n    ↔ v0 (AI-generated UI components)\n    ↔ AI Elements (production chat UI components)      ⤳ skill: ai-elements\n    ↔ shadcn/ui (component foundation)                 ⤳ skill: shadcn\n\nAI GATEWAY                                 ⤳ skill: ai-gateway  📖 docs: https://vercel.com/docs/ai-gateway\n├── Unified API (\"creator/model-name\" format)\n│   → @ai-sdk/gateway package\n│   ↔ AI SDK (automatic when using model strings)\n│\n├── Authentication\n│   ⊃ OIDC (default — auto-provisioned via `vercel env pull`)\n│   ⊃ AI_GATEWAY_API_KEY (alternative — manual key)\n│   ⊃ VERCEL_OIDC_TOKEN (short-lived JWT, auto-refreshed on deploy)\n│   → @vercel/oidc (reads VERCEL_OIDC_TOKEN from env)\n│   → Vercel CLI (`vercel env pull` provisions OIDC token)\n│\n├── Features\n│   ⊃ Provider Routing (order, only, fallback models)\n│   ⊃ Automatic Retries & Failover\n│   ⊃ Cost Tracking & Usage Attribution (tags, user tracking)\n│   ⊃ <20ms routing latency\n│   ⊃ Bring Your Own Key (0% markup)\n│   ⊃ Built-in Observability\n│\n├── Image Generation (gateway-native)\n│   ⊃ Multimodal LLMs: model: 'google/gemini-3.1-flash-image-preview' + generateText → result.files\n│   ⊃ Image-only models: experimental_generateImage (Imagen 4.0, Flux 2, Grok Imagine)\n│   ⊃ Default model: google/gemini-3.1-flash-image-preview\n│   ⊃ DALL-E, gemini-2.x image models are outdated — use Gemini 3.1 Flash Image Preview\n│\n├── Supported Providers\n│   ⊃ OpenAI, Anthropic, Google, Meta, xAI, Mistral\n│   ⊃ DeepSeek, Amazon Bedrock, Cohere, Perplexity, Alibaba\n│   └── 100+ models total\n│\n└── Multimodal\n    ⊃ Text, Image, Video generation\n    ↔ AI SDK (unified interface)\n\nWORKFLOW DEVKIT (WDK)                      ⤳ skill: workflow  📖 docs: https://vercel.com/docs/workflow\n├── Core Concepts\n│   ⊃ 'use workflow' directive\n│   ⊃ 'use step' directive\n│   ⊃ Durable execution (survives deploys, crashes)\n│   ⊃ Deterministic replay\n│   ⊃ Pause/resume (minutes to months)\n│   ⊃ Hooks (defineHook → human-in-the-loop approval, pause/resume)\n│   ⊃ AI Gateway OIDC required (vercel link + vercel env pull before dev)\n│\n├── Worlds (Execution Environments)\n│   ⊃ Local World (JSON files on disk)\n│   ⊃ Vercel World (managed, zero-config on Vercel)\n│   ⊃ Self-hosted (Postgres, Redis, custom)\n│\n├── AI Integration\n│   ⊃ DurableAgent (@workflow/ai/agent)\n│   → AI SDK Agent class (wrapped with durability)\n│   → AI SDK tool calling (each tool = retryable step)\n│   → AI Gateway (OIDC auth for model strings in workflow steps)\n│\n├── Key Properties\n│   ⊃ Open source, no vendor lock-in\n│   ⊃ TypeScript-native (async/await, no YAML)\n│   ⊃ Observable (step-level visibility)\n│   ⊃ Retryable (automatic retry on failure)\n│\n└── Integrations\n    ↔ AI SDK 6 (DurableAgent)\n    ↔ Vercel Functions (automatic step isolation)\n    ↔ Next.js (API routes as workflow endpoints)\n\nv0 (AI Development Agent)                  ⤳ skill: v0-dev  📖 docs: https://v0.dev/docs\n├── Capabilities\n│   ⊃ Natural language → production React/Next.js code\n│   ⊃ Visual input (Figma, screenshots, sketches)\n│   ⊃ Multi-framework output (React, Vue, Svelte, HTML)\n│   ⊃ Agentic intelligence (research, plan, debug, iterate)\n│\n├── Integration Features\n│   ⊃ GitHub Integration (branches, PRs, deploy on merge)\n│   ⊃ One-click Vercel deployment\n│   ⊃ Environment variable import from Vercel\n│   ⊃ shadcn/ui + Tailwind CSS defaults\n│\n└── Ecosystem Position\n    → Next.js (primary output framework)\n    → Vercel Platform (deployment target)\n    ↔ AI SDK (AI features in generated apps)\n    ↔ Vercel Marketplace (integrations in generated apps)\n\nCHAT SDK (TypeScript)                       ⤳ skill: chat-sdk  📖 docs: https://chat-sdk.dev\n├── Core\n│   ⊃ Chat class (event routing, adapter coordination)\n│   ⊃ Thread & Message (normalized cross-platform models)\n│   ⊃ Postable interface (shared by Thread and Channel: post, postEphemeral, mentionUser, startTyping)\n│   ⊃ openDM / channel (out-of-thread message routing)\n│   ⊃ Serialization (registerSingleton, reviver for JSON deserialization)\n│   ⊃ Cards (JSX → Slack Block Kit, Teams Adaptive Cards, Discord Embeds)\n│   ⊃ Modals (Slack-only form dialogs)\n│   ⊃ Streaming (native on Slack, post+edit fallback elsewhere)\n│   ⊃ Emoji system (cross-platform placeholders)\n│\n├── Platform Adapters\n│   ⊃ @chat-adapter/slack (single + multi-workspace, OAuth, native streaming)\n│   ⊃ @chat-adapter/teams (Microsoft Teams, Adaptive Cards)\n│   ⊃ @chat-adapter/discord (HTTP Interactions + Gateway, Ed25519)\n│   ⊃ @chat-adapter/telegram (Telegram Bot API, webhook verification)\n│   ⊃ @chat-adapter/gchat (Google Chat, Spaces)\n│   ⊃ @chat-adapter/github (Issues/PRs as threads)\n│   ⊃ @chat-adapter/linear (Issue comment threads)\n│\n├── State Adapters\n│   ⊃ @chat-adapter/state-redis (production, distributed locking)\n│   ⊃ @chat-adapter/state-ioredis (Redis Cluster/Sentinel)\n│   ⊃ @chat-adapter/state-memory (dev/testing only)\n│\n├── Event Handlers\n│   ⊃ onNewMention, onSubscribedMessage, onNewMessage\n│   ⊃ onReaction, onAction, onSlashCommand\n│   ⊃ onModalSubmit, onModalClose\n│   ⊃ onAssistantThreadStarted, onAssistantContextChanged\n│   ⊃ onAppHomeOpened\n│   ⊃ onMemberJoinedChannel\n│\n├── Key Patterns\n│   ↔ AI SDK (streaming AI responses via thread.post(textStream))\n│   ↔ Workflow DevKit (registerSingleton/reviver for durable serialization)\n│   ↔ Vercel Functions (webhook handlers, waitUntil)\n│   ↔ Next.js (API routes for webhooks)\n│   ↔ Upstash Redis (state adapter backend)\n│\n└── Testing\n    ⊃ Replay framework (record real webhooks, replay in tests)\n    ⊃ Test context factories (createSlackTestContext, etc.)\n    ⊃ Assertion helpers (expectValidMention, expectSentMessage)\n\nVERCEL AGENT                               ⤳ skill: vercel-agent  📖 docs: https://vercel.com/docs/workflow/agent\n├── Capabilities\n│   ⊃ Automated code review (PR analysis, security, logic errors)\n│   ⊃ Incident investigation (anomaly debugging)\n│   ⊃ SDK installation assistance\n│   ⊃ Vercel Sandbox (secure patch validation)   ⤳ skill: vercel-sandbox\n│\n└── Integrations\n    ↔ GitHub (PR triggers, @vercel mentions)\n    ↔ Vercel Sandbox (isolated code execution)\n    ↔ AI SDK (underlying AI capabilities)\n```\n\n---\n\n## 4. Build Tools\n\n```\nTURBOREPO                                  ⤳ skill: turborepo  📖 docs: https://turbo.build/repo/docs\n├── Purpose: Monorepo build orchestration\n│   ⊃ Task caching (local + remote)\n│   ⊃ Parallel execution (all cores)\n│   ⊃ Incremental builds (content-aware hashing)\n│   ⊃ --affected flag (changed packages only)\n│   ⊃ Pruned subsets (deploy only what's needed)\n│   ⊃ Rust-powered core\n│\n├── Remote Caching\n│   → Vercel Account (free tier available)\n│   ↔ CI/CD pipelines (shared cache across machines)\n│\n├── Conformance (code quality + best-practice checks for monorepos)\n│   ⊃ Automated rule enforcement (ESLint, TypeScript, import boundaries)\n│   ↔ Turborepo (runs as part of task pipeline)\n│   ↔ Vercel Platform (enforced on deploy)\n│   ⤳ skill: turborepo  (Conformance is configured within Turborepo)\n│\n└── Integrations\n    ↔ Next.js (monorepo with multiple Next.js apps)\n    ↔ Vercel Platform (auto-detected, optimized builds)\n    ↔ Turbopack (per-app bundling)\n\nTURBOPACK                                  ⤳ skill: turbopack  📖 docs: https://turbo.build/pack/docs\n├── Purpose: JavaScript/TypeScript bundler\n│   ⊃ Instant HMR (doesn't degrade with app size)\n│   ⊃ Multi-environment builds (Browser, Server, Edge, SSR, RSC)\n│   ⊃ TypeScript, JSX, CSS, CSS Modules, WebAssembly\n│   ⊃ React Server Components (native support)\n│\n├── Status: Default bundler in Next.js 16\n│   → Next.js (top-level turbopack config)\n│   ⇢ alternative to: Webpack\n│\n└── Architecture\n    ⊃ Rust-powered\n    ⊃ Incremental computation engine\n    ⊃ Lives in the Next.js monorepo\n```\n\nAGENT BROWSER                              ⤳ skill: agent-browser\n├── Purpose: Browser automation for dev-server testing\n│   ⊃ Snapshot-driven interaction with localhost\n│   ⊃ Works with next dev, vite, nuxt dev, vercel dev\n│\n└── Use When: Verifying UI behavior, form testing, e2e workflows\n\nAGENT BROWSER VERIFY                       ⤳ skill: agent-browser-verify\n├── Purpose: Automated dev-server verification checklist\n│   ⊃ Triggers on dev-server start (next dev, vite, etc.)\n│   ⊃ Runs visual gut-check: page loads, no errors, key UI renders\n│\n└── Use When: After starting a dev server, before continuing development\n\nVERIFICATION                                   ⤳ skill: verification\n├── Purpose: Full-story verification orchestrator\n│   ⊃ Infers the user story from recent edits and project structure\n│   ⊃ Verifies end-to-end: browser → API → data → response\n│   ⊃ Coordinates agent-browser-verify, investigation-mode, observability\n│\n└── Use When: Dev server starts, user says \"something's off\", or verifying a feature works end-to-end\n\nREACT BEST PRACTICES                       ⤳ skill: react-best-practices\n├── Purpose: TSX/JSX quality review checklist\n│   ⊃ Component structure, hooks, a11y, performance, TypeScript\n│   ⊃ Triggers when editing component files\n│\n└── Use When: After editing multiple TSX components, before shipping\n\nSWR (v2, React Hooks)                      ⤳ skill: swr  📖 docs: https://swr.vercel.app\n├── Purpose: Client-side data fetching with stale-while-revalidate caching\n│   ⊃ useSWR (data fetching with auto-revalidation)\n│   ⊃ useSWRMutation (remote mutations, optimistic UI)\n│   ⊃ useSWRInfinite (pagination & infinite loading)\n│   ⊃ SWRConfig (global configuration provider)\n│\n├── Key Features\n│   ⊃ Request deduplication\n│   ⊃ Revalidation on focus, reconnect, interval\n│   ⊃ Built-in cache with shared keys\n│   ⊃ Middleware support\n│\n└── Integrations\n    ↔ Next.js (App Router & Pages Router)\n    ↔ React (any React framework)\n\nNCC (Node.js Compiler Collection)          ⤳ skill: ncc  📖 docs: https://github.com/vercel/ncc\n├── Purpose: Compile Node.js modules into a single file with all dependencies\n│   ⊃ Serverless function bundling\n│   ⊃ CLI tool distribution\n│   ⊃ GitHub Actions bundling\n│   ⊃ TypeScript compilation (uses project tsconfig.json)\n│   ⊃ External module exclusion\n│\n└── Use When: Single-file deployment, reducing node_modules, bundling serverless functions\n\nMICRO (HTTP Microservices)                 ⤳ skill: micro  📖 docs: https://github.com/vercel/micro\n├── Purpose: Lightweight async HTTP microservices framework\n│   ⊃ Single-endpoint HTTP servers\n│   ⊃ JSON/text/buffer body parsing\n│   ⊃ Composable handler middleware\n│   ⊃ micro-dev for hot-reloading development\n│\n└── Use When: Minimal HTTP services, single-purpose API endpoints\n\nGEIST (Font Family)                        ⤳ skill: geist  📖 docs: https://github.com/vercel/geist-font\n├── Purpose: Vercel's open-source font family for Next.js\n│   ⊃ Geist Sans (modern sans-serif for UI)\n│   ⊃ Geist Mono (monospace for code)\n│   ⊃ next/font integration (zero layout shift)\n│   ⊃ CSS variables (--font-geist-sans, --font-geist-mono)\n│   ⊃ Variable font (all weights 100–900)\n│\n└── Use When: Typography setup in Next.js, Vercel design system styling\n\nGEISTDOCS (Documentation Template)         ⤳ skill: geistdocs  📖 docs: https://preview.geistdocs.com/docs\n├── Purpose: Production-ready documentation template for Vercel microsites\n│   ⊃ Next.js 16 + Fumadocs framework\n│   ⊃ MDX authoring with auto-routing (content/docs/)\n│   ⊃ AI-powered chat (Ask AI, llms.txt, Open in Chat)\n│   ⊃ i18n, feedback widget, RSS, Edit on GitHub\n│   ⊃ geistdocs.tsx config (Logo, nav, title, prompt, translations)\n│\n└── Use When: Building documentation sites, docs microsites, developer docs\n\n---\n\n## 5. Storage & Data\n\n```\nVERCEL BLOB (active, first-party)          ⤳ skill: vercel-storage  📖 docs: https://vercel.com/docs/storage/vercel-blob\n├── Purpose: File storage for unstructured data\n│   ⊃ Client uploads (up to 5 TB)\n│   ⊃ Conditional gets with ETags\n│   ⊃ @vercel/blob package\n│\n└── Use When: Media files, user uploads, large assets\n\nVERCEL EDGE CONFIG (active, first-party)   ⤳ skill: vercel-storage  📖 docs: https://vercel.com/docs/storage/edge-config\n├── Purpose: Global low-latency key-value for config\n│   ⊃ Feature flags\n│   ⊃ A/B testing configuration\n│   ⊃ Dynamic routing rules\n│   ⊃ @vercel/edge-config package (supports Next.js 16 cacheComponents)\n│\n└── Use When: Config that must be read at the edge instantly\n\nMARKETPLACE STORAGE (partner-provided)     ⤳ skill: vercel-storage\n├── Neon Postgres (replaces @vercel/postgres)\n│   ⊃ @neondatabase/serverless\n│   ⊃ Branching, auto-scaling\n│   ⇢ alternative to: @vercel/postgres (sunset)\n│\n├── Upstash Redis (replaces @vercel/kv)\n│   ⊃ @upstash/redis\n│   ⊃ Same Vercel billing integration\n│   ⇢ alternative to: @vercel/kv (sunset)\n│\n└── Other: MongoDB, PlanetScale, Supabase, etc.\n    ↔ Vercel Marketplace (one-click install, auto env vars)\n```\n\n**IMPORTANT**: `@vercel/postgres` and `@vercel/kv` are **sunset**. Use Neon and Upstash respectively.\n\n---\n\n## 6. Security\n\n```\nVERCEL FIREWALL                            ⤳ skill: vercel-firewall  📖 docs: https://vercel.com/docs/security/vercel-firewall\n├── DDoS Protection (automatic, all plans)\n│   ⊃ Layer 3/4 mitigation\n│   ⊃ Layer 7 protection\n│   ⊃ 40x faster with stream processing\n│\n├── Web Application Firewall (WAF)\n│   ⊃ Custom rules engine (path, user-agent, IP, geo, JA4)\n│   ⊃ Framework-aware rules (no regex needed)\n│   ⊃ Managed rulesets (OWASP Top 10, Enterprise)\n│   ⊃ Rate limiting\n│   ⊃ Bot Filter (public beta, all plans)\n│   ⊃ Attack Challenge Mode\n│   ⊃ Persistent Actions (block repeat offenders)\n│   ⊃ Firewall API (programmatic control)\n│   ⊃ 300ms global propagation\n│\n└── Integrations\n    ↔ Edge Network (embedded in request lifecycle)\n    ↔ Vercel Observability (linked logs)\n    ↔ Vercel REST API (Firewall API)\n\nSIGN IN WITH VERCEL                        ⤳ skill: sign-in-with-vercel  📖 docs: https://vercel.com/docs/security/sign-in-with-vercel\n├── OAuth 2.0 / OIDC Identity Provider\n│   ⊃ Authorization Code flow\n│   ⊃ ID tokens with user profile claims\n│   ⊃ Access tokens for Vercel API calls\n│\n└── Integrations\n    ↔ Teams & Access Control (team-scoped auth)\n    ↔ Vercel REST API (token exchange)\n    ↔ Next.js (auth route handlers)\n\nAUTHENTICATION INTEGRATIONS                ⤳ skill: auth\n├── Clerk (native Vercel Marketplace)\n│   ⊃ Auto-provisioned env vars\n│   ⊃ Middleware auth patterns\n│   ⊃ Pre-built UI components\n│\n├── Descope (Vercel Marketplace)\n│   ⊃ Passwordless / social login flows\n│   ⊃ Visual flow builder\n│\n├── Auth0\n│   ⊃ Enterprise SSO / SAML\n│   ⊃ Multi-tenant identity\n│\n└── Integrations\n    ↔ Vercel Marketplace (provisioning)\n    ↔ Next.js Middleware (route protection)\n    ↔ Sign in with Vercel (Vercel OAuth)\n```\n\n---\n\n## 7. Observability\n\n```\nVERCEL OBSERVABILITY                        ⤳ skill: observability  📖 docs: https://vercel.com/docs/analytics\n├── Web Analytics\n│   ⊃ First-party, privacy-friendly\n│   ⊃ Custom events (Pro/Enterprise)\n│   ⊃ UTM parameters (Analytics Plus)\n│   ↔ Next.js (@vercel/analytics)\n│\n├── Speed Insights\n│   ⊃ Real user performance data\n│   ⊃ Core Web Vitals\n│   ↔ Next.js (@vercel/speed-insights)\n│\n├── Monitoring & Logs\n│   ⊃ Real-time infrastructure logs\n│   ⊃ Function runtime logs\n│   ⊃ Custom queries and visualizations\n│   ⤳ skill: investigation-mode\n│\n├── Vercel Drains (export observability data)\n│   ⊃ OpenTelemetry-compatible traces\n│   ⊃ Web analytics events\n│   ⊃ Speed Insights metrics\n│   → Datadog, Honeycomb, Grafana Tempo, New Relic\n│\n└── Integrations\n    ↔ Vercel Firewall (security event logs)\n    ↔ Vercel Functions (automatic tracing)\n    ↔ Next.js (automatic instrumentation)\n```\n\n---\n\n## 8. CLI & API\n\n```\nVERCEL CLI (vercel / vc)                   ⤳ skill: vercel-cli  📖 docs: https://vercel.com/docs/cli\n├── Deployment\n│   ⊃ vercel / vercel deploy (preview deployment)\n│   ⊃ vercel --prod (production deployment)\n│   ⊃ vercel build (local build)\n│   ⊃ vercel deploy --prebuilt (deploy build output only)\n│   ⊃ vercel promote / vercel rollback\n│\n├── Development\n│   ⊃ vercel dev (local dev server)\n│   ⊃ vercel link (connect to Vercel project)\n│   ⊃ vercel pull (pull env vars and project settings)\n│\n├── Environment Variables\n│   ⊃ vercel env ls / add / rm / pull\n│   ⊃ Branch-scoped variables\n│   ⊃ Sensitive variables (write-only)\n│\n├── Marketplace Integrations\n│   ⊃ vercel integration add (install integration)\n│   ⊃ vercel integration list (list installed)\n│   ⊃ vercel integration open (open dashboard)\n│   ⊃ vercel integration remove (uninstall)\n│\n├── Other\n│   ⊃ vercel logs (view function logs)\n│   ⊃ vercel inspect (deployment details)\n│   ⊃ vercel domains (manage domains)\n│   ⊃ vercel certs (SSL certificates)\n│   ⊃ vercel dns (DNS records)\n│   ⊃ vercel teams (team management)\n│\n└── CI/CD Integration\n    ⊃ VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID\n    ↔ Any CI provider (GitHub Actions, Azure DevOps, etc.)\n\nVERCEL MCP SERVER (Official)                ⤳ skill: vercel-api  📖 docs: https://vercel.com/docs/mcp\n├── URL: https://mcp.vercel.com\n│   ⊃ Streamable HTTP transport\n│   ⊃ OAuth 2.1 authentication (automatic)\n│   ⊃ Read-only in initial release (Beta)\n│\n├── MCP Tools\n│   ⊃ Search & navigate Vercel / Next.js / AI SDK docs\n│   ⊃ List & inspect projects and deployments\n│   ⊃ Query build logs and function invocation logs\n│   ⊃ List domains and environment variables\n│   ⊃ View team members and settings\n│\n├── Supported AI Clients\n│   ⊃ Codex, Cursor, VS Code (reviewed and approved clients)\n│\n└── Relationship to REST API\n    → Uses Vercel REST API under the hood\n    ↔ AI SDK MCP Client (@ai-sdk/mcp)\n\nVERCEL REST API / @vercel/sdk               ⤳ skill: vercel-api  📖 docs: https://vercel.com/docs/rest-api\n├── Endpoint Categories\n│   ⊃ /v1/deployments — Create, list, inspect, cancel\n│   ⊃ /v1/projects — CRUD, environment variables, domains\n│   ⊃ /v1/teams — Members, billing, settings\n│   ⊃ /v1/domains — Register, configure, transfer\n│   ⊃ /v1/dns — Record management\n│   ⊃ /v1/certs — SSL certificate management\n│   ⊃ /v1/secrets — Secret management\n│   ⊃ /v1/integrations — Marketplace integration management\n│   ⊃ /v1/edge-config — Edge Config management\n│   ⊃ /v1/firewall — WAF rule management\n│\n├── SDK (@vercel/sdk)\n│   ⊃ TypeScript SDK for all API endpoints\n│   ⊃ vercel.deployments, vercel.projects, etc.\n│\n└── Authentication\n    ⊃ Bearer Token (personal or team)\n    ⊃ OAuth (for integrations)\n```\n\n---\n\n## 9. Marketplace\n\n```\nVERCEL MARKETPLACE                          ⤳ skill: marketplace  📖 docs: https://vercel.com/marketplace\n├── Categories\n│   ⊃ Databases (Neon, MongoDB, Supabase, PlanetScale)\n│   ⊃ CMS (Sanity, Contentful, Storyblok)      ⤳ skill: cms\n│   ⊃ Auth (Clerk, Auth0)\n│   ⊃ Payments (Stripe)                       ⤳ skill: payments\n│   ⊃ Email (Resend)                          ⤳ skill: email\n│   ⊃ Feature Flags (LaunchDarkly, Statsig)\n│   ⊃ AI Agents (CodeRabbit, Corridor, Sourcery, Parallel)\n│   ⊃ Storage (Upstash Redis, Cloudinary)\n│   ⊃ Monitoring (Datadog, Sentry)\n│\n├── Features\n│   ⊃ Unified billing\n│   ⊃ One-click install\n│   ⊃ Auto-provisioned environment variables\n│   ⊃ CLI management (vercel integration add/list/open/remove)\n│\n└── Integration\n    ↔ Vercel CLI (agent-friendly discovery)\n    ↔ Vercel REST API (programmatic management)\n    ↔ Environment Variables (auto-injected)\n```\n\n---\n\n## 10. Decision Matrix — When to Use What\n\n### Rendering Strategy\n| Need | Use | Why |\n|------|-----|-----|\n| Static content, rarely changes | SSG (`generateStaticParams`) | Fastest, cached at edge |\n| Static with periodic updates | ISR (`revalidate`) | Fresh enough, still fast |\n| Per-request dynamic data | SSR (Server Components) | Always fresh, streamed |\n| Mix of static shell + dynamic parts | Cache Components (`'use cache'`) | Best of both worlds |\n| Real-time interactive UI | Client Components | Full browser API access |\n\n### Data Mutations\n| Need | Use | Why |\n|------|-----|-----|\n| Form submissions, in-app mutations | Server Actions | Integrated with caching, progressive enhancement |\n| Public API, webhooks, large uploads | Route Handlers | REST semantics, streaming support |\n| Scheduled tasks | Cron Jobs + Serverless Functions | Reliable scheduling |\n\n### AI Features\n| Need | Use | Why |\n|------|-----|-----|\n| **Any AI feature (default)** | **AI Gateway** (`model: 'provider/model'`) | **Failover, cost tracking, observability — no provider API keys needed on Vercel** |\n| **Any streaming AI UI (default)** | **AI Elements** (`npx ai-elements`) + AI SDK `useChat` | **Handles UIMessage parts, streaming markdown, tool calls, reasoning — no manual rendering** |\n| **Any AI-generated text (mandatory)** | **AI Elements `<MessageResponse>`** | **Universal markdown renderer — never render AI text as raw `{text}`. Use for chat, workflows, reports, notifications** |\n| Chat interface | AI SDK `useChat` + `streamText` + AI Gateway + AI Elements | Streaming UI, provider-agnostic |\n| Chat UI components (messages, tools, reasoning) | AI Elements (`npx ai-elements`) | Pre-built, handles UIMessage parts |\n| Custom chat rendering (no AI Elements) | Manual `message.parts` iteration | Full control, see ⤳ skill: json-render |\n| Image generation (default) | AI Gateway `model: 'google/gemini-3.1-flash-image-preview'` + `generateText` → `result.files` | Multimodal LLM, best quality, gateway-native |\n| Image generation (image-only models) | `experimental_generateImage` (Imagen 4.0, Flux 2) | Only for dedicated image models, not multimodal LLMs |\n| Structured data extraction | AI SDK `generateText` + `Output.object()` + AI Gateway | Type-safe, schema-validated |\n| Multi-step agent | AI SDK `Agent` class + AI Gateway | Loop control, tool calling |\n| Production agent (must not lose state) | Workflow DevKit `DurableAgent` | Survives crashes, observable |\n| Provider-specific features (e.g., computer use) | Direct provider SDK (`@ai-sdk/anthropic`) | Only when gateway doesn't expose the feature |\n| Connect to external tools | AI SDK MCP Client | Standard protocol, OAuth |\n| Agent needs live Vercel state | Vercel MCP Server | Read projects, deployments, logs via MCP |\n| Multi-platform chat bot (Slack, Teams, Discord, Telegram, etc.) | Chat SDK (`chat` + `@chat-adapter/*`) | Single codebase, unified API, cards, streaming |\n| Chat bot with AI responses | Chat SDK + AI SDK (`thread.post(textStream)`) | Streaming AI across all platforms |\n| UI generation from prompts | v0 | Visual output, GitHub integration |\n\n**IMPORTANT**: Default to AI Gateway for all AI features. Only use direct provider SDKs (`@ai-sdk/anthropic`, `@ai-sdk/openai`, etc.) when you need provider-specific features not exposed through the gateway.\n\n### Storage\n| Need | Use | Why |\n|------|-----|-----|\n| File uploads, media | Vercel Blob | First-party, up to 5TB |\n| Feature flags, A/B config | Edge Config | Ultra-low latency at edge |\n| Relational database | Neon (via Marketplace) | Serverless Postgres, branching |\n| Key-value cache | Upstash Redis (via Marketplace) | Serverless Redis, same billing |\n\n### Build & Monorepo\n| Need | Use | Why |\n|------|-----|-----|\n| Single Next.js app | Turbopack (default) | Fastest HMR, built-in |\n| Monorepo with multiple apps/packages | Turborepo | Caching, parallelism, affected |\n| Code quality enforcement in monorepo | Conformance | Automated best-practice checks |\n| Non-Next.js framework | Framework-native bundler | Vercel adapters handle deploy |\n\n### Security\n| Need | Use | Why |\n|------|-----|-----|\n| DDoS protection | Vercel Firewall (automatic) | Always on, all plans |\n| Custom traffic rules | WAF rules engine | Framework-aware, 300ms propagation |\n| Bot blocking | Bot Filter | One-click, public beta |\n| Rate limiting | WAF rate limiting | Per-endpoint control |\n| OWASP protection | Managed rulesets (Enterprise) | Industry-standard rules |\n| Compliance isolation (SOC2, HIPAA) | Secure Compute | Dedicated infrastructure, no shared tenancy |\n| Tokenless CI/CD deployments | OIDC Federation | Short-lived tokens, no secrets to rotate |\n\n### Functions\n| Need | Use | Why |\n|------|-----|-----|\n| Standard server logic | Serverless Functions (Node.js) | Full Node.js, up to 14min (paid) |\n| Ultra-low latency, simple logic | Edge Functions | <1ms cold start, global |\n| Long-running with I/O waits | Fluid Compute | Shared instances, waitUntil |\n| AI streaming responses | Streaming Functions | SSE, zero config |\n| Scheduled execution | Cron Jobs | vercel.json schedule config |\n\n### Disambiguation: Interception Compute\n\nThese three mechanisms all intercept or handle requests before your application logic runs.\nChoose based on **where** the interception happens and **what** you need to do.\n\n| Mechanism | Layer | Runtime | Use When | Avoid When |\n|-----------|-------|---------|----------|------------|\n| **Routing Middleware** (`middleware.ts` / platform-level) | Edge Network, before cache | V8 isolates (Web Standard APIs) | Auth checks, geo-redirects, A/B routing, header rewriting — any framework | You need Node.js APIs, heavy computation, or database access |\n| **`proxy.ts`** (Next.js 16+) | Application layer, replaces `middleware.ts` | Node.js | Same use cases as Routing Middleware but you need `node:*` modules, ORM calls, or full Node.js compat | You're not on Next.js 16+; prefer Routing Middleware for non-Next.js frameworks |\n| **Edge Functions** | Edge Network, handles the full request | V8 isolates (Web Standard APIs) | Ultra-low-latency API endpoints, simple compute at the edge, streaming responses | You need Node.js runtime, long execution times, or large dependencies |\n\n> **Key distinction**: Routing Middleware and `proxy.ts` are *interceptors* — they rewrite, redirect, or annotate requests before the handler runs. Edge Functions *are* the handler — they produce the response. If you previously used Next.js `middleware.ts` and are upgrading to Next.js 16, rename to `proxy.ts` (see § Migration Awareness).\n\n⤳ skill: routing-middleware — Platform-level request interception\n⤳ skill: vercel-functions — Edge Functions and Serverless Functions\n⤳ skill: nextjs — `proxy.ts` in Next.js 16\n\n### Disambiguation: Caching Layers\n\nThree distinct caching systems serve different purposes. They can be used independently or layered together.\n\n| Mechanism | Scope | Invalidation | Use When | Avoid When |\n|-----------|-------|-------------|----------|------------|\n| **Next.js Cache** (`'use cache'`, `revalidate`, `revalidatePath/Tag`) | Per-route or per-component, framework-managed | Time-based (`revalidate: N`), on-demand (`revalidateTag()`, `revalidatePath()`) | Caching rendered pages, component trees, or data fetches within a Next.js app | You need caching outside Next.js, or need to cache arbitrary key-value data |\n| **Runtime Cache** (Vercel platform, per-region KV) | Per-region key-value store, any framework | Tag-based (`purgeByTag()`), key-based (`delete()`) | Caching expensive computations, API responses, or shared data across functions — works with any framework on Vercel | You only need page-level caching (use Next.js Cache instead); you need global consistency (Runtime Cache is per-region) |\n| **CDN Cache + Purge-by-Tag** (Edge Network, `Cache-Control` + `Cache-Tag` headers) | Global CDN edge, HTTP-level | `Cache-Control` TTL, on-demand purge via Vercel API (`POST /v1/edge-config/purge`) | Static assets, ISR pages, any HTTP response you want cached globally at the edge | Dynamic per-user content, responses that must never be stale |\n\n> **Layering pattern**: A typical Next.js app uses all three — Next.js Cache for component/route-level freshness, Runtime Cache for shared cross-request data (e.g., product catalog), and CDN Cache for static assets and ISR pages. Each layer has its own invalidation strategy; tag-based invalidation can cascade across layers when configured.\n\n⤳ skill: runtime-cache — Per-region key-value caching with tag-based invalidation\n⤳ skill: nextjs — `'use cache'`, `revalidatePath`, `revalidateTag`\n\n---\n\n## 11. Common Cross-Product Workflows\n\n### 1. Build an AI Chatbot\n```\n1. vercel link (or create project in dashboard)\n2. Enable AI Gateway in Vercel dashboard → auto-provisions OIDC credentials\n3. vercel env pull (pulls VERCEL_OIDC_TOKEN + gateway env vars to .env.local)\n4. npm install ai @ai-sdk/react (core SDK + React hooks — `@ai-sdk/react` is required for `useChat`)\n5. npx ai-elements (install chat UI components — Message, Conversation, PromptInput)\n6. Code: model: 'anthropic/claude-sonnet-4.6' (plain string routes through AI Gateway automatically)\n7. Server: convertToModelMessages(messages) → streamText → toUIMessageStreamResponse()\n8. Client: useChat({ transport: new DefaultChatTransport({ api: '/api/chat' }) })\n9. Next.js (App Router) → AI SDK + AI Elements → AI Gateway (OIDC auth)\n                        → Vercel Functions (streaming) → vercel deploy\n```\n\n**OIDC Authentication (default):** When you run `vercel env pull`, it provisions a `VERCEL_OIDC_TOKEN` — a short-lived JWT that the AI Gateway uses automatically. No manual API keys needed. The `@ai-sdk/gateway` package reads `VERCEL_OIDC_TOKEN` from the environment via `@vercel/oidc`. On Vercel deployments, OIDC tokens are auto-refreshed. For local dev, re-run `vercel env pull` if the token expires (~24h).\n```\n\n### 2. Build a Multi-Platform Chat Bot\n```\n1. npm install chat @chat-adapter/slack @chat-adapter/telegram @chat-adapter/state-redis\n2. Create lib/bot.ts → new Chat({ adapters: { slack, telegram }, state: createRedisState() })\n3. Register handlers: onNewMention, onSubscribedMessage, onAction\n4. Create webhook routes (for example app/api/bot/slack/route.ts and app/api/bot/telegram/route.ts)\n   → bot.webhooks.<platform>(req, { waitUntil })\n5. For AI responses: npm install ai → thread.post(result.textStream)\n6. For rich messages: use Card JSX → renders to each platform's native card format\n7. Deploy to Vercel → configure SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, TELEGRAM_BOT_TOKEN, REDIS_URL\n8. Add more platforms: npm install @chat-adapter/discord @chat-adapter/teams @chat-adapter/telegram\n   → add to adapters map → one webhook route per platform\n```\n\n### 3. Build a Durable AI Agent\n```\n1. vercel link → enable AI Gateway → vercel env pull (OIDC credentials required)\n2. Next.js (API Route) → Workflow DevKit (DurableAgent) → AI SDK (tool calling)\n                       → AI Gateway (OIDC auth for model strings in workflow steps)\n                       → Neon Postgres (state) → Vercel Functions (step execution)\n3. For human-in-the-loop: defineHook() + getWritable() token emission + resumeHook() route\n4. For AI text in workflow events: use <MessageResponse> from AI Elements (not raw text)\n```\n\n### 4. Full-Stack SaaS App\n```\nNext.js (App Router) → Neon Postgres (data) → Clerk (auth, via Marketplace)\n                     → Stripe (payments, via Marketplace) → Vercel Blob (uploads)\n                     → Edge Config (feature flags) → Vercel Analytics\n```\n\n**Starter kit**: Use `npx next-forge@latest init` to scaffold a production-ready SaaS monorepo with all of the above pre-wired (plus email, observability, security, AI, i18n, and more). ⤳ skill: next-forge\n\n**Clerk integration gotchas**:\n- `vercel integration add clerk` requires terms acceptance in the terminal (AI agents are blocked — user must run it manually)\n- After CLI install, the user must complete setup in the Vercel Dashboard to connect Clerk to the project\n- Clerk auto-provisions `CLERK_SECRET_KEY` and `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`, but you must manually set `NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in` and `NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up`\n- **Organization flow**: After sign-in, if the user has no organization, `auth()` returns `{ userId, orgSlug: null }`. Handle this explicitly — redirect to an org creation page or show `<CreateOrganization />`. Without this, the app will loop back to the landing page endlessly.\n- The `proxy.ts` (or `middleware.ts`) must call `clerkMiddleware()` for `auth()` to work in Server Components. If proxy is in the wrong location, you get: `Clerk: auth() was called without Clerk middleware`\n\n### 5. Monorepo with Multiple Apps\n```\nTurborepo (orchestration) → Next.js App A → Vercel Platform (deploy)\n                          → Next.js App B → Vercel Platform (deploy)\n                          → Shared packages → Turbopack (bundling)\n                          → Remote Cache → Vercel (shared across CI)\n```\n\n### 6. Deploy with Custom CI\n```\nGit Push → CI Pipeline → vercel build → vercel deploy --prebuilt\n        → VERCEL_TOKEN auth → Preview URL → vercel promote (production)\n```\n\n---\n\n## 12. Migration Awareness\n\n| Deprecated | Replacement | Migration Path |\n|-----------|-------------|----------------|\n| `@vercel/postgres` | `@neondatabase/serverless` | Use `@neondatabase/vercel-postgres-compat` for drop-in |\n| `@vercel/kv` | `@upstash/redis` | Same billing, direct replacement |\n| `middleware.ts` (Next.js 16) | `proxy.ts` | Rename file, Node.js runtime only |\n| `experimental.turbopack` | `turbopack` (top-level) | Move config in next.config |\n| Sync Request APIs (Next.js 16) | Async Request APIs | `await cookies()`, `await headers()`, etc. |\n| PPR (Next.js 15 canary) | Cache Components | Follow Vercel migration guide |\n| AI SDK 5 | AI SDK 6 | Run `npx @ai-sdk/codemod v6` |\n| `generateObject` / `streamObject` | `generateText` / `streamText` + `Output.object()` | Unified structured output API |\n| `parameters` (AI SDK tools) | `inputSchema` | Aligned with MCP spec |\n| `result` (AI SDK tools) | `output` | Aligned with MCP spec |\n| `maxSteps` (AI SDK) | `stopWhen: stepCountIs(N)` | Import `stepCountIs` from `ai` |\n| `CoreMessage` | `ModelMessage` | Use `convertToModelMessages()` |\n| `Experimental_Agent` | `ToolLoopAgent` | `system` → `instructions` |\n| `useChat({ api })` | `useChat({ transport: new DefaultChatTransport({ api }) })` | v6 transport pattern |\n| `handleSubmit` / `input` | `sendMessage({ text })` / own state | v6 chat hook API |\n| `toDataStreamResponse()` | `toUIMessageStreamResponse()` | For chat UIs with useChat |\n| `message.content` | `message.parts` iteration | UIMessage format (text, tool-*, reasoning) |\n| Manual API keys (`ANTHROPIC_API_KEY`) | OIDC via `vercel env pull` | Auto-provisioned, no secrets to manage |\n| `agent.generateText()` | `agent.generate()` | Simplified Agent API |\n| `agent.streamText()` | `agent.stream()` | Simplified Agent API |\n| `isLoading` (useChat) | `status === \"streaming\" \\|\\| status === \"submitted\"` | v6 status enum |\n| `onResponse()` callback | Transport configuration | Removed in v6 |\n| `body` option (useChat) | Pass data through transport | v6 transport pattern |\n| DALL-E 2/3 | `model: 'google/gemini-3.1-flash-image-preview'` | Better quality, faster, cheaper |\n| `gemini-2.0-flash-exp-image-generation` | `gemini-3.1-flash-image-preview` | Dramatically better quality |\n| `gpt-4o` | `gpt-5.4` | Better, cheaper, faster |\n| `experimental_createWorkflow` | `createWorkflow()` (stable) | WDK API stabilized |\n| `\"pipeline\"` (turbo.json) | `\"tasks\"` | Turborepo v2 rename |\n| `next/head` | `metadata` / `generateMetadata()` | App Router pattern (Pages Router only) |\n| `next export` | `output: \"export\"` in next.config | CLI command removed |\n| `cacheHandler` (singular) | `cacheHandlers` (plural) | Next.js 16 config rename |\n\n---\n\n## Conventions\n\n### UI Design Defaults\n\n- For application UI, default to **shadcn/ui + Geist**. Do not build core controls from raw HTML plus ad-hoc Tailwind when design-system primitives exist.\n- Default to **dark mode** for dashboards, AI products, internal tools, and developer surfaces. Use light mode when the product is clearly content-first or editorial.\n- Favor **zinc/neutral/slate tokens**, one accent color, and clear borders over scattered rainbow accents, heavy gradients, and random glassmorphism.\n- Let **type, spacing, and composition** create hierarchy: Tabs + Card + Form for settings, Card + Table + Filters for dashboards, Sheet for mobile navigation, AlertDialog for destructive confirmation.\n- Use **Geist Sans** for interface text and **Geist Mono** for code, metrics, IDs, timestamps, and commands.\n- Avoid generic UI output: raw buttons, clickable divs, repeated bordered card grids, inconsistent radii, and forgotten empty/loading/error states.\n\n### Next.js 16\n\n- Default to Server Components. Only add `'use client'` when you need interactivity or browser APIs.\n- Push `'use client'` boundaries as far down the component tree as possible.\n- Use Server Actions (`'use server'`) for data mutations, not Route Handlers (unless building a public API).\n- All request APIs are async in Next.js 16: `await cookies()`, `await headers()`, `await params`, `await searchParams`.\n- Use `proxy.ts` instead of `middleware.ts` (Next.js 16 rename). Proxy runs on Node.js runtime only. **Location**: place `proxy.ts` at the same level as `app/` — at project root normally, or inside `src/` if using `--src-dir`.\n- Turbopack config is top-level in `next.config.ts`, not under `experimental.turbopack`.\n- Use Cache Components (`'use cache'`) instead of PPR for mixing static and dynamic content.\n- Prefer `next/image` for images and `next/font` for fonts — both optimize automatically on Vercel.\n- `@vercel/postgres` and `@vercel/kv` are sunset — use `@neondatabase/serverless` and `@upstash/redis`.\n\n### AI SDK v6\n\n- **Default to AI Gateway** — pass `\"provider/model\"` strings directly (e.g., `model: 'anthropic/claude-sonnet-4.6'`) — they route through the AI Gateway automatically. The `gateway()` wrapper from `'ai'` is optional and only needed when using `providerOptions.gateway` for routing/failover/tags. Do NOT install or import direct provider SDKs (`@ai-sdk/anthropic`, `@ai-sdk/openai`, etc.) unless you need provider-specific features not exposed through the gateway.\n- **Install `@ai-sdk/react` for React hooks** — `useChat`, `useCompletion`, and `useObject` live in `@ai-sdk/react` (not `ai`). Always `npm install ai @ai-sdk/react` together for React/Next.js projects.\n- **OIDC is the default auth for AI Gateway** — when you run `vercel env pull`, it provisions `VERCEL_OIDC_TOKEN` which the `@ai-sdk/gateway` package reads automatically via `@vercel/oidc`. No `AI_GATEWAY_API_KEY` or provider-specific API keys needed. On Vercel deployments, OIDC tokens are auto-refreshed. For local dev, re-run `vercel env pull` if the token expires (~24h).\n- **For AI projects, set up a Vercel project first** — run `vercel link` (or create via dashboard) → enable AI Gateway in dashboard → `vercel env pull` to get OIDC credentials locally. Do NOT manually create `.env.local` with provider-specific API keys like `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.\n- **AI Elements is MANDATORY for all AI-generated text** — `npx ai-elements@latest` must be installed immediately after scaffolding. Never render AI text as raw `{text}` or `<p>{content}</p>` — it shows ugly `**`, `##`, `---`. Use `<Message>` for chat with `useChat`, and `<MessageResponse>` (from `@/components/ai-elements/message`) for any other AI markdown (workflow events, reports, briefings, notifications, email previews). `<MessageResponse>` wraps Streamdown with code highlighting, math, mermaid, and CJK plugins.\n- **Server-side: use `convertToModelMessages()` (async) + `toUIMessageStreamResponse()`** — not `toDataStreamResponse()`. Client-side: use `DefaultChatTransport` with `useChat`, not the v5 `api` parameter.\n- Use `inputSchema` (not `parameters`) and `output`/`outputSchema` (not `result`) for tool definitions — aligned with MCP spec.\n- Always stream for user-facing AI: use `streamText` + `useChat`, not `generateText`.\n- `generateObject` and `streamObject` are removed in v6 — use `generateText` / `streamText` with `Output.object()` instead.\n- **`maxSteps` was removed** — use `stopWhen: stepCountIs(N)` (import `stepCountIs` from `ai`) for multi-step tool calling in both `streamText` and the `Agent` class.\n- Use the `Agent` class for multi-step reasoning instead of manual tool-calling loops. Agent methods are `agent.generate()` and `agent.stream()` (not `agent.generateText()` / `agent.streamText()`).\n- Use `DurableAgent` from `@workflow/ai/agent` for production agents that must survive crashes.\n- **Image generation is gateway-native** — use `model: 'google/gemini-3.1-flash-image-preview'` with `generateText()` for best results (images in `result.files`). Use `experimental_generateImage` only for image-only models (Imagen 4.0, Flux 2). Do NOT use DALL-E or older Gemini 2.x image models — they are outdated.\n- **Outdated models**: `gpt-4o` → use `gpt-5.4`; `gemini-2.0-flash-exp-image-generation` → use `gemini-3.1-flash-image-preview`; DALL-E 2/3 → use Gemini 3.1 Flash Image Preview.\n- Use `@ai-sdk/mcp` (stable, not experimental) for MCP server connections.\n- Use `mcp-to-ai-sdk` CLI to generate static tool definitions from MCP servers for security.\n- Use AI SDK DevTools (`npx @ai-sdk/devtools`) during development for debugging.\n\n### Vercel Platform\n\n- Never hardcode secrets — use environment variables via `vercel env` or Marketplace auto-provisioning.\n- Add `.env*.local` to `.gitignore` — these files contain pulled secrets.\n- Use Fluid Compute for long-running functions — extends max duration to 800s on paid plans.\n- Use `waitUntil` (or `after` in Next.js) for background work after sending a response.\n- Configure cron jobs in `vercel.json` and verify with `CRON_SECRET` header.\n- Use `vercel deploy --prebuilt` in CI for fastest deploys (separate build from deploy).\n- For monorepos, use Turborepo with remote caching and `--affected` for efficient CI.\n\n---\n\n## Plugin Mechanics\n\nThis document is part of the **Vercel plugin for Codex**. Skills are discovered automatically by Codex via SKILL.md frontmatter metadata (`retrieval.aliases`, `intents`, `entities`, `pathPatterns`, `bashPatterns`). The `vercel.md` ecosystem graph is available as a reference for the full Vercel knowledge graph.\n"}}}}