opencode-skills-collection 3.0.35 → 3.0.36

package/bundled-skills/vercel-optimize/references/doctrine.md

@@ -0,0 +1,105 @@
+# Doctrine
+
+The four non-negotiable rules that shape every action this skill takes. If a future change conflicts with one of these, the change is wrong.
+
+## Rule 1: Observability before investigation
+
+The skill never reads a source file without an observability signal pointing at it. Step 1 (`node scripts/collect-signals.mjs`) is always first. Nothing reads source code until `signals.json` exists.
+
+**Why this fails when skipped:** without metrics, the skill defaults to "grep the repo for known anti-patterns and complain." That produces noisy, low-impact recs that aren't tied to traffic, cost, or user pain. Metrics-first investigation keeps the skill focused on observed traffic, cost, and reliability signals.
+
+### Four-check first-pass (Enterprise)
+
+When `plan === 'enterprise'`, the gate run must surface these four checks before code-level recommendations. Field engineers confirm these are the highest-leverage account-level levers across every renewal audit:
+
+1. **Observability Plus enabled?** From `signals.observabilityPlus`. If false, the whole audit degrades; surface as a top-of-report item.
+2. **Reverse proxy in front?** Heuristic from response headers / CNAME chain (when collected). A non-Vercel CDN over Vercel ISR is usually a "dumb pipe" — wasted spend.
+3. **WAF rules enabled?** From `signals.project.security`. BotID + managed rules absent on a project with bot evidence is the most common cost spike.
+4. **ISR read:write ratio.** From `metrics.isrReadsByRoute` + `metrics.isrWritesByRoute`. Include CDN-tier reads (see [data-collection.md](data-collection.md)) before flagging "writes > reads."
+
+These checks anchor the Enterprise-tier report's opening narrative; code-level recs follow.
+
+## Rule 2: Deterministic gate before every sub-agent investigation
+
+`node scripts/gate-investigations.mjs` is a pure-JS, LLM-free function. It reads `signals.json` and outputs `{toLaunch, platform, gated}`. Same input always produces byte-identical output (modulo `appliedAt`).
+
+Every kind of candidate (uncached route, slow route, errors, cold starts, scanner findings, platform-level recs) has its threshold expression encoded as a `gate(signals) → Candidate[]` function in `lib/gates/<kind>.mjs`.
+
+**Failed gates surface in the final report**, under "Not investigated in this run," with the exact reason they were held back. This is the user-facing trust mechanism: you see what we considered and chose to skip, and the reason.
+
+**Why this matters:** the agent never decides "should I look at this route?" via LLM judgment. The threshold is mechanical. This eliminates the entire failure mode where the agent investigates routes it shouldn't (cold-path) and recommends fixes for routes that don't need them.
+
+## Rule 3: Candidate-bound investigation scope
+
+When the gate emits a candidate with `files: ['src/app/api/products/route.ts']`, the agent reads ONLY that file (and its imports as the chain unfolds). It does NOT `grep -r` across the repo.
+
+If you find yourself wanting to grep the whole codebase, stop and re-read the current candidate's `question` field. If the question doesn't constrain the search, the candidate is malformed — log it as `gated` and skip. Do NOT compensate with a wider search.
+
+**Why this matters:** the agent's job is to verify and explain the metric anomaly the gate found, not to do a general code review. Wandering investigations produce drift, hallucination, and recommendations untied to the cost and performance data.
+
+### Scanner findings (the supplementary signal)
+
+Static AST-grep scanners run in parallel with the metric-driven investigations. Their output is annotated with the per-file observability signal (`function invocations: 1.2M; 95th percentile duration: 850ms; cache hit rate: 0%` if the file maps to a hot route, `COLD-PATH` if it maps to a route with no traffic, `NO-ROUTE-MAPPING` if the file doesn't map to any route).
+
+**Default rule:** scanner findings on `COLD-PATH` or `NO-ROUTE-MAPPING` files are dropped. They become recs only if the pattern is *traffic-independent*: build configuration, middleware matcher, source maps in production, raw script tags, React Compiler config. These don't care about traffic — they affect every request equally or affect the build itself.
+
+The traffic-independent allow-list lives in each scanner's `metadata.trafficIndependent: boolean` field. Set it to `true` only when you can defend the claim.
+
+## Rule 4: Doc-grounded, version-aware recommendations — no hallucinations
+
+Every recommendation must carry at least one citation from `references/docs-library.json`. Anything else is dropped at sanitizer time.
+
+The library has two parts:
+- **URLs** — Vercel docs, Next.js docs, SvelteKit docs, etc. Each declares `applicableFrameworks` (e.g., `["next@>=15.0.0"]`).
+- **Cross-skill rule references** — by name only (`vercel-react-best-practices:async-parallel`). The agent's host resolves these.
+
+Three sanitizers enforce this:
+- `missing-citation` — drops recs with empty `citations[]`.
+- `unknown-citation` — strips URLs not in the library, marks `needsReview=true`.
+- `version-mismatch` — strips URLs whose `applicableFrameworks` doesn't match the project's framework@version (parsed from `package.json`).
+
+Two verifier claim types check it: `citation_in_library` (URL ∈ allow-list) and `citation_applies_to_version` (semver match).
+
+**Why this matters:** LLMs cite plausible-looking URLs that 404, or recommend Next 15 features to Next 13 users. Both are trust-killers. The allow-list closes the first failure mode; the `applicableFrameworks` field closes the second.
+
+### Performance citations cite observed data
+
+Every performance claim cites the actual observability datum from `signals.json` — e.g., `functionRoutes[/api/products].p95Ms=850`. Estimated improvements are framed as ranges grounded in the observed baseline: `"Reduce /api/products 95th percentile duration from 850ms toward ~250-400ms based on similar cached routes."` Never an unanchored claim.
+
+### Cost framing is magnitude, never precise
+
+Cost claims like `$340/mo` are forbidden. The dollar noise floor on projections is too high to justify precision. The `impactMagnitude({currentCost, impactTier})` helper maps to phrases like `"hundreds of dollars per month at current traffic"` (computed against the user's actual `vercel usage` data).
+
+The `$-strip` sanitizer enforces this at output time — any `$N` literal in customer-facing fields is stripped.
+
+Performance numbers stay precise because they're observed, not extrapolated. We trust observed metrics; we don't trust dollar projections.
+
+## What good looks like
+
+A good run produces:
+- A small number (5-15) of recommendations.
+- Every rec ties to a specific route or file plus a specific metric signal.
+- Every rec carries before/after code and ≥1 citation matching the user's framework version.
+- Cost framing uses magnitude phrases. Performance framing uses precise observed numbers.
+- The "Not investigated in this run" section explains every other signal we saw and why we chose not to dig (cache hit rate was below threshold, 95th percentile duration was already healthy, etc.).
+- No `$N/mo` strings, no fabricated URLs, no Next.js 15 features recommended to a Next.js 13 user.
+
+## What bad looks like (anti-patterns we will not ship)
+
+- Recommendations from grepping the repo for known anti-patterns, without checking traffic.
+- "Enable Fluid Compute" without a cold-start signal.
+- "Add caching to /api/users" when the route has cookies() and is auth-gated.
+- "Reduce the duration of `/.well-known/workflow/v1/step`" because a Workflow step is long-running. Workflow runtime endpoints are generated orchestration routes; high wall-clock duration there is expected unless a separate reliability/error signal points elsewhere.
+- "Fix `/api/chat/[id]/stream` because it has high duration" without proving the stream does avoidable pre-first-byte work, high active CPU, duplicate invocations, or movable post-response work.
+- "Save $340/mo by doing X" — invented precision.
+- Citations to URLs that don't exist or that describe Next.js features the user's version doesn't have.
+- Long lists of recs the user can't act on; every rec needs an evidence chain.
+
+## Out of scope
+
+The skill is bounded to runtime cost and performance optimization on Vercel-hosted projects. The following are explicit non-goals; if signals or scanner findings surface in these areas, route them out:
+
+- **Deployment artifact size** in isolation. Bundle size matters only when it shows up as runtime cost (cold start, FDT) or performance (LCP, INP). If the only effect is "the .next directory is large," it's not in scope.
+- **Build-time issues without runtime impact.** Slow builds, build-cache misses, monorepo build fan-out — these only enter scope when they show up as Build Minutes billing pressure (then they go through the `build-minutes-fanout` gate). A 6-minute build that completes successfully and ships a small artifact is not a target.
+- **Security advisories and credential rotation.** RCE in `next-mdx-remote`, leaked env vars, OIDC vs explicit-key auth hygiene — refer to a security skill, not this one. Exception: when a security setting is also a documented cost lever (BotID = bot traffic = edge cost), it enters via the `platform_bot_protection` gate.
+- **Commercial / billing-process trivia.** Discount sliders, seat reconciliation, contract renewal mechanics. The skill can quantify which SKU is expensive; it does not negotiate.

package/bundled-skills/vercel-optimize/references/observability-plus.md

@@ -0,0 +1,108 @@
+# Observability Plus Stop-And-Ask
+
+Use this file only when `signals.observabilityPlusBlocker` is set. Do not silently continue into scanner-only mode unless the user chooses that path.
+
+## Why This Check Exists
+
+This is a data dependency, not an upgrade pitch. The skill ranks work by observed route behavior so it can separate hot, expensive paths from code that only looks suspicious. These gates need per-route metrics:
+
+| Gate | Required signal |
+|---|---|
+| `slow_route` | Function duration and invocation count by route |
+| `uncached_route` | Cache result and request count by route |
+| `cold_start` | Function start type by route |
+| `route_errors` | Function status by route |
+| `isr_overrevalidation` | ISR reads and writes by route |
+| `middleware_heavy` | Middleware invocations and duration |
+| `cwv_poor` | Core Web Vitals by route |
+| `platform_bot_protection` | Fast Data Transfer by bot category |
+
+Scanner-only mode can still catch traffic-independent code issues, but it cannot rank the hottest routes or prove cost impact. Make that tradeoff explicit before continuing.
+
+## User Template
+
+Render this template first, then wait for the user's choice. Replace only `<detail>`. Do not add a preface; the heading is the opening line.
+
+```md
+**Per-route metrics are unavailable.**
+
+<detail>
+
+This audit needs route-level metrics to rank fixes by observed latency, cache hit rate, error rate, cold-start rate, and Incremental Static Regeneration reads and writes. Without them, I can run a scanner-only audit for traffic-independent code issues, but I cannot tell which routes matter most or prove cost impact.
+
+Docs: https://vercel.com/docs/observability/observability-plus
+
+Choose one:
+1. Enable Observability Plus, then re-run the metric-backed audit.
+2. Continue in scanner-only mode for a limited audit.
+```
+
+If the host supports a structured question tool, use this exact customer-facing copy. Do not rewrite it.
+
+```json
+{
+  "question": "Enable Observability Plus and re-run, or continue with a limited scanner-only audit?",
+  "header": "Observability Plus",
+  "options": [
+    {
+      "label": "Enable and re-run",
+      "description": "Use route-level metrics to rank the routes that matter most for cost and performance."
+    },
+    {
+      "label": "Run scanner-only",
+      "description": "Check traffic-independent code patterns without route ranking or proven cost impact."
+    }
+  ]
+}
+```
+
+Use the full product name in this question. Do not abbreviate product names or metrics in customer-facing blocker copy.
+
+## After The User Chooses
+
+If the user chooses **Enable and re-run**, stop after this short response:
+
+```md
+Enable Observability Plus from the Vercel dashboard's Observability tab, then tell me to rerun. I'll restart the metric-backed audit once route-level metrics are available.
+```
+
+Do not include raw team IDs, org IDs, project IDs, pricing language, dashboard screenshots, or extra persuasion. The docs link in the blocker message already covers availability and billing details.
+
+If the user chooses **Run scanner-only**, continue with the scanner-only steps below.
+
+## Blocker Copy
+
+| Blocker | Detail |
+|---|---|
+| `payment_required` | `Detected: route-level metrics were recognized for this team, but these metric queries are not usable.` |
+| `no_oplus_probe` | `Detected: this team does not expose the route-level metrics this audit needs.` |
+| `not_linked` | `Detected: this app directory is not linked to a Vercel project.` |
+| `forbidden` | `Detected: the Vercel CLI is authenticated to a team that cannot read this project.` |
+| `project_not_found` | `Detected: the project ID is not visible to the authenticated team.` |
+| `project_disabled` | `Detected: route-level metrics are enabled for the team but disabled for this project.` |
+| `all_failed_other` | `Detected: every per-route metric query failed. Error code: <code>.` |
+
+For `not_linked`, do not use the Observability Plus template. Link the app directory first:
+
+```bash
+vercel link --yes --project <project-name-or-id> --cwd <app-dir>
+```
+
+Add `--team <team-id-or-slug>` when the team is known. If the user supplied both app path and project name, run the link command instead of asking them what to do.
+
+For `forbidden` and `project_not_found`, ask the user to confirm the exact Vercel project and team/personal scope before presenting the Observability Plus choice.
+
+For `project_disabled`, do not present it as a team subscription problem. Ask the user to enable Observability Plus for this project, then re-run.
+
+For `no_traffic`, do not use this template. Tell the user the project has no meaningful traffic in the 14-day window, then ask whether to run scanner-only mode now or come back after traffic accumulates.
+
+## Scanner-Only Mode
+
+If the user picks scanner-only mode:
+
+1. Re-run `node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"` if the current `signals.json` stopped at the fast blocker (`usageError=NOT_COLLECTED_OBSERVABILITY_BLOCKED` or `project=null`).
+2. Run code scanners.
+3. Launch only traffic-independent findings.
+4. Render a clear data gap: per-route metric gates were skipped because Observability Plus data was unavailable.
+
+Do not imply the scanner-only report is a complete optimization audit.

package/bundled-skills/vercel-optimize/references/playbooks/README.md

@@ -0,0 +1,53 @@
+# Playbooks
+
+Application-profile-specific advice that shapes how recommendations are phrased and ordered. Playbooks never invent claims — every rec still traces to a verified candidate or finding. They tell the recommender what to emphasize when a project matches a profile.
+
+## How a playbook gets applied
+
+1. Step 1 detects the project's stack + dependencies.
+2. The recommender heuristics infer an application profile (best guess from frameworks + dep signals).
+3. The matching playbook(s) are included in the recommender's context.
+4. Recommendations are shaped: ordering tilts toward the profile's priority list; phrasing nods to profile-specific concerns.
+
+## Profile detection (best-effort heuristics)
+
+| Signals → | Profile |
+|---|---|
+| `@vercel/sandbox`, `@ai-sdk/*`, `ai`, `openai`, `@anthropic-ai/sdk` deps OR AI Gateway / Sandbox SKU active in `usage.services` | `ai-application` |
+| `stripe`, `@shopify/*`, `react-stripe-js`, "cart"/"checkout" routes | `ecommerce` |
+| `next-auth`, `clerk`, dashboard routes, multi-tenant headers | `saas` |
+| Only `pages/api/**` or `app/api/**`, no UI routes | `api-service` |
+| Heavy MDX / markdown, mostly static routes | `content-site` |
+| Lots of `/(marketing)/` route groups, A/B test deps | `marketing` |
+
+`ai-application` is checked first — AI-shaped customers often share routes with SaaS/ecommerce surfaces, but the billing shape (AI Gateway dominant) and remediation set (provider failover, sandbox reuse, OIDC keyless) belong to this profile.
+
+When detection is uncertain, no playbook is applied. The recommender works fine without one — the playbook is a tilt, not a requirement.
+
+## Playbook schema
+
+Each playbook is a Markdown file with a fixed shape so the recommender can parse it reliably. Required sections:
+
+```markdown
+# {Profile name}
+
+## Typical billing shape
+(Which dimensions dominate — e.g., "Edge Requests > Function Duration > Image Optimization")
+
+## Priority patterns
+(Ordered list of patterns this profile particularly benefits from)
+
+## Frequent gotchas
+(Anti-patterns specific to this profile)
+
+## Cross-references
+(Rec IDs from recommendations.md or rule names from vercel-react-best-practices)
+```
+
+## Contributing a new playbook
+
+1. Identify a clear application profile and one or two representative project profiles that exemplify it.
+2. Create `references/playbooks/<profile>.md` matching the schema.
+3. Add detection signals to the table above (the heuristics live in the recommender code; document them here).
+4. Update the playbook selection matrix in `references/scoring.md`.
+5. Run `node --test packages/vercel-optimize-tests/test/support-topics.test.mjs packages/vercel-optimize-tests/test/investigation-brief.test.mjs`. No tests directly cover playbooks (they're content), but the schema validator runs in CI.

package/bundled-skills/vercel-optimize/references/playbooks/ai-application.md

@@ -0,0 +1,32 @@
+# AI application
+
+LLM-backed apps, agents, code-sandbox tools, RAG pipelines. Cost shape is dominated by per-token AI Gateway spend and Sandbox active-compute time, not edge requests or function duration. Many AI customers also have a SaaS surface (auth, dashboards), but the cost lever lives upstream of the dashboard.
+
+## Typical billing shape
+
+AI Gateway > Sandbox Active Compute > Function Duration > Function Invocations. Edge Requests usually quiet; ISR rarely applies. Observability Events can climb fast if every tool-call span is captured at full fidelity.
+
+## Priority patterns
+
+1. **Provider failover.** Configure AI Gateway with an active-active fallback chain across providers (OpenAI + Anthropic, or model-family pairs). Critical-path agents must not be single-provider — a 429 from one provider becomes a user-visible outage otherwise. Field example: MELI runs homegrown active-active routing because retry-on-error against a single provider degraded their NLP-on-support flow.
+2. **OIDC keyless auth, not explicit API keys.** In production, use the AI Gateway OIDC binding so requests are signed by deployment identity. In local dev, `vercel env run -- <cmd>` rotates OIDC each run. An explicit `AI_GATEWAY_API_KEY` in repo env vars is a regression — it bypasses keyless and creates a long-lived secret.
+3. **Sandbox reuse over per-request `Sandbox.create`.** Each fresh sandbox costs at least 1 minute of billed compute (boot + teardown rounded up). When isolation isn't required (single-tenant agents, shared workspaces), pool sandboxes by name (`sandbox.get(name)`) — auto-snapshot on death + auto-resume on next get is the persistence model.
+4. **`after()` / `waitUntil()` for tool logging.** Tool-call telemetry, audit writes, and analytics should never block the user response. Use `after()` (Next 15+) or `waitUntil()` from `@vercel/functions` for any write that doesn't affect the streamed response.
+5. **Fluid Compute for JIT/process warmth.** Streaming LLM responses benefit from warm processes; the GraphQL/Apollo JIT cache + persisted-document plans only pay back when processes survive across requests. Fluid is the default; disabling it on AI workloads is almost always wrong.
+
+## Frequent gotchas
+
+- **Single-provider lock-in.** "We're using AI Gateway" doesn't imply failover — the provider list still has to be configured. A single-provider gateway is a thinner wrapper, not multi-provider resilience.
+- **Sandbox-per-request.** `new Sandbox(...)` inside a per-request handler with no `id` argument creates a fresh microVM each time. Cheaper to pool when isolation allows.
+- **BYOK fallback cost invisible.** AI Gateway with BYOK silently falls back to system credits on 429 / provider outage; cost migrates from "free BYOK" to "billed credits" without a separate signal unless tracked.
+- **Observability Events runaway.** Captured every tool call + every streamed delta at 100% sampling — events SKU climbs above 30% of bill. Cap span cardinality before scaling traffic.
+
+## Cross-references
+
+- [external-api-critical-path](../support-topics/external-api-critical-path.md) — sequential vs parallel calls; AI Gateway is one external API among others
+- [fluid-compute-caveats](../support-topics/fluid-compute-caveats.md) — module-state hazards and shared-instance caveats
+- [function-duration-io-and-after](../support-topics/function-duration-io-and-after.md) — `after()` for post-response tool logging
+- [observability-events-cost-attribution](../support-topics/observability-events-cost-attribution.md) — when Observability Events climb above 20% of bill
+- [use-cache-remote-shared-origin-data](../support-topics/use-cache-remote-shared-origin-data.md) — caching shared LLM context or embedding lookups
+- `https://vercel.com/docs/ai-gateway` — provider configuration, failover chain
+- `https://vercel.com/docs/vercel-sandbox` — `sandbox.get(name)` and active-compute billing

package/bundled-skills/vercel-optimize/references/playbooks/api-service.md

@@ -0,0 +1,30 @@
+# API service
+
+Headless API backend. No UI routes. Often consumed by mobile apps, partner integrations, or other Vercel projects via rewrites.
+
+## Typical billing shape
+
+Function Duration dominates (every request is a function invocation). Edge Requests scale with API traffic. External API costs matter when the service is a thin shim over third-party APIs (Stripe, Twilio, etc.).
+
+## Priority patterns
+
+1. **Cache GET responses at the edge.** Idempotent GET endpoints (catalog reads, status checks, public data) should ship with `Cache-Control: public, s-maxage=<seconds>, stale-while-revalidate=<longer>`. The CDN serves repeat callers without invoking the function.
+2. **Rate-limit at the edge, not the function.** Middleware with proper matcher scoping handles abusive clients before they hit your function-duration bill.
+3. **Parallel external API calls.** A "checkout-like" endpoint that calls Stripe + inventory + email-service sequentially is the most common slow_route in this profile. `Promise.all` is the obvious fix.
+4. **Background work post-response.** `after()` (Next 15+) for analytics, webhooks-to-self, and any write that doesn't affect the response.
+5. **Connection pooling.** Direct PG connections from serverless function instances exhaust the database. Use PgBouncer / Prisma Accelerate / Neon's pooler.
+
+## Frequent gotchas
+
+- **No `Cache-Control` on the public GETs.** This is the most common finding in this profile, and the easiest fix.
+- **Auth check serialized with data load.** `await checkAuth()` then `await loadData()` — these are often independent and can run in parallel if your auth path doesn't depend on the data.
+- **External API fan-out for one user.** A "build me a profile" endpoint that calls 5 third parties sequentially. Even small latency improvements multiplied by every user are huge.
+- **Long-running async operations on the request path.** Image generation, PDF rendering, big report computation. Move these to background queues or `after()`.
+
+## Cross-references
+
+- `https://vercel.com/docs/caching/cdn-cache` — the GET-handler Cache-Control fix
+- `vercel-react-best-practices:async-parallel` — parallelize external API calls
+- `vercel-react-best-practices:server-after-nonblocking` — `after()` for post-response work
+- `https://vercel.com/docs/fluid-compute` — when cold starts on infrequently-called endpoints hurt
+- `https://nextjs.org/docs/app/building-your-application/routing/middleware` — for rate-limit middleware

package/bundled-skills/vercel-optimize/references/playbooks/content-site.md

@@ -0,0 +1,30 @@
+# Content site
+
+Documentation, blogs, knowledge bases, marketing-adjacent content with mostly static pages. Authoring may be headless-CMS-driven or markdown-in-repo.
+
+## Typical billing shape
+
+Edge Requests dominate (every page view is an edge request; static assets even more). Image Optimization is often the #2 line item. Function Duration tends to be low — most pages should be static or ISR.
+
+## Priority patterns
+
+1. **Pre-render everything that can be pre-rendered.** Blog index, individual posts, docs pages, category pages. Use `generateStaticParams` for App Router or `getStaticPaths` for Pages Router. Anything CMS-driven should run on a webhook revalidation, not on every request.
+2. **ISR with a sensible cadence.** Pages that need fresh-ish content but don't need real-time accuracy go ISR. `revalidate: 3600` (hourly) is a good starting point for docs; `60s` for blog index pages.
+3. **`next/image` for every image asset.** Hero images, author photos, post inline images, OG images. Even thumbnail-only sites benefit from format negotiation (WebP/AVIF).
+4. **`next/font` for self-hosted fonts.** Eliminates FOIT/FOUT, eliminates the third-party request, prevents CLS.
+5. **Prefetch on hover.** `next/link` does this by default. For other frameworks, consider intersection-observer-based prefetch on the visible link set.
+
+## Frequent gotchas
+
+- **`force-dynamic` on the blog index.** Almost never necessary. The index can ISR or be fully static.
+- **Markdown rendering on every request.** If you're parsing MDX at request time, you're paying function-duration cost on what should be a static asset. Build-time MDX → static HTML.
+- **Search rebuilt on every request.** Site search backed by a function that queries a CMS on every keystroke. Move to a search index (Algolia, Pagefind, build-time generated) and serve from the CDN.
+- **CMS preview routes leaking into production traffic.** A `/preview/[slug]` route that's effectively another rendering path; sometimes called from production by mistake. Audit referrers.
+
+## Cross-references
+
+- `https://nextjs.org/docs/app/api-reference/functions/generate-static-params` — for pre-rendering
+- `https://vercel.com/docs/incremental-static-regeneration` — for the ISR fix
+- `https://nextjs.org/docs/app/api-reference/components/image` — image optimization
+- `https://nextjs.org/docs/app/api-reference/components/font` — self-hosted fonts
+- `vercel-react-best-practices:bundle-defer-third-party` — defer analytics/cookie banners

package/bundled-skills/vercel-optimize/references/playbooks/ecommerce.md

@@ -0,0 +1,30 @@
+# E-commerce
+
+Storefronts with cart, checkout, product catalogs. Often Stripe-integrated. Traffic skews toward catalog browsing (cacheable) and checkout (uncacheable).
+
+## Typical billing shape
+
+Edge Requests dominate (catalog browsing, image asset traffic) → Image Optimization (product images) → Function Duration (cart/checkout APIs). ISR Reads matter when product pages use ISR.
+
+## Priority patterns
+
+1. **Catalog pages: aggressive ISR + image optimization.** Product list and product detail pages should be ISR with a sensible `revalidate` (60s-3600s). Every image should go through `next/image` (or the framework equivalent). For Vercel-hosted storefronts, image cost can dominate everything else.
+2. **Checkout: keep dynamic, but parallelize external calls.** Cart/checkout/payment routes are correctly dynamic. The win is in reducing their function duration — `Promise.all` for independent calls to Stripe + inventory + tax services. Cite `vercel-react-best-practices:async-parallel`.
+3. **Cart drawer hydration: lift `'use client'` to the leaf.** Cart components are interactive, but the page wrapping them shouldn't be. Hoist server-rendered parts upward; only the buttons/forms are client.
+4. **Webhooks: separate, not on the user path.** Stripe/Shopify webhook handlers should live as their own routes with short duration limits. They don't share traffic patterns with the storefront.
+5. **Edge middleware for A/B + region routing only.** Catalog locale routing is a fine fit. Auth/cart state belongs in the dynamic page, not middleware.
+
+## Frequent gotchas
+
+- **Product images served raw.** `<img src={product.imageUrl}>` for hundreds of variants costs more than the rest of the bill combined. Always next/image.
+- **`force-dynamic` on the storefront homepage.** Often added during development to test cart-state behavior, never removed. Audit ruthlessly.
+- **Sequential Stripe calls.** "Create customer" → "create subscription" → "create invoice" is often three sequential awaits where two could run in parallel.
+- **Bot traffic on product search.** Marketing-driven traffic + bot traffic on search routes inflates edge request cost. Bot Protection often pays for itself within a month.
+
+## Cross-references
+
+- `vercel-react-best-practices:async-parallel` — parallelize Stripe/inventory/tax calls in checkout
+- `vercel-react-best-practices:async-suspense-boundaries` — stream the checkout shell, fill cart drawer later
+- `vercel-react-best-practices:bundle-defer-third-party` — defer analytics (GA, Mixpanel) post-hydration
+- `https://nextjs.org/docs/app/api-reference/components/image` — for the catalog image fix
+- `https://vercel.com/docs/bot-management` — for bot traffic on search/product routes

package/bundled-skills/vercel-optimize/references/playbooks/marketing.md

@@ -0,0 +1,30 @@
+# Marketing site
+
+Landing pages, lead-capture forms, A/B-tested variants, region-routed homepages. Traffic is bursty (campaigns drive spikes). Bot traffic can be substantial.
+
+## Typical billing shape
+
+Edge Requests dominate. Image Optimization is high (hero images, illustrations, product screenshots). Bandwidth matters for video content. Function Duration is usually low — most pages are static or ISR.
+
+## Priority patterns
+
+1. **Aggressive caching at the edge.** Marketing pages rarely change between campaign updates. `Cache-Control: public, s-maxage=86400, stale-while-revalidate=604800` keeps the CDN warm for 24h and stale-serves for a week.
+2. **Bot Protection.** Marketing campaigns attract competitor scrapers and bot traffic that inflates edge requests without delivering value. If edge cost is > $100/month and Bot Protection is disabled, this is almost always the top platform rec.
+3. **ISR for content-driven sections.** Customer logos, testimonials, "latest blog post" widgets, pricing tables — anything coming from a CMS. Revalidate hourly or on webhook.
+4. **A/B test logic at the edge, not in the page.** Edge Middleware for the variant assignment; cached static page per variant. Don't render the variant choice on every request.
+5. **Defer all third-party JS post-hydration.** Analytics, chat widgets, marketing pixels, cookie banners. None of them block the LCP. Cite `vercel-react-best-practices:bundle-defer-third-party`.
+
+## Frequent gotchas
+
+- **Hero images served at native resolution.** A 4MP hero image on every viewport, including mobile. `next/image` with `sizes` is mandatory.
+- **Cookie banner blocks first paint.** GDPR-compliant cookie banners often render synchronously in the head. Defer; render after hydration; persist consent state via a tiny inline script.
+- **Tracking pixel waterfalls.** Three different analytics services loaded in a chain. Load them after hydration in parallel; better yet, replace some with server-side tracking via webhook.
+- **`/api/contact` is the only function but runs hot.** Marketing sites are mostly static but the contact form gets bot-spammed. Rate limit at middleware; consider a queue for outgoing emails.
+
+## Cross-references
+
+- `https://vercel.com/docs/bot-management` — almost always the right platform rec
+- `https://vercel.com/docs/incremental-static-regeneration` — for CMS-driven sections
+- `https://nextjs.org/docs/app/api-reference/components/image` — hero/illustration optimization
+- `vercel-react-best-practices:bundle-defer-third-party` — defer analytics/pixels
+- `https://nextjs.org/docs/app/building-your-application/routing/middleware` — A/B variant routing at the edge

package/bundled-skills/vercel-optimize/references/playbooks/saas.md

@@ -0,0 +1,31 @@
+# SaaS
+
+Multi-tenant applications with authenticated dashboards, settings, billing. Auth-gated by default. Traffic skews toward function duration (per-user data fetches) over edge requests.
+
+## Typical billing shape
+
+Function Duration dominates (every dashboard request runs the function fully — no edge caching for auth-gated content). Edge Requests grow with API surface. ISR rarely applies. Image Optimization rarely material.
+
+## Priority patterns
+
+1. **Per-request memoization with React.cache().** Server Components called from multiple places in the same request tree often re-query the database. `React.cache()` dedupes within the request. Cite `vercel-react-best-practices:server-cache-react`.
+2. **Parallel data loads in Server Components.** Dashboards typically load user + org + billing + recent-activity. Run all four in parallel via `Promise.all`. Cite `vercel-react-best-practices:async-parallel` and `:server-parallel-fetching`.
+3. **Fluid Compute.** Auth-gated routes have higher cold-start sensitivity (every cold start is a user waiting). If cold-start signal shows up in observability, Fluid Compute is usually the right account-level rec.
+4. **Async work after response.** Activity logs, audit trails, analytics events — anything that doesn't block the user — should run via `after()` (Next 15+) or `waitUntil()` from `@vercel/functions`. Cite `vercel-react-best-practices:server-after-nonblocking`.
+5. **Suspense boundaries around expensive widgets.** The dashboard shell renders fast; widgets stream in. This shifts perceived latency without changing the underlying queries.
+
+## Frequent gotchas
+
+- **N+1 ORM queries.** A list page that loops over results and fetches related records per-item. Especially common with Prisma's `.findUnique` inside a `.map`. Use `include` or batch via DataLoader.
+- **Sequential session+permission checks.** `await getSession()` then `await checkPermissions()` then `await loadData()` — these can often be parallelized when the permissions check doesn't depend on the data load.
+- **No connection pooling on serverless.** Prisma without a pooler exhausts the database under load. Connection pooling is mandatory.
+- **Polling for state from the client.** Every poll is a function invocation. Replace with SWR + on-demand revalidation, or with `revalidateTag` triggered by the mutation that actually changes state.
+
+## Cross-references
+
+- `vercel-react-best-practices:server-cache-react` — per-request dedup
+- `vercel-react-best-practices:server-parallel-fetching` — restructure for Promise.all
+- `vercel-react-best-practices:async-suspense-boundaries` — stream the dashboard shell
+- `vercel-react-best-practices:server-after-nonblocking` — defer audit/analytics writes (Next 15+)
+- `vercel-react-best-practices:client-swr-dedup` — replace polling with SWR
+- `https://vercel.com/docs/fluid-compute` — when cold starts hurt

package/bundled-skills/vercel-optimize/references/playbooks/sveltekit.md

@@ -0,0 +1,75 @@
+# SvelteKit
+
+Framework-specific playbook for SvelteKit projects on Vercel. Applies in
+addition to whichever application-profile playbook fits (saas, ecommerce,
+content-site, etc.). SvelteKit-on-Vercel ships through
+`@sveltejs/adapter-vercel`, so most platform-level recs map to adapter
+config rather than per-route framework APIs.
+
+## Typical billing shape
+
+Function Duration dominates server-rendered routes (every `+page.server.ts`
+`load` + `+server.ts` POST handler runs as a function). Edge Requests grow
+with API surface (`+server.ts` and form actions). ISR is supported via the
+adapter; when enabled, it converts to a cache_result HIT after first render.
+Image Optimization is rarely a SvelteKit-specific lever (it's the same
+Vercel image service Next.js uses).
+
+## Priority patterns
+
+1. **Adapter ISR for cacheable content.** Routes that don't depend on
+   per-request data are still served as functions by default. The
+   adapter accepts an `isr: { expiration: 60 }` option per route (set
+   in `+page.server.ts` via `export const config`). This converts
+   function invocations to cache hits. Cite
+   `https://kit.svelte.dev/docs/adapter-vercel` +
+   `https://vercel.com/docs/incremental-static-regeneration`.
+2. **Prerender what's static.** `export const prerender = true` in
+   `+page.server.ts` or `+page.ts` moves a route from function to CDN.
+   Cite `https://kit.svelte.dev/docs/page-options`.
+3. **Parallel `load` fetches.** A `load` function with multiple
+   sequential `await fetch(...)` calls leaves wall-clock time on the
+   table — wrap them in `Promise.all` (or return promises directly
+   from `load`, which SvelteKit streams). Cite
+   `https://kit.svelte.dev/docs/load`.
+4. **Move per-request work to `+server.ts` action handlers and run
+   them via `fetch` from the client.** Reduces SSR cost when only a
+   slice of the page actually needs server data on every request.
+5. **`hooks.server.ts` matcher hygiene.** Like Next.js middleware, the
+   `handle` hook intercepts every request unless filtered. Heavy
+   `handle` code multiplies cost by request volume. Move work into the
+   specific route's `load` when only that route needs it.
+6. **Adapter runtime + region config.** Single-region default; if the
+   project's users skew to a different region, set `regions: [...]` on
+   the adapter to reduce TTFB by 100-300ms.
+
+## Frequent gotchas
+
+- **Per-route SSR when prerender would do.** Marketing pages, docs,
+  blog posts often end up as functions because nobody added
+  `prerender = true`. The scanner flags these.
+- **`+layout.server.ts` data fetches blocking every child route.**
+  Auth-check + user-load in a layout makes EVERY function invocation
+  wait on those queries — even routes that don't read user. Push
+  user-load into the routes that need it.
+- **Adapter version drift.** `adapter-vercel@5` adds new options (ISR,
+  split). `adapter-vercel@3` doesn't. The recommender must check the
+  installed version before suggesting `isr: ...`.
+- **`fetch` calls in `load` to your own SvelteKit routes.** SvelteKit
+  optimizes these into direct module calls during SSR, but only if
+  the URL is relative. A hardcoded `https://your-domain.tld/api/...`
+  defeats this optimization.
+- **No connection pooling on serverless.** Same as Next.js — Postgres
+  without a pooler exhausts the database under load.
+
+## Cross-references
+
+- `https://kit.svelte.dev/docs/adapter-vercel` — adapter config (ISR, regions, runtime)
+- `https://kit.svelte.dev/docs/page-options` — prerender, ssr, csr
+- `https://kit.svelte.dev/docs/load` — parallel fetches in load
+- `https://kit.svelte.dev/docs/routing` — file conventions
+- `https://kit.svelte.dev/docs/hooks` — handle / handleFetch
+- `https://kit.svelte.dev/docs/form-actions` — server-side form handling
+- `https://kit.svelte.dev/docs/state-management` — request-scoped state
+- `https://vercel.com/docs/incremental-static-regeneration` — ISR on Vercel
+- `https://vercel.com/docs/fluid-compute` — Fluid Compute (framework-agnostic)