@oriro/orirocli 0.1.8 → 0.1.11

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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