opencode-skills-collection 3.0.35 → 3.0.37

package/bundled-skills/vercel-optimize/references/support-topics/next-image-lcp-preload-sizes.md

@@ -0,0 +1,23 @@
+---
+id: next-image-lcp-preload-sizes
+title: Next.js image LCP preload and sizes
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["next@*"]
+metrics: ["LCP"]
+priority: 86
+citations: ["https://nextjs.org/docs/app/api-reference/components/image", "https://web.dev/articles/optimize-lcp"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For poor LCP, identify whether the LCP element is an image before touching unrelated JavaScript. Hero images need correct sizing, priority behavior, and source-cache hygiene.
+
+## Evidence To Check
+Inspect above-the-fold media for `next/image`, `fill` without `sizes`, deprecated `priority` on Next.js 16, missing `preload` or `fetchPriority`, oversized dimensions, and remote-image TTL/source behavior.
+
+## Do Not Recommend When
+Do not preload multiple possible LCP images or route tiny icons/SVG UI assets through image optimization. Do not change quality or TTL without checking source-update semantics.
+
+## Verification
+Name the LCP value, image element or component, current props/config, and the exact line to change.

package/bundled-skills/vercel-optimize/references/support-topics/next-route-handler-get-cache-defaults.md

@@ -0,0 +1,22 @@
+---
+id: next-route-handler-get-cache-defaults
+title: Next.js Route Handler GET cache defaults
+status: active
+candidateKinds: ["uncached_route", "cache_header_gap"]
+frameworks: ["next@>=15.0.0"]
+priority: 91
+citations: ["https://nextjs.org/docs/app/api-reference/file-conventions/route", "https://vercel.com/docs/caching/cdn-cache"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+On Next.js 15+, GET Route Handlers are dynamic by default. For hot public GET handlers, verify whether uncached behavior is intentional before recommending cache headers or route config.
+
+## Evidence To Check
+Use method share, cache result, and source. Check `GET`, `revalidate`, `dynamic`, request headers, cookies, auth, query params, and response `Cache-Control`.
+
+## Do Not Recommend When
+Do not cache POST-style handlers, webhooks, per-user APIs, streaming responses, search requests with user-specific params, or handlers that read auth/cookies.
+
+## Verification
+Name the Next.js version, GET share, cache result mix, and the exact handler or header line that makes public caching safe.

package/bundled-skills/vercel-optimize/references/support-topics/next-script-third-party-strategy.md

@@ -0,0 +1,23 @@
+---
+id: next-script-third-party-strategy
+title: Next.js third-party script strategy
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["next@*"]
+metrics: ["LCP", "INP"]
+priority: 85
+citations: ["https://nextjs.org/docs/app/api-reference/components/script", "https://web.dev/articles/optimize-inp"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Third-party scripts are only actionable when they line up with the poor metric and route. For LCP or INP, prove a specific script blocks critical rendering, hydration, or interaction.
+
+## Evidence To Check
+Inspect `next/script`, raw `<script>`, tag managers, chat widgets, analytics, and consent code. Check `beforeInteractive`, `afterInteractive`, `lazyOnload`, and whether the script is route-local or global.
+
+## Do Not Recommend When
+Do not move required bot detection, consent, auth, or payment scripts later without product evidence. Do not recommend `worker` for App Router.
+
+## Verification
+Name the poor metric, script source, current strategy, and the exact route or layout line to change.

package/bundled-skills/vercel-optimize/references/support-topics/nextjs-version-cache-semantics.md

@@ -0,0 +1,22 @@
+---
+id: nextjs-version-cache-semantics
+title: Next.js cache semantics by version
+status: active
+candidateKinds: ["uncached_route"]
+frameworks: ["next@>=15.0.0"]
+priority: 85
+citations: ["https://nextjs.org/docs/app/api-reference/directives/use-cache", "https://nextjs.org/docs/app/api-reference/functions/cacheLife", "https://nextjs.org/docs/app/building-your-application/caching"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+On Next.js 15+, match the fix to the cache primitive already in use.
+
+## Evidence To Check
+Check `'use cache'`, `cacheLife`, `cacheTag`, `fetch` cache options, route handlers, and dynamic APIs.
+
+## Do Not Recommend When
+Do not suggest APIs outside the detected Next.js version. Do not claim `cacheLife()` emits CDN `Cache-Control` headers or that missing `cacheLife()` alone makes a `'use cache'` route run per request. Omitted `cacheLife()` calls use the default profile.
+
+## Verification
+Name the detected Next.js version and exact cache primitive or route header.

package/bundled-skills/vercel-optimize/references/support-topics/not-found-catchall-request-waste.md

@@ -0,0 +1,23 @@
+---
+id: not-found-catchall-request-waste
+title: Not-found and catch-all request waste
+status: active
+candidateKinds: ["uncached_route"]
+frameworks: ["*"]
+routePatterns: ["(^|/)404$", "not-found", "\\[\\.\\.\\."]
+priority: 92
+citations: ["https://vercel.com/docs/routing/", "https://vercel.com/docs/redirects/bulk-redirects/", "https://vercel.com/docs/vercel-firewall/vercel-waf/custom-rules", "https://vercel.com/docs/vercel-firewall/vercel-waf/managed-rulesets"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+High-volume 404 or catch-all traffic is often request waste. First determine whether the traffic is legacy URLs, bots, broken links, or a real product route.
+
+## Evidence To Check
+Use route volume, method share, cache result, bot share, and top request paths. Inspect redirects, rewrites, catch-all routes, sitemap/robots output, and any WAF rules already logging or blocking the pattern.
+
+## Do Not Recommend When
+Do not block or redirect legitimate product routes, search crawlers, or unknown traffic without a log-mode validation path. Do not replace a useful 404 page with a blanket rewrite.
+
+## Verification
+Name the dominant bad path pattern, observed request or bot volume, and the redirect, routing, or WAF rule that would stop the wasted function path.

package/bundled-skills/vercel-optimize/references/support-topics/nuxt-route-rules-cache-isr.md

@@ -0,0 +1,22 @@
+---
+id: nuxt-route-rules-cache-isr
+title: Nuxt routeRules cache and ISR
+status: active
+candidateKinds: ["uncached_route", "isr_overrevalidation", "rendering_candidate"]
+frameworks: ["nuxt@>=3.0.0"]
+priority: 90
+citations: ["https://vercel.com/docs/frameworks/full-stack/nuxt", "https://nuxt.com/docs/4.x/api/utils/define-route-rules", "https://nuxt.com/docs/4.x/guide/concepts/rendering"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For Nuxt on Vercel, route-level caching usually belongs in `routeRules`. Match the lever to the route: prerender for static pages, ISR for shared content, and SSR for request-specific views.
+
+## Evidence To Check
+Inspect `nuxt.config`, inline route rules, server routes, pages, auth/session reads, and observed cache or ISR read/write patterns. Verify whether the route should be Vercel cache-backed ISR rather than generic SWR.
+
+## Do Not Recommend When
+Do not cache authenticated, cart, checkout, preview, or per-user routes. Do not add routeRules without proving the route is public and the freshness window is acceptable.
+
+## Verification
+Name the observed route signal, current routeRule or missing rule, chosen cache mode, and exact config line.

package/bundled-skills/vercel-optimize/references/support-topics/observability-events-cost-attribution.md

@@ -0,0 +1,22 @@
+---
+id: observability-events-cost-attribution
+title: Observability Events cost attribution
+status: active
+candidateKinds: ["observability_events_attribution"]
+frameworks: ["*"]
+priority: 92
+citations: ["https://vercel.com/docs/observability/observability-plus", "https://vercel.com/docs/alerts"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Observability Events is the metered SKU under Observability Plus. When the current bill shows a large Observability Events share, event volume is the lever. Reduce upstream: lift cache hit rate, narrow middleware matchers, and reduce unnecessary custom-span cardinality.
+
+## Evidence To Check
+Verify the share from `usage.services`. Cross-reference `requestsByRouteCache`, `middlewareCount`, external API span counts, and third-party tracing (`tracesSampleRate=1`).
+
+## Do Not Recommend When
+Skip below 15% share. Skip when cache hit rate is already >90% across hot routes — the lever is elsewhere. Do not propose sampling unless the specific metered signal has a documented sampling control.
+
+## Verification
+Name the share, upstream drivers, and concrete remediation per driver, not generic "reduce events".

package/bundled-skills/vercel-optimize/references/support-topics/post-response-work-waituntil.md

@@ -0,0 +1,22 @@
+---
+id: post-response-work-waituntil
+title: Post-response work with waitUntil
+status: active
+candidateKinds: ["slow_route", "external_api_slow"]
+frameworks: ["next@<15.0.0", "sveltekit@*", "astro@*", "nuxt@*", "unknown@*"]
+priority: 78
+citations: ["https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+For stacks without Next.js `after()`, check whether non-critical work can run after the response instead of extending user-visible latency.
+
+## Evidence To Check
+Inspect the listed route for analytics, logging, notifications, cache warming, metrics, or webhook side effects that happen after the response data is ready.
+
+## Do Not Recommend When
+Do not move work that decides the response, must fail the request, changes visible state synchronously, or needs a durable retry guarantee.
+
+## Verification
+Name the blocking side effect, the observed latency or upstream signal, and the exact line that can move behind `waitUntil`.

package/bundled-skills/vercel-optimize/references/support-topics/route-error-durable-offload.md

@@ -0,0 +1,22 @@
+---
+id: route-error-durable-offload
+title: Durable offload for timeout-heavy routes
+status: active
+candidateKinds: ["route_errors"]
+frameworks: ["*"]
+priority: 84
+citations: ["https://vercel.com/docs/workflow", "https://workflow-sdk.dev/docs/foundations/starting-workflows", "https://workflow-sdk.dev/docs/foundations/workflows-and-steps", "https://vercel.com/docs/queues", "https://vercel.com/docs/functions/limitations"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Timeout-heavy routes often need a job boundary, not a higher limit. Workflow fits durable multi-step work that can continue after the response; return a run ID instead of waiting on `returnValue`.
+
+## Evidence To Check
+Use `errorStatusPattern`, `errorCodes`, and source flow. Look for fan-out, polling, batch work, AI jobs, uploads, sleeps, approval, multi-step side effects. If Workflow is already used, check whether the route waits or streams progress.
+
+## Do Not Recommend When
+Do not offload work that must finish before responding. Do not claim savings from offload alone: Workflow Steps/Storage bill separately, and invoked functions still use compute billing.
+
+## Verification
+Name the timeout/error class, long-running operation, post-enqueue response contract, and queue or workflow boundary that preserves semantics.

package/bundled-skills/vercel-optimize/references/support-topics/route-error-runtime-limits.md

@@ -0,0 +1,22 @@
+---
+id: route-error-runtime-limits
+title: Route errors and runtime limits
+status: active
+candidateKinds: ["route_errors"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/functions", "https://vercel.com/docs/functions/limitations", "https://vercel.com/docs/cli/inspect"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Route error candidates are reliability findings with cost impact. Determine whether the failures are app exceptions, timeouts, payload limits, or deployment-specific regressions.
+
+## Evidence To Check
+Use `errorStatusPattern`, `errorCodes`, and `errorsByDeployment`. In source, inspect the path most likely to throw, time out, or exceed a platform limit.
+
+## Do Not Recommend When
+Do not frame high 5xx volume as a performance tuning issue. Do not suggest increasing limits before proving the route needs more headroom.
+
+## Verification
+Name the error class, deployment concentration if present, and the file line that triggers or fails to handle it.

package/bundled-skills/vercel-optimize/references/support-topics/runtime-cache-reusable-data.md

@@ -0,0 +1,22 @@
+---
+id: runtime-cache-reusable-data
+title: Runtime Cache for reusable server data
+status: active
+candidateKinds: ["slow_route", "external_api_slow"]
+frameworks: ["*"]
+priority: 84
+citations: ["https://vercel.com/docs/caching/runtime-cache", "https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Runtime Cache is only useful when the same server-side result is reused across requests. Treat it as a measured alternative when CDN response caching is unsafe or incomplete.
+
+## Evidence To Check
+Use p75/p95 latency, call count, caller routes, and transfer bytes. In source, identify database queries, external API calls, or expensive computations that return the same result for many viewers.
+
+## Do Not Recommend When
+Skip per-user data, mutations, secrets, one-off requests, or unknown freshness. Skip Runtime Cache when CDN caching solves the route. For Next with Cache Components, check `use cache: remote` first; use Runtime Cache only as a justified fallback.
+
+## Verification
+Name the reusable data, observed route or hostname pressure, required freshness window, and the exact call site to wrap.

package/bundled-skills/vercel-optimize/references/support-topics/sveltekit-isr-prerender-safety.md

@@ -0,0 +1,22 @@
+---
+id: sveltekit-isr-prerender-safety
+title: SvelteKit ISR and prerender safety
+status: active
+candidateKinds: ["uncached_route", "isr_overrevalidation"]
+frameworks: ["sveltekit@*"]
+priority: 90
+citations: ["https://vercel.com/docs/frameworks/full-stack/sveltekit", "https://svelte.dev/docs/kit/adapter-vercel", "https://svelte.dev/docs/kit/page-options"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For SvelteKit, the right lever is often `prerender` or adapter ISR on public consumer pages. First prove every visitor can safely see the same response for the configured interval.
+
+## Evidence To Check
+Inspect `+page`, `+page.server`, `+server`, layouts, `prerender`, `ssr`, and adapter `isr` config. Compare route cache results, ISR writes, and whether the route reads cookies, auth, or per-user locals.
+
+## Do Not Recommend When
+Do not use ISR for dashboards, carts, checkout, account data, drafts, or any route whose output varies per visitor. Do not add ISR when `prerender = true` already makes it irrelevant.
+
+## Verification
+Name the route, current SvelteKit page option or adapter config, observed cache or ISR signal, and the exact file line to change.

package/bundled-skills/vercel-optimize/references/support-topics/sveltekit-split-cold-start-tradeoff.md

@@ -0,0 +1,22 @@
+---
+id: sveltekit-split-cold-start-tradeoff
+title: SvelteKit split function cold-start tradeoff
+status: active
+candidateKinds: ["cold_start", "slow_route"]
+frameworks: ["sveltekit@*"]
+priority: 82
+citations: ["https://vercel.com/docs/frameworks/full-stack/sveltekit", "https://svelte.dev/docs/kit/adapter-vercel"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+SvelteKit bundles routes together by default to avoid excessive cold starts. Treat `split: true` as a targeted tradeoff, not a blanket optimization.
+
+## Evidence To Check
+Use cold-start share, cold-vs-warm latency, deployment concentration, and source bundle pressure. Check adapter options and whether a large dependency belongs to one route or the whole app.
+
+## Do Not Recommend When
+Do not split every route without evidence of function size pressure or route-local initialization cost. Do not split if cold starts are already the dominant problem.
+
+## Verification
+Name the cold-start signal, route or dependency that motivates the split, and the exact adapter config line.

package/bundled-skills/vercel-optimize/references/support-topics/usage-spike-triage.md

@@ -0,0 +1,22 @@
+---
+id: usage-spike-triage
+title: Usage spike triage
+status: active
+candidateKinds: ["usage_spike_triage"]
+frameworks: ["*"]
+priority: 95
+citations: ["https://vercel.com/docs/alerts", "https://vercel.com/docs/spend-management", "https://vercel.com/docs/bot-management"]
+maxBriefChars: 950
+---
+
+## Investigation Brief
+A single-day or single-SKU spike needs cause before fix. Branches: bot or AI crawler on a cacheable route, viral moment, pricing-model migration, or code regression.
+
+## Evidence To Check
+Confirm SKU and day from `usage.breakdown.data`. Cross-check firewall/bot data, traffic curve, SKU rename timing, and deploy log around the spike day. Spend Management and Alerts are monitoring tools; they do not replace finding the traffic or deploy cause.
+
+## Do Not Recommend When
+Do not propose a code fix until the branch is identified. Do not rate-limit a viral moment or revert a deploy for third-party crawler traffic.
+
+## Verification
+Name SKU, day, value, window mean, branch, and one supporting datum.

package/bundled-skills/vercel-optimize/references/support-topics/use-cache-date-stamp-isr-write-amplifier.md

@@ -0,0 +1,23 @@
+---
+id: use-cache-date-stamp-isr-write-amplifier
+title: "'use cache' date-stamp ISR write amplifier"
+status: active
+candidateKinds: ["use_cache_date_stamp"]
+frameworks: ["next@>=15.0.0"]
+scannerPatterns: ["use-cache-date-stamp"]
+priority: 88
+citations: ["https://nextjs.org/docs/app/api-reference/directives/use-cache", "https://nextjs.org/docs/app/api-reference/functions/cacheLife"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+`'use cache'` keys on argument identity and prerender output. A `new Date()`, `Date.now()`, or `Math.random()` baked into the cached output forces a fresh ISR write on every regeneration even when the data is unchanged.
+
+## Evidence To Check
+Check the scanner finding's `subtype`: `module-scope` (module-level date) or `in-cache-fn` (inside the cached body). Cross-reference `isrWritesByRoute` — a stable write rate against low reads is the symptom.
+
+## Do Not Recommend When
+Skip if the date is inside `useEffect`/`useCallback`/`useMemo`. Skip if `'use cache'` is only a comment. Skip if the date is the intended cache key.
+
+## Verification
+Name the file, the specific primitive call, and the replacement: build-time constant or client-side `useEffect`.

package/bundled-skills/vercel-optimize/references/support-topics/use-cache-remote-shared-origin-data.md

@@ -0,0 +1,22 @@
+---
+id: use-cache-remote-shared-origin-data
+title: Remote cache for shared origin data
+status: active
+candidateKinds: ["external_api_slow", "slow_route", "uncached_route"]
+frameworks: ["next@>=16.0.0"]
+priority: 87
+citations: ["https://vercel.com/docs/caching/runtime-cache", "https://nextjs.org/docs/app/api-reference/directives/use-cache-remote"]
+maxBriefChars: 950
+---
+
+## Investigation Brief
+For Next 16 candidates, check whether shared origin data or reusable route-handler work belongs in remote cache. Default `'use cache'` is not cross-request on Vercel. Use `'use cache: remote'` or `generateStaticParams`.
+
+## Evidence To Check
+Hostname p75, caller routes, call count, bytes. Verify data is shared and tolerates the freshness window. Confirm `'use cache: remote'`.
+
+## Do Not Recommend When
+Skip per-user, mutation, secret, or freshness-critical data. Skip when upstream is fast or rarely called. Avoid sub-ms reads (Edge Config) — overhead exceeds source latency.
+
+## Verification
+Name hostname, shared data, freshness window, and exact boundary. State `'use cache: remote'`.

package/bundled-skills/vercel-optimize/references/support-topics/workflow-resumable-stream-routes.md

@@ -0,0 +1,23 @@
+---
+id: workflow-resumable-stream-routes
+title: Workflow resumable stream routes
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["*"]
+routePatterns: ["(^|/)api/.*/stream/?$", "(^|/)chat/.*/stream/?$", "\\[id\\].*/stream"]
+priority: 98
+citations: ["https://workflow-sdk.dev/docs/ai/resumable-streams", "https://workflow-sdk.dev/docs/foundations/streaming", "https://vercel.com/docs/workflow"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Stream-shaped routes may be Workflow SDK reconnection endpoints. Long wall-clock duration can be the live client connection.
+
+## Evidence To Check
+Look for `WorkflowChatTransport`, `getRun`, `run.getReadable`, `startIndex`, `x-workflow-run-id`, `x-workflow-stream-tail-index`, `getWritable`, or `createUIMessageStreamResponse`. Compare CPU, TTFB, wall-clock. Check full replay, missing tail-index, unreleased locks, or unclosed streams.
+
+## Do Not Recommend When
+Do not cache stream endpoints or remove resumability. Do not call high duration a bug when CPU is low, TTFB is healthy, and the route only holds a client connection.
+
+## Verification
+Name whether the route starts or reconnects a run, then cite the exact waste: replay, missing tail-index, lock leak, unclosed stream, high CPU, or avoidable pre-first-byte work.

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

@@ -0,0 +1,102 @@
+# Verification
+
+How claims in recommendations are mechanically verified, and when the recommender re-runs after a low pass rate.
+
+## Table of contents
+
+- [Why mechanical verification](#why-mechanical-verification)
+- [Claim types](#claim-types)
+- [Dispositions](#dispositions)
+- [Re-gen trigger and accept criteria](#re-gen-trigger-and-accept-criteria)
+- [Verifier implementation](#verifier-implementation)
+
+## Why mechanical verification
+
+The recommender is an LLM. LLMs hallucinate counts, miscount file occurrences, and confuse code snippets between similar-looking files. Mechanical verification — grep + filesystem reads + JSON checks against `signals.json` and `references/docs-library.json` — catches these failures before the customer sees them.
+
+The contract: every numeric claim, file reference, code snippet, citation URL, and contradiction-with-other-claims is verified. The LLM is not asked to judge whether its own output is correct.
+
+## Claim types
+
+The verifier extracts claims from `why`, `fix`, `currentBehavior`, `desiredBehavior`, and `verify` fields. Each matched claim runs through one of these handlers:
+
+| # | Claim type | Pattern in rec | Verification |
+|---|---|---|---|
+| 1 | `pattern_count` | "N fetch() calls in file X" | grep/ast-grep in X, exact count match |
+| 2 | `pattern_exists` | "uses JSON.parse(JSON.stringify())" | grep, boolean |
+| 3 | `pattern_absent` | "no Cache-Control header" | grep, verify absence (with guards — see below) |
+| 4 | `file_exists` | "app/not-found.tsx exists" | fs.access |
+| 5 | `finding_count` | "2 unoptimized images" | finding count vs `verifiedFindings.json` |
+| 6 | `contradiction` | Claim A vs Claim B | Substring conflict check |
+| 7 | `code_snippet` | Code fence labeled "Before:" | substring search in cited file |
+| 8 | `arithmetic` | "20% of 100K = 20K" | math check |
+| 9 | `repo_count` | "11 unstable_cache usages across 8 files" | grep repo, count distinct files |
+| 10 | `cited_count_literal` | "60+ icons in packages/ui/src/icons" | glob directory, count by extension |
+| 11 | `citation_in_library` | Any URL in `citations[]` | URL ∈ `references/docs-library.json` |
+| 12 | `citation_applies_to_version` | Any URL in `citations[]` | URL's `applicableFrameworks` matches `signals.json.stack.framework@frameworkVersion` |
+| 13 | `cache_vary_matches_dynamic_inputs` | CDN cache rec touches route files that read Vercel geolocation | Fails unless the rec varies by a coarse Vercel geolocation header such as `X-Vercel-IP-Country`, `X-Vercel-IP-Country-Region`, or `X-Vercel-IP-City` |
+| 13a | `cache_vary_cardinality_safe` | CDN cache rec sets `Vary` on request-specific geography | Fails on high-cardinality `X-Vercel-IP-Latitude` / `X-Vercel-IP-Longitude` / `X-Vercel-IP-Postal-Code` |
+| 14 | `next_cached_not_found_causal_support` | Rec claims `notFound()` inside `'use cache'` caused 5xx | Fails unless backed by Next-specific docs or runtime stack evidence |
+| 15 | `next_stable_cache_api_for_version` | Next.js 16 cache rec includes code examples | Fails on `unstable_cacheLife` / `unstable_cacheTag` or one-arg `revalidateTag()` |
+| 16 | `next_cache_components_runtime_cache_preference` | Next.js rec uses Runtime Cache APIs while `cacheComponents=true` | Fails unless `use cache: remote` is used or Runtime Cache is framed as a fallback |
+| 17 | `next_cache_components_route_segment_config` | Next.js 16 rec suggests removed route segment config while `cacheComponents=true` | Fails on `dynamicParams`, `dynamic`, `revalidate`, or `fetchCache` recommendations |
+| 17a | `next_route_revalidate_static_prereq` | Rec suggests route-level `export const revalidate` for a Next.js page/layout route | Fails when the route chain contains request-time APIs or common auth helpers that can force dynamic rendering |
+| 18 | `next_cache_lifetime_freshness_supported` | Rec lengthens a tagged Cache Components lifetime with `cacheLife()` | Fails unless every affected `cacheTag()` has matching `revalidateTag()` / `updateTag()` evidence |
+| 19 | `next_cache_life_cdn_header_semantics` | Rec claims `cacheLife()` emits CDN/Cache-Control headers or that missing `cacheLife()` alone makes a route run per request | Fails unless rewritten to the documented Cache Components lifetime behavior or backed by production header evidence |
+| 20 | `next_cache_tag_invalidation_supported` | Cache-lifetime rec claims existing tag invalidation | Fails unless every claimed `cacheTag()` has matching `revalidateTag()` / `updateTag()` evidence |
+| 21 | `cache_rec_not_error_dominated_or_acknowledged` | CDN cache rec targets a route with function 5xx metrics | Fails unless the rec excludes or acknowledges error traffic |
+| 22 | `cache_control_header_syntax` | CDN cache rec includes `Cache-Control`, `CDN-Cache-Control`, or `Vercel-CDN-Cache-Control` values | Fails on empty directives such as a trailing comma |
+| 23 | `cache_policy_positive_or_no_ready_rec` | Cache candidate emits a ready recommendation | Fails unless it names a positive cache policy; no-store-only belongs in no-change/observation output |
+| 24 | `cache_404_long_ttl_safety` | CDN cache rec mentions a 404 or not-found branch | Fails unless the rec keeps the 404/not-found branch uncached, short-lived, or explicitly separate |
+| 25 | `immutable_dynamic_route_safety` | Dynamic route rec uses browser `immutable` caching | Fails unless the URL is byte-versioned or the directive is scoped to Vercel's CDN |
+| 26 | `auth_guard_parallelization_safety` | Parallelization rec touches private/auth/ownership data | Fails if private data can be fetched before the auth or ownership guard |
+| 27 | `parallelization_impact_not_overclaimed` | Parallelization rec promises a helper-sized latency drop | Fails unless helper/span timing was measured |
+| 28 | `parallelization_not_cpu_bound_work` | Parallelization rec targets CPU or compile work | Fails unless measured wait/I/O time proves there is independent work to overlap |
+| 29 | `runtime_error_cause_supported` | Route-error rec names a runtime exception/root cause | Fails unless runtime logs or stack evidence support the cause |
+| 30 | `turbo_build_cache_safety` | Rec enables Turbo build caching | Fails when the package build script has migration side effects or Turbo outputs omit framework build output |
+
+Verifier guards:
+
+- **`snippet_in_wrong_file`**: code snippet found, but in a different file from the cited path → disposition `unsupported` (don't fail the rec; the LLM was close, but the source file claim is wrong).
+- **`line-number-as-count`**: "filename:42" matched against a `pattern_count` claim → skip; this is a line-number, not a count.
+- **`prose-of-absence`**: "no cache headers" without an explicit grep confirmation → `unsupported`; absence claims require evidence.
+- **`pattern_count` for abstracted DB calls**: `db.method()` in a file with DB imports + await helpers but literal count 0 → `unsupported` (import-chain resolution is out of scope).
+
+## Dispositions
+
+Each verified claim resolves to one of four states:
+
+| Disposition | Meaning | Counted toward `passRate`? |
+|---|---|---|
+| `verified` | Claim matches reality | yes (counts as pass) |
+| `failed` | Claim contradicts reality | yes (counts as fail) |
+| `unsupported` | Claim can't be checked mechanically (see guards above) | no |
+| `unverifiable` | Out of scope (e.g., external API behavior, runtime-only) | no |
+
+`passRate = verified / (verified + failed)`. Unsupported and unverifiable don't count either way.
+
+## Re-gen trigger and accept criteria
+
+After verification:
+
+| Condition | Action |
+|---|---|
+| `passRate < 0.8 AND verifiableClaimCount >= 2` | Re-run Step 3.3 (the recommender) with `topFailures` injected as feedback |
+| Project-config contradiction, cache-safety failure, or framework-semantic failure | Hard re-run. The customer report holds back the original rec until re-gen fixes it or abstains |
+| `passRate >= 0.8` OR `verifiableClaimCount < 2` | Accept the run, proceed to Step 4 |
+
+_(Floor lowered 5 → 2 in May 2026 audit: a rec with 1/1 failed claim is just as broken as 1/5, and the old floor let many small recs escape re-gen entirely.)_
+
+Re-gen accept criteria:
+
+- `regenPassRate >= originalPassRate` AND
+- Rec count not gutted (regen doesn't drop more than 50% of recs) AND
+- Findings still cited (no rec orphaning)
+
+If re-gen makes things worse, keep the original output unless the trigger was hard safety (`project_config_contradiction`, `cache_vary_safety`, or `semantic_safety`). Hard-safety failures must not ship to the customer report.
+
+## Verifier implementation
+
+`scripts/verify-and-regen.mjs` invokes `lib/extract-claims.mjs` and `lib/verify-claim.mjs` in-process for each verifiable claim. Pure functions, no network, no LLM — deterministic.
+
+For `citation_in_library` and `citation_applies_to_version`, the script uses `lib/citations.mjs`'s `isKnownUrl()` and `sanitizeCitations()` helpers (already tested). For everything else, it shells out to grep + ast-grep via execFile.

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

@@ -0,0 +1,76 @@
+# Voice
+
+Use Vercel's customer-facing voice: sharp teammate, clear, competent, no fluff.
+
+Write for a user deciding what to fix next. Lead with the observed signal, the specific change, and how to verify it. Do not explain the skill's internals unless the user asked for debug details.
+
+## Rules
+
+- Use plain words. Prefer "use" over "leverage," "reduce" over "optimize" when the action is specific.
+- Be direct. No apologetic preambles, no marketing language, no "For context" wrap-up paragraphs.
+- Keep every recommendation tied to a route, file, metric, or project setting.
+- Use observed numbers only. Never invent savings, traffic, latency, or percentages.
+- Use cost magnitude language, not precise savings: "hundreds of dollars per month at current traffic," not "$340/mo."
+- Use precise performance language when measured: "95th percentile duration is 1,240ms."
+- Frame prerequisites as engineering constraints, not upsells. Explain the decision impact: what the missing data prevents, what the limited fallback can still do, and what the user should choose next.
+- Use short bullets and tables. Avoid long paragraphs in reports and final chat messages.
+- Write full sentences with punctuation in reports.
+
+## Avoid
+
+- `seamlessly`, `effortlessly`, `powerful`, `robust`, `leverage`, `unleash`, `blazing`, `lightning-fast`, `turnkey`, `holistic`, `best-in-class`, `next-generation`, `cutting-edge`, `world-class`, `streamline`, `elevate`, `harness`, `crafted`, `myriad`, `plethora`, `empower`, `utilize`
+- Filler adverbs: `just`, `simply`, `actually`
+- Hedge starts: `Consider`, `You may want to`, `It is important to note`
+- Rhetorical reframes: `It's not X, it's Y`
+- Unicode arrows in prose: `->`, `→`, `⇒`
+- Internal process terms in customer output: `sub-agent`, `abstention`, `abstained`, `passRate`, `quality score`, `sanitizer`
+
+Use customer-facing replacements:
+
+| Internal | Customer-facing |
+|---|---|
+| `sub-agent` | `investigation` |
+| `abstained` | `found no supported change` |
+| `abstention` | `investigated, no change recommended` |
+| `passRate` | `verification result` |
+| `quality score` | `review result` |
+| `inv` | `function invocations` or `requests`, based on the metric |
+| `p95` | `95th percentile` |
+| `perf` | `performance` |
+| `CWV` | `Core Web Vitals` |
+
+## Product names
+
+Use these spellings:
+
+| Right | Wrong |
+|---|---|
+| `Observability Plus` | `OPlus`, `Oplus`, `O11y Plus`, `o11y+`, `obs+` |
+| `Vercel Functions` | `serverless functions` when referring to Vercel's product |
+| `fluid compute` mid-sentence | `Fluid Compute` mid-sentence |
+| `BotID` | `Bot ID`, `botID` |
+| `AI Gateway` | `Vercel AI Gateway`, `ai gateway` |
+| `AI SDK` | `Vercel AI SDK` |
+| `Edge Config` | `EdgeConfig` |
+| `Routing Middleware` | `Edge Middleware` |
+| `Web Analytics` | `Vercel Analytics` |
+| `Hobby`, `Pro`, `Enterprise` | `hobby`, `pro`, `enterprise` as plan names |
+
+Mirror billing names from the user's dashboard. If a dashboard still says `Edge Requests`, use `Edge Requests`; do not rename it.
+
+## Recommendation shape
+
+| Field | Pattern |
+|---|---|
+| `what` | Verb + change + scope. Example: `Add shared caching to /api/products`. |
+| `why` | State the metric and code evidence. Example: `The route handled 1,200,000 requests with a 0% cache hit rate; src/app/api/products/route.ts returns no Cache-Control header.` |
+| `fix` | Numbered steps. Start each step with a verb. |
+| `verify` | Tell the user exactly which metric or command to re-check. |
+
+Good:
+
+> Add `Cache-Control: s-maxage=300, stale-while-revalidate=86400` to `/api/products`. The route handled 1,200,000 GET requests with a 0% cache hit rate.
+
+Bad:
+
+> Consider leveraging a robust caching strategy to unlock better performance.

package/bundled-skills/vercel-optimize/scripts/budget-summary.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Mid-flow checkpoint: should the orchestrator ask the user to raise the budget?
+// JSON output is the contract the orchestrator parses; markdown is human-only.
+
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { buildBudgetSummary, renderBudgetSummaryMarkdown } from '../lib/budget-summary.mjs';
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.gatePath) {
+    console.error('usage: node scripts/budget-summary.mjs <gate.json> [--format json|markdown] [--no-prompt]');
+    process.exit(1);
+  }
+  const gate = JSON.parse(await readFile(args.gatePath, 'utf-8'));
+  const summary = buildBudgetSummary(gate);
+  // --no-prompt: CI / non-interactive hosts collapse the checkpoint to a logging hop.
+  if (args.noPrompt) {
+    summary.shouldAsk = false;
+    summary.reason = 'forced false via --no-prompt (non-interactive host)';
+    summary.printContract = null;
+    summary.questionText = '';
+    summary.questionPayload = null;
+    summary.options = [];
+    summary.chatPreview = `Audit scope: no question needed — ${summary.reason}.`;
+    summary.exactChatMessage = {
+      body: summary.chatPreview,
+      lineCount: summary.chatPreview.split('\n').length,
+      sha256: createHash('sha256').update(summary.chatPreview).digest('hex'),
+    };
+    summary.printCheck = null;
+  }
+  if (args.format === 'markdown') {
+    process.stdout.write(renderBudgetSummaryMarkdown(summary) + '\n');
+  } else {
+    process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+  }
+}
+
+function parseArgs(argv) {
+  const out = { positional: [], format: 'json' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--format') out.format = argv[++i];
+    else if (a.startsWith('--format=')) out.format = a.slice('--format='.length);
+    else if (a === '--no-prompt') out.noPrompt = true;
+    else out.positional.push(a);
+  }
+  out.gatePath = out.positional[0];
+  return out;
+}
+
+main().catch((err) => {
+  console.error('[budget-summary] FAILED:', err.message);
+  process.exit(1);
+});