@oriro/orirocli 0.1.9 → 0.1.11

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,30 +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'`.
+---
+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'`.