@oriro/orirocli 0.1.0

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

@@ -0,0 +1,33 @@
+---
+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/skills/craft/vercel-optimize/references/support-topics/route-error-runtime-limits.md

@@ -0,0 +1,31 @@
+---
+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/skills/craft/vercel-optimize/references/support-topics/runtime-cache-reusable-data.md

@@ -0,0 +1,30 @@
+---
+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/skills/craft/vercel-optimize/references/support-topics/sveltekit-isr-prerender-safety.md

@@ -0,0 +1,31 @@
+---
+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/skills/craft/vercel-optimize/references/support-topics/sveltekit-split-cold-start-tradeoff.md

@@ -0,0 +1,30 @@
+---
+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/skills/craft/vercel-optimize/references/support-topics/usage-spike-triage.md

@@ -0,0 +1,31 @@
+---
+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/skills/craft/vercel-optimize/references/support-topics/use-cache-date-stamp-isr-write-amplifier.md

@@ -0,0 +1,31 @@
+---
+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/skills/craft/vercel-optimize/references/support-topics/use-cache-remote-shared-origin-data.md

@@ -0,0 +1,30 @@
+---
+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/skills/craft/vercel-optimize/references/support-topics/workflow-resumable-stream-routes.md

@@ -0,0 +1,32 @@
+---
+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/skills/craft/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/skills/craft/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/skills/craft/vercel-optimize/scripts/budget-summary.mjs

@@ -0,0 +1,58 @@
+#!/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 { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+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);
+});

package/skills/craft/vercel-optimize/scripts/build-docs.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Regenerates references/{scanner-patterns,candidates}.md from lib/{scanners,gates}/*
+// metadata. The .mjs files are the source of truth; check-docs-fresh.mjs blocks
+// PRs where the regenerated output diverges from what's checked in.
+
+import { writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gates, MAX_CODE_CANDIDATES, GATE_VERSION } from "../lib/gates/index.mjs";
+import { scanners } from "../lib/scanners/index.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REFS = join(HERE, "..", "references");
+
+const GENERATED_BANNER =
+  "<!-- THIS FILE IS GENERATED by scripts/build-docs.mjs. Do not edit by hand. -->\n" +
+  "<!-- To change scanner descriptions, edit lib/scanners/*.mjs metadata exports. -->\n" +
+  "<!-- To change gate thresholds, edit lib/gates/*.mjs metadata exports. -->\n\n";
+
+async function main() {
+  await writeFile(join(REFS, "scanner-patterns.md"), renderScanners());
+  await writeFile(join(REFS, "candidates.md"), renderCandidates());
+  console.error("[build-docs] wrote scanner-patterns.md + candidates.md");
+}
+
+function renderScanners() {
+  const sorted = scanners.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + "# Scanner patterns\n\n";
+  out +=
+    "AST/grep-style scanners run in parallel with metric-driven investigation. They find known anti-patterns. Findings on cold-path or unmappable files are dropped unless the scanner declares `trafficIndependent: true`.\n\n";
+  out += `Total scanners: ${sorted.length}.\n\n`;
+  out += "## Patterns\n\n";
+  for (const s of sorted) {
+    const m = s.metadata;
+    out += `### \`${m.id}\` — ${m.title}\n\n`;
+    out += `- **Severity**: ${m.severity}\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Traffic-independent**: ${m.trafficIndependent ? "yes (cold-path findings survive the doctrine drop)" : "no (cold-path findings get dropped)"}\n\n`;
+    out += `**Description.** ${m.description}\n\n`;
+    out += `**Fix.** ${m.fix}\n\n`;
+    if (m.citations?.length) {
+      out += `**Citations:**\n${m.citations.map((c) => `- \`${c}\``).join("\n")}\n\n`;
+    }
+    out += "---\n\n";
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function renderCandidates() {
+  const sorted = gates.slice().sort((a, b) => a.metadata.id.localeCompare(b.metadata.id));
+  let out = GENERATED_BANNER + "# Candidate gates\n\n";
+  out +=
+    "The deterministic threshold expressions that turn observability signals into investigation candidates. Pure JS, no LLM. Thresholds live in `lib/gates/*.mjs`.\n\n";
+  out += `Total gates: ${sorted.length}. Budget cap: \`MAX_CODE_CANDIDATES = ${MAX_CODE_CANDIDATES}\`. Gate version: \`${GATE_VERSION}\`.\n\n`;
+  out += "## Gates\n\n";
+  for (const g of sorted) {
+    const m = g.metadata;
+    out += `### \`${m.id}\`\n\n`;
+    out += `- **Threshold**: \`${m.threshold}\`\n`;
+    out += `- **Billing dimension**: ${m.billingDimension}\n`;
+    out += `- **Scope**: ${m.scope}\n`;
+    out += `- **Source citation**: \`${m.sourceCitation}\`\n\n`;
+    out += `${m.description}\n\n`;
+    out += "---\n\n";
+  }
+  return trimTrailingBlankLine(out);
+}
+
+function trimTrailingBlankLine(value) {
+  return value.replace(/\n{2,}$/, "\n");
+}
+
+main().catch((err) => {
+  console.error("[build-docs] FAILED:", err.message);
+  process.exit(1);
+});