@oriro/orirocli 0.1.9 → 0.1.11

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

@@ -1,32 +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.
+---
+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

@@ -1,102 +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.
+# 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

@@ -1,76 +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.
+# 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

@@ -1,58 +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);
-});
+#!/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);
+});