opencode-skills-collection 3.0.35 → 3.0.37

package/bundled-skills/vercel-optimize/references/support-topics/README.md

@@ -0,0 +1,46 @@
+# Support Topics
+
+Support topics are small, candidate-scoped investigation guardrails injected into sub-agent briefs.
+
+They are not recommendations, gates, scanners, or broad documentation. A topic tells the investigator what evidence to check, what false positives to avoid, and when to abstain for one class of candidate.
+
+## Add A Topic
+
+Add one file: `references/support-topics/<id>.md`.
+
+The filename must match the `id`. Frontmatter uses a strict subset of YAML: one `key: value` per line, arrays as JSON arrays.
+
+```md
+---
+id: cdn-cache-auth-safety
+title: CDN cache auth safety
+status: active
+candidateKinds: ["uncached_route", "cache_header_gap"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/caching/cdn-cache"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+...
+
+## Evidence To Check
+...
+
+## Do Not Recommend When
+...
+
+## Verification
+...
+```
+
+## Rules
+
+- Every active topic must cite only URLs or skill-rule refs already present in `references/docs-library.json`.
+- Use `candidateKinds` to keep the topic narrow. Use `"*"` only for workflow/protocol topics that truly apply to every candidate.
+- Use optional `metrics` only when a topic applies to a specific candidate metric, such as `["LCP"]`, `["INP"]`, or `["CLS"]` for Core Web Vitals.
+- Use optional `routePatterns` as JavaScript regex source strings when a topic should appear only for specific candidate routes, such as `["(^|/)404$"]`.
+- Keep the body below `maxBriefChars`; the brief renderer caps selected topics before they reach the sub-agent.
+- Put URLs in frontmatter only. Topic bodies should describe checks and guardrails, not cite new sources.
+- Do not include internal repository paths, service names, pricing tables, exact savings claims, or framework APIs without version gating.

package/bundled-skills/vercel-optimize/references/support-topics/astro-edge-middleware-scope.md

