@oriro/orirocli 0.1.9 → 0.1.11

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

@@ -1,32 +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
+# 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/skills/craft/vercel-optimize/references/playbooks/api-service.md

@@ -1,30 +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
+# 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/skills/craft/vercel-optimize/references/playbooks/content-site.md

@@ -1,30 +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
+# 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/skills/craft/vercel-optimize/references/playbooks/ecommerce.md

@@ -1,30 +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
+# 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/skills/craft/vercel-optimize/references/playbooks/marketing.md

@@ -1,30 +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
+# 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/skills/craft/vercel-optimize/references/playbooks/saas.md

@@ -1,31 +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
+# 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/skills/craft/vercel-optimize/references/playbooks/sveltekit.md

@@ -1,75 +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)
+# 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)