@@ -0,0 +1,22 @@
+---
+id: astro-edge-middleware-scope
+title: Astro edge middleware scope
+status: active
+candidateKinds: ["middleware_heavy"]
+frameworks: ["astro@*"]
+priority: 88
+citations: ["https://vercel.com/docs/frameworks/frontend/astro", "https://docs.astro.build/en/guides/integrations-guide/vercel/"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+Astro middleware can run at the edge for broad request sets. If middleware volume is high, prove which paths actually need interception.
+
+## Evidence To Check
+Use middleware invocation share and top paths. Inspect adapter middleware mode, middleware source, auth/redirect logic, and whether static assets, prerendered pages, or public pages are being intercepted.
+
+## Do Not Recommend When
+Do not bypass required auth, locale, header, or routing logic. Do not move global middleware work into every page when the current scope is already minimal.
+
+## Verification
+Name the middleware share, dominant paths, current middleware mode, and exact source or config line to narrow.

package/bundled-skills/vercel-optimize/references/support-topics/astro-output-mode-and-isr.md

@@ -0,0 +1,22 @@
+---
+id: astro-output-mode-and-isr
+title: Astro output mode and ISR
+status: active
+candidateKinds: ["uncached_route", "rendering_candidate"]
+frameworks: ["astro@*"]
+priority: 90
+citations: ["https://vercel.com/docs/frameworks/frontend/astro", "https://docs.astro.build/en/guides/on-demand-rendering/", "https://docs.astro.build/en/reference/configuration-reference/"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Astro defaults to static output; `server` output makes pages render on demand unless route-level prerendering changes that. First decide whether the hot route truly needs SSR.
+
+## Evidence To Check
+Inspect `astro.config`, adapter options, `output`, route-level `prerender`, dynamic params, middleware, and whether the content is shared across visitors. Compare route cache result and request volume.
+
+## Do Not Recommend When
+Do not prerender or cache personalized, preview, cart, checkout, or auth-gated pages. Do not change output mode for the whole app when one route-level flag is enough.
+
+## Verification
+Name the Astro output mode, route-level prerender state, observed route signal, and exact config or page line.

package/bundled-skills/vercel-optimize/references/support-topics/auth-preserving-parallelization.md

@@ -0,0 +1,22 @@
+---
+id: auth-preserving-parallelization
+title: Authorization-preserving parallelization
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["*"]
+priority: 90
+citations: ["vercel-react-best-practices:async-parallel", "vercel-react-best-practices:server-parallel-fetching"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Parallelizing awaits is safe only when it does not move private data access ahead of the auth, ownership, tenant, or permission check protecting that data.
+
+## Evidence To Check
+List every awaited operation being reordered. If a private lookup currently runs after `getSession()`, an ownership query, a tenant check, or a redirect guard, prove the lookup itself enforces the same predicate before recommending `Promise.all`.
+
+## Do Not Recommend When
+Do not parallelize a private record fetch with the ownership check that authorizes that fetch. Instead, recommend combining the guard and data lookup into one query constrained by the authenticated user, tenant, or ownership key.
+
+## Verification
+The fix must preserve the sequential guard or replace it with a single authorized query. Do not promise a latency drop equal to a helper unless that helper duration was measured.

package/bundled-skills/vercel-optimize/references/support-topics/bot-protection-product-guardrails.md

@@ -0,0 +1,22 @@
+---
+id: bot-protection-product-guardrails
+title: Bot Protection product guardrails
+status: active
+candidateKinds: ["platform_bot_protection"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/bot-management", "https://vercel.com/docs/vercel-firewall/vercel-waf/managed-rulesets", "https://vercel.com/docs/vercel-firewall/vercel-waf/custom-rules", "https://vercel.com/docs/botid"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+Bot Protection recommendations must be grounded in observed automated traffic or meaningful edge-request scale.
+
+## Evidence To Check
+Check bot bandwidth share, edge request volume, existing WAF managed rules, and whether BotID or Bot Protection is already enabled. Prefer a staged Log to Challenge or Deny path for rules whose false-positive risk is not proven.
+
+## Do Not Recommend When
+Do not recommend disabling Vercel security products to reduce cost. Do not recommend Bot Protection for quiet projects with no bot evidence.
+
+## Verification
+State the observed bot share or scale signal, current protection state, and any existing log, challenge, deny, or BotID check.

package/bundled-skills/vercel-optimize/references/support-topics/build-minutes-monorepo-fanout.md

@@ -0,0 +1,23 @@
+---
+id: build-minutes-monorepo-fanout
+title: Build Minutes monorepo fanout
+status: active
+candidateKinds: ["build_minutes_fanout"]
+frameworks: ["*"]
+scannerPatterns: ["turbo-force-bypass"]
+priority: 90
+citations: ["https://vercel.com/docs/monorepos", "https://vercel.com/docs/builds", "https://turborepo.dev/docs/crafting-your-repository/caching"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Build Minutes climbs when commits rebuild unchanged work. Common causes: `TURBO_FORCE`, `cache: false`, missing outputs, or disabled build-skip settings.
+
+## Evidence To Check
+Confirm Build Minutes share and scanner subtype. Inspect `package.json`, `turbo.json`, outputs, `.gitignore`, `vercel.json`, and project settings. If `build` runs migrations, split them into an uncached step before recommending Turbo build caching.
+
+## Do Not Recommend When
+Skip under 5% bill share with no scanner finding. Skip single-project repos and intentional CI-only force flags. Do not recommend `ignoreCommand` from repo grep alone; dashboard-only skip-unaffected may be better.
+
+## Verification
+Name the offending file and pattern. Recommend only the verified fix: cache a pure build task, add generated `outputs`, enable skip-unaffected builds, or add `ignoreCommand` only when needed.

package/bundled-skills/vercel-optimize/references/support-topics/cache-components-static-shell-boundaries.md

@@ -0,0 +1,22 @@
+---
+id: cache-components-static-shell-boundaries
+title: Cache Components static shell boundaries
+status: active
+candidateKinds: ["rendering_candidate"]
+frameworks: ["next@>=16.0.0"]
+priority: 94
+citations: ["https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents", "https://nextjs.org/docs/app/getting-started/caching", "https://nextjs.org/docs/app/guides/migrating-to-cache-components"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+On Next.js 16 with Cache Components, avoid older segment-config advice. The right question is whether the route can keep a static shell while dynamic data moves behind explicit cached or runtime boundaries.
+
+## Evidence To Check
+Check `cacheComponents`, `use cache`, `cacheLife`, request-time APIs, Suspense boundaries, and scanner evidence such as `force-dynamic` or `headers-in-page`.
+
+## Do Not Recommend When
+Do not suggest `dynamic`, `revalidate`, or `fetchCache` as the primary fix when Cache Components is enabled. Do not cache request-personalized content.
+
+## Verification
+Name the Next.js version, Cache Components state, dynamic trigger, and the exact boundary or directive that can change.

package/bundled-skills/vercel-optimize/references/support-topics/cache-components-suspense-dedupe-pitfall.md

@@ -0,0 +1,23 @@
+---
+id: cache-components-suspense-dedupe-pitfall
+title: Cache Components Suspense dedupe pitfall
+status: active
+candidateKinds: ["cache_components_suspense_dedupe"]
+frameworks: ["next@>=16.0.0"]
+scannerPatterns: ["cache-components-suspense-dedupe"]
+priority: 87
+citations: ["https://nextjs.org/docs/app/api-reference/directives/use-cache", "https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents", "https://nextjs.org/docs/app/guides/migrating-to-cache-components"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Default `'use cache'` does not dedupe identical calls across separate `<Suspense>` boundaries on the same render. Each boundary re-invokes the cached function, multiplying function-duration and ISR write churn.
+
+## Evidence To Check
+Confirm the scanner finding's repeated fetch URL or helper name. Verify the call sites are within the same route segment and inside distinct `<Suspense>` boundaries. Cross-reference `fnDurationP95ByRoute` and `isrWritesByRoute` for the owning route.
+
+## Do Not Recommend When
+Skip if the repeated call is intentional (different parameters, different intent). Skip if the duplicate is in a single component body where in-request memoization already applies.
+
+## Verification
+Name the duplicated call, count, and either: (a) the page-level promise to hoist or (b) the function to move to `'use cache: remote'`.

package/bundled-skills/vercel-optimize/references/support-topics/cdn-cache-auth-safety.md

@@ -0,0 +1,22 @@
+---
+id: cdn-cache-auth-safety
+title: CDN cache auth safety
+status: active
+candidateKinds: ["uncached_route", "cache_header_gap"]
+frameworks: ["*"]
+priority: 100
+citations: ["https://vercel.com/docs/caching/cdn-cache", "https://vercel.com/docs/caching/cache-control-headers", "https://vercel.com/docs/project-configuration"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Treat edge caching as a safety question first. The route must be a public, cacheable GET path before a shared-cache recommendation is allowed.
+
+## Evidence To Check
+Use `methodDistribution`, `cacheBreakdown`, and headers. Before `s-maxage`, rule out cookies, sessions, authorization, draft state, and user-specific data.
+
+## Do Not Recommend When
+Do not cache mutations, dashboards, account data, request-personalized responses, or routes whose value changes per viewer. Do not mix `private` with shared-cache directives.
+
+## Verification
+Name GET share, cache mix, file line, and policy: mechanism, scope, TTL/freshness, and `Vary`. If the right policy is `no-store`, emit no-change/observation.

package/bundled-skills/vercel-optimize/references/support-topics/cold-start-initialization-bundle.md

@@ -0,0 +1,22 @@
+---
+id: cold-start-initialization-bundle
+title: Cold-start initialization and bundle weight
+status: active
+candidateKinds: ["cold_start"]
+frameworks: ["*"]
+priority: 92
+citations: ["https://vercel.com/docs/functions/debug-slow-functions", "https://vercel.com/docs/functions/limitations", "https://vercel.com/docs/functions/runtimes"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Cold-start candidates need a code-path check, not only a project-setting check. First prove whether cold requests are paying for imports, module-scope setup, runtime choice, or dependency weight.
+
+## Evidence To Check
+Use `startTypeSplit`, `coldVsWarmLatencyP95`, and `coldByDeployment`. In source, inspect module-scope SDK setup, database/client construction, top-level network calls, heavy dependencies, runtime exports, and deployment-local changes.
+
+## Do Not Recommend When
+Do not blame cold starts when warm requests are similarly slow. Do not recommend keep-warm traffic or more memory before proving initialization or runtime pressure.
+
+## Verification
+Name the cold-start share, cold-vs-warm gap, and exact initialization, dependency, or runtime line that explains it.

package/bundled-skills/vercel-optimize/references/support-topics/core-web-vitals-client-bottlenecks.md

@@ -0,0 +1,22 @@
+---
+id: core-web-vitals-client-bottlenecks
+title: Core Web Vitals client bottlenecks
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/speed-insights", "https://web.dev/articles/vitals", "https://web.dev/articles/optimize-lcp", "https://web.dev/articles/optimize-inp", "https://web.dev/articles/optimize-cls"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Core Web Vitals candidates need metric-specific investigation. LCP, INP, and CLS usually have different causes and fixes.
+
+## Evidence To Check
+Use the poor metric in the deep dive first. For LCP, inspect server response and critical media. For INP, inspect heavy client JavaScript and interaction handlers. For CLS, inspect dimensions, fonts, and injected content.
+
+## Do Not Recommend When
+Do not emit a generic “improve Web Vitals” recommendation. Do not optimize a metric that is not poor for this route.
+
+## Verification
+Name the poor p75 metric, its value, and the exact source mechanism behind that metric.

package/bundled-skills/vercel-optimize/references/support-topics/database-egress-pooling-region.md

@@ -0,0 +1,22 @@
+---
+id: database-egress-pooling-region
+title: Database region and connection pressure
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["*"]
+priority: 60
+citations: ["https://vercel.com/docs/regions", "https://vercel.com/docs/functions", "https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package", "https://vercel.com/docs/functions/limitations"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+Only recommend database or region changes when source and metrics both point to downstream I/O rather than in-process compute.
+
+## Evidence To Check
+Compare `cpu.p95` with `latency.p95`, then inspect database awaits, query fan-out, connection creation, pool lifecycle handling, and configured regions in project files.
+
+## Do Not Recommend When
+Do not name a database provider, pooling product, or region change unless the repo and project config prove it applies.
+
+## Verification
+Tie the finding to the observed wall-clock gap and the exact query, pool, or region configuration line.

package/bundled-skills/vercel-optimize/references/support-topics/dynamic-rendering-traps.md

@@ -0,0 +1,22 @@
+---
+id: dynamic-rendering-traps
+title: Dynamic rendering traps
+status: active
+candidateKinds: ["rendering_candidate"]
+frameworks: ["next@>=13.0.0"]
+priority: 90
+citations: ["https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config", "https://nextjs.org/docs/app/api-reference/functions/generate-static-params", "https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Rendering candidates are only actionable when the dynamic behavior is accidental. First prove that the route can be static, ISR, or partially static.
+
+## Evidence To Check
+Inspect `dynamic`, `revalidate`, `generateStaticParams`, route params, and dynamic APIs such as request headers or cookies. Check whether the dynamic call is in a layout, because that can affect a larger route tree.
+
+## Do Not Recommend When
+Do not remove dynamic rendering for auth, personalization, draft mode, per-request redirects, or request-specific data.
+
+## Verification
+The recommendation must cite the dynamic trigger and explain why the target route can tolerate static or ISR behavior.

package/bundled-skills/vercel-optimize/references/support-topics/external-api-critical-path-platform.md

@@ -0,0 +1,22 @@
+---
+id: external-api-critical-path-platform
+title: Cross-framework external API critical path
+status: active
+candidateKinds: ["external_api_slow"]
+frameworks: ["*"]
+priority: 86
+citations: ["https://vercel.com/docs/functions/debug-slow-functions", "https://vercel.com/docs/caching/runtime-cache", "https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+External API candidates are actionable only when the slow hostname is on a customer route's critical path. Prove the route waits on it before suggesting a cache, payload, or post-response change.
+
+## Evidence To Check
+Use hostname latency, caller routes, transfer bytes, and source awaits. Check sequential calls, overbroad payloads, repeated shared data, and side effects that can move after the response.
+
+## Do Not Recommend When
+Do not cache mutations, secrets, per-user responses, or unknown freshness contracts. Do not blame Vercel runtime when the upstream owns the latency.
+
+## Verification
+Name the hostname, caller route, observed p75/p95 or bytes, and exact await or fetch line that blocks the response.

package/bundled-skills/vercel-optimize/references/support-topics/external-api-critical-path.md

@@ -0,0 +1,22 @@
+---
+id: external-api-critical-path
+title: External API critical path
+status: active
+candidateKinds: ["external_api_slow"]
+frameworks: ["next@>=13.0.0"]
+priority: 90
+citations: ["vercel-react-best-practices:async-parallel", "vercel-react-best-practices:server-parallel-fetching", "vercel-react-best-practices:server-cache-react"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For external API candidates, identify the customer route that waits on the slow hostname and whether the call is on the critical path.
+
+## Evidence To Check
+Use callers-by-route evidence, transfer size, and source awaits. Check whether the upstream call can run in parallel, be cached safely, be reduced in payload size, or move after response.
+
+## Do Not Recommend When
+Do not cache mutations, secrets, per-user responses, or upstream calls whose freshness requirement is unknown.
+
+## Verification
+Name the hostname, caller route, p75 or p95 latency, and the exact source line that waits on the call.

package/bundled-skills/vercel-optimize/references/support-topics/fast-data-transfer-payloads.md

@@ -0,0 +1,22 @@
+---
+id: fast-data-transfer-payloads
+title: Fast Data Transfer payloads
+status: active
+candidateKinds: ["uncached_route"]
+frameworks: ["*"]
+priority: 65
+citations: ["https://vercel.com/docs/manage-cdn-usage", "https://vercel.com/docs/caching/cdn-cache"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+When uncached routes carry high bandwidth, check payload shape before recommending only cache headers. Fast Data Transfer includes the bytes transferred by requests and responses; compare compressed response sizes to the signal, not raw JSON.
+
+## Evidence To Check
+Use `bandwidthByCache`, response size, and source serialization. Look for unbounded JSON, large embedded objects, static files through functions, missing pagination.
+
+## Do Not Recommend When
+Do not shrink payloads without identifying fields or assets that are unnecessary for the route’s response.
+
+## Verification
+Tie the finding to observed bytes, cache result mix, and the exact response line. A "large payload" claim must reflect post-compression bytes — the unit FDT meters.

package/bundled-skills/vercel-optimize/references/support-topics/fluid-compute-caveats.md

@@ -0,0 +1,22 @@
+---
+id: fluid-compute-caveats
+title: Fluid compute caveats
+status: active
+candidateKinds: ["platform_fluid_compute", "cold_start"]
+frameworks: ["*"]
+priority: 80
+citations: ["https://vercel.com/docs/fluid-compute"]
+maxBriefChars: 900
+---
+
+## Investigation Brief
+Fluid compute is a project-level lever. Use it when the setting is off and metrics show cold-start or warm-instance reuse pressure. Fluid can handle multiple invocations in one function instance; avoid per-request state in module scope.
+
+## Evidence To Check
+Check project facts, `startTypeSplit`, cold-vs-warm latency, and routes carrying the cold-start share. When enabling Fluid, audit module-state hazards Fluid surfaces (not creates): module-scoped mutable state, lazy singletons holding per-user data, globals keyed on per-request inputs.
+
+## Do Not Recommend When
+Do not recommend enabling fluid compute when project facts say it is already on. Do not frame as a file-level code fix.
+
+## Verification
+State project setting, cold-start rate or fallback slow-route signal, affected route concentration. If enabling, call out module-state audit as follow-up.

package/bundled-skills/vercel-optimize/references/support-topics/function-duration-io-and-after.md

@@ -0,0 +1,22 @@
+---
+id: function-duration-io-and-after
+title: Function duration, I/O, and post-response work
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["next@>=15.0.0"]
+priority: 75
+citations: ["https://nextjs.org/docs/app/api-reference/functions/after", "vercel-react-best-practices:async-parallel", "vercel-react-best-practices:server-after-nonblocking"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+When wall-clock latency is much higher than CPU time, check critical-path awaits before blaming rendering or compute.
+
+## Evidence To Check
+Compare `cpu.p95`, `ttfb.p95`, and `latency.p95`. In source, separate dependent awaits from independent awaits, and identify analytics, logging, or notification work that can run after the response.
+
+## Do Not Recommend When
+Do not wrap dependent operations in `Promise.all`. Do not replace `Promise.allSettled` when partial failure handling is intentional.
+
+## Verification
+Name the awaits that can move, the work that can run post-response, and the observed CPU-vs-wall-clock gap.

package/bundled-skills/vercel-optimize/references/support-topics/function-invocation-reduction.md

@@ -0,0 +1,22 @@
+---
+id: function-invocation-reduction
+title: Function invocation reduction
+status: active
+candidateKinds: ["slow_route"]
+frameworks: ["next@>=13.0.0"]
+priority: 70
+citations: ["https://react.dev/reference/react/cache", "vercel-react-best-practices:server-parallel-fetching", "vercel-react-best-practices:server-cache-react"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+For slow routes, prove duplicated in-request work in the listed files before recommending consolidation or memoization.
+
+## Evidence To Check
+Look for repeated awaits, duplicate fetches, same-app route handler calls, and helpers that run more than once per request.
+
+## Do Not Recommend When
+Do not collapse endpoints called independently by different clients. Do not persistently cache user-specific data. Do not recommend `Promise.all` for CPU-bound or compile-bound work unless trace/span evidence shows wait time to overlap. High `cpu.p95` near `latency.p95` is a warning sign, not proof of a latency win.
+
+## Verification
+Quote duplicated call sites with `latency.p95`, `cpu.p95`, or request-count evidence. If the fix overlaps awaits, cite measured helper/span timing or state the impact is unmeasured.

package/bundled-skills/vercel-optimize/references/support-topics/function-region-misconfiguration-ttfb.md

@@ -0,0 +1,23 @@
+---
+id: function-region-misconfiguration-ttfb
+title: Function region misconfiguration (TTFB)
+status: active
+candidateKinds: ["region_misconfig"]
+frameworks: ["*"]
+scannerPatterns: ["region-pin-in-config"]
+priority: 85
+citations: ["https://vercel.com/docs/functions/configuring-functions/region", "https://vercel.com/docs/regions"]
+maxBriefChars: 950
+---
+
+## Investigation Brief
+A single function region is pinned. Per-region TTFB data is unavailable today (`evidence.dataGap`); treat as an audit prompt — validate the pinned region against user geo and data-source location before recommending changes.
+
+## Evidence To Check
+Scanner subtype (`vercel-json-single`, `segment-preferred`) and pinned regions. Cross-check Speed Insights TTFB and country analytics for traffic geo. Locate the data source — proximity to it often wins on cache-miss paths.
+
+## Do Not Recommend When
+Skip if TTFB is healthy across countries. Skip if pinned intentionally for data proximity. Skip on small projects (<20 routes). Do not propose multi-region without confirming the data layer is reachable without cross-region egress.
+
+## Verification
+Name pinned region(s), traffic geo, data-source location, and a specific call: relocate, expand, or keep with a TTFB monitor.

package/bundled-skills/vercel-optimize/references/support-topics/image-optimization-cost-control.md

@@ -0,0 +1,22 @@
+---
+id: image-optimization-cost-control
+title: Image optimization cost control
+status: active
+candidateKinds: ["image_optimization"]
+frameworks: ["*"]
+priority: 90
+citations: ["https://vercel.com/docs/image-optimization", "https://vercel.com/docs/image-optimization/managing-image-optimization-costs", "https://vercel.com/docs/image-optimization/limits-and-pricing"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Image recommendations should distinguish real user-facing image work from wasteful transformations.
+
+## Evidence To Check
+Inspect the sampled files for raw image tags, dimensions, remote sources, repeated transforms, source image limits, icons, SVGs, GIFs, and existing framework image components.
+
+## Do Not Recommend When
+Do not route tiny icons, SVG UI assets, or animated GIFs through image optimization just because they are images. Do not change remote-source policy without checking the existing config.
+
+## Verification
+Name the image files or components, current rendering path, and the metric or scanner evidence that makes optimization material.

package/bundled-skills/vercel-optimize/references/support-topics/isr-revalidation-static-generation.md

@@ -0,0 +1,22 @@
+---
+id: isr-revalidation-static-generation
+title: ISR revalidation and static generation
+status: active
+candidateKinds: ["isr_overrevalidation"]
+frameworks: ["next@>=13.4.0"]
+priority: 95
+citations: ["https://vercel.com/docs/incremental-static-regeneration", "https://nextjs.org/docs/app/api-reference/functions/revalidateTag", "https://nextjs.org/docs/app/api-reference/functions/revalidatePath"]
+maxBriefChars: 1000
+---
+
+## Investigation Brief
+For ISR over-revalidation, the goal is to reduce unnecessary regeneration work without making content stale beyond the product’s tolerance.
+
+## Evidence To Check
+Compare ISR writes to reads, then inspect the route’s `revalidate`, `cacheLife()`, tag invalidation, and content update path. Look for very short timer revalidation on routes where updates are event-driven. If recommending `cacheLife()` or `cacheTag()` for tagged content, prove the exact tags are invalidated by `revalidateTag()` or `updateTag()`; near-matches do not count.
+
+## Do Not Recommend When
+Do not lengthen revalidation for inventory, pricing, auth, or other user-critical freshness without source evidence that stale content is acceptable. Do not claim existing CMS or webhook invalidation unless the matching invalidation call or config is in the allowed files.
+
+## Verification
+Tie the fix to the observed ISR writes per read and the line that controls revalidation or on-demand invalidation.

package/bundled-skills/vercel-optimize/references/support-topics/middleware-proxy-edge-cost.md

@@ -0,0 +1,22 @@
+---
+id: middleware-proxy-edge-cost
+title: Middleware edge cost
+status: active
+candidateKinds: ["middleware_heavy"]
+frameworks: ["next@>=12.0.0"]
+priority: 90
+citations: ["https://nextjs.org/docs/app/building-your-application/routing/middleware", "https://vercel.com/docs/routing-middleware"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Middleware recommendations should reduce unnecessary interception, not remove required request handling.
+
+## Evidence To Check
+Use `topMiddlewarePaths` and the matcher config. Confirm which paths need auth, rewrites, headers, or locale handling. Check whether static assets, images, or routes with no middleware need are being matched.
+
+## Do Not Recommend When
+Do not narrow the matcher in a way that bypasses required auth or routing behavior. Do not move middleware work into every route if the current matcher is already scoped.
+
+## Verification
+State the current middleware share, the dominant matched paths, and the exact matcher line to change.

package/bundled-skills/vercel-optimize/references/support-topics/next-fetch-revalidate-floor.md

@@ -0,0 +1,22 @@
+---
+id: next-fetch-revalidate-floor
+title: Next.js fetch revalidation floor
+status: active
+candidateKinds: ["uncached_route", "isr_overrevalidation"]
+frameworks: ["next@>=13.0.0"]
+priority: 88
+citations: ["https://nextjs.org/docs/app/api-reference/functions/fetch", "https://nextjs.org/docs/app/building-your-application/caching"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Next.js `fetch` options can set the route's effective cache floor. Low `revalidate`, `revalidate: 0`, or `cache: 'no-store'` can explain uncached traffic and excessive ISR work.
+
+## Evidence To Check
+Inspect route-tree `fetch` calls. Compare route revalidation with per-fetch `cache`, `next.revalidate`, tags, dynamic APIs, and duplicated URLs with conflicting options.
+
+## Do Not Recommend When
+Do not raise freshness windows for pricing, inventory, auth, draft, or user-specific data unless the source proves stale reads are acceptable.
+
+## Verification
+Name the observed cache or ISR signal, the lowest cache setting that controls the route, and the exact fetch line to change.

package/bundled-skills/vercel-optimize/references/support-topics/next-font-cls-self-hosting.md

@@ -0,0 +1,23 @@
+---
+id: next-font-cls-self-hosting
+title: Next.js font CLS guardrail
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["next@>=13.2.0"]
+metrics: ["CLS"]
+priority: 86
+citations: ["https://nextjs.org/docs/app/api-reference/components/font", "https://web.dev/articles/optimize-cls"]
+maxBriefChars: 800
+---
+
+## Investigation Brief
+For poor CLS, check fonts only when the route actually loads external font CSS or swaps text after render.
+
+## Evidence To Check
+Inspect layouts and global styles for external font links, CSS imports, custom font-face rules, late-loading font classes, and whether `next/font` is already used.
+
+## Do Not Recommend When
+Do not migrate fonts when CLS is caused by images, ads, embeds, or injected UI. Do not suggest `next/font` for unsupported Next.js versions.
+
+## Verification
+Name the CLS value, font-loading mechanism, and the exact layout or stylesheet line to change.

package/bundled-skills/vercel-optimize/references/support-topics/next-heavy-ui-lazy-load-boundaries.md

@@ -0,0 +1,23 @@
+---
+id: next-heavy-ui-lazy-load-boundaries
+title: Next.js heavy UI lazy-load boundaries
+status: active
+candidateKinds: ["cwv_poor"]
+frameworks: ["next@*"]
+metrics: ["LCP", "INP"]
+priority: 82
+citations: ["https://nextjs.org/docs/app/guides/lazy-loading", "https://web.dev/articles/optimize-inp"]
+maxBriefChars: 850
+---
+
+## Investigation Brief
+Heavy above-the-fold or rarely used UI can hurt LCP and INP when it ships too much JavaScript on first load. Look for concrete route-local UI, not generic bundle advice.
+
+## Evidence To Check
+Inspect client components, menus, search overlays, personalization widgets, maps, editors, and large imported libraries. Check whether they can load on interaction, viewport, or route entry with `next/dynamic` or dynamic import.
+
+## Do Not Recommend When
+Do not lazy-load essential above-the-fold content needed for initial meaning or accessibility. Do not use `ssr: false` from a Server Component.
+
+## Verification
+Name the poor metric, heavy UI boundary, imported library or component, and exact line to split.