@oriro/orirocli 0.1.0

package/skills/craft/vercel-optimize/references/scoring.md

@@ -0,0 +1,208 @@
+## Step 4 — Score and report
+
+This reference covers everything that happens after recommendations are drafted: quality floor, impact framing, sort order, the customer-facing report template, and the playbook selection matrix.
+
+## Table of contents
+
+- [Quality floor and prune rules](#quality-floor-and-prune-rules)
+- [Impact framing — the magnitude rule](#impact-framing--the-magnitude-rule)
+- [`impactLabel` schema](#impactlabel-schema)
+- [Sort order and platform-rec cap](#sort-order-and-platform-rec-cap)
+- [The customer-facing report template](#the-customer-facing-report-template)
+- [Playbook selection matrix](#playbook-selection-matrix)
+
+## Quality floor and prune rules
+
+| Rule                                               | Value                                           | Why                                                                                                                                         |
+| -------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Drop recommendations with `quality.overall < 0.55` | Hard cutoff (raised from 0.4 in May 2026 audit) | Bad-grade recs erode trust faster than they help. 0.55 matches the Poor/Fair grade boundary; recs below this are "Poor" and shouldn't ship. |
+| Prune cap on findings                              | 30% of input                                    | Stops the pruner from wiping the report when LLM merit-grades are noisy                                                                     |
+| Platform-rec cap                                   | 3                                               | Account-level recs (Fluid, Bot Protection, Speed Insights) only have room for the top three                                                 |
+| Quick-wins definition                              | `effort === 'low' AND priority > 40`            | Surfaces fixes the user can ship in a single PR                                                                                             |
+| Savings floor (internal ranking only)              | $5/mo equivalent                                | Below this, even a "high" tier impact translates to "negligible" magnitude                                                                  |
+
+## Impact framing — the magnitude rule
+
+**Performance: be precise.** Use observed numbers. Example:
+
+> "Reduce /api/products p95 from 850ms toward ~250-400ms; cache hit would lift from 0% toward ~60% based on similar cached routes."
+
+Performance numbers come from `signals.json.metrics.*` — they're observed, not extrapolated. Cite the exact route + metric value.
+
+**Dollar cost: never precise.** Use MAGNITUDE BUCKETS via `lib/impact-magnitude.mjs`'s `impactMagnitude({currentCost, impactTier})`:
+
+| Estimated reduction (USD) | Magnitude    | Customer-facing phrase                                  |
+| ------------------------- | ------------ | ------------------------------------------------------- |
+| < $5                      | `negligible` | "small cost impact at current traffic"                  |
+| $5 – $50                  | `small`      | "low-tens of dollars per month at current traffic"      |
+| $50 – $500                | `medium`     | "hundreds of dollars per month at current traffic"      |
+| $500 – $5,000             | `large`      | "low-thousands of dollars per month at current traffic" |
+| > $5,000                  | `very-large` | "thousands+ of dollars per month at current traffic"    |
+
+Reduction is computed as `currentCost × fraction` where `fraction = {high: 0.4, medium: 0.2, low: 0.1}[impactTier]`. The fraction is intentionally conservative — we'd rather under-promise than mislead.
+
+### Discountable vs non-discountable SKUs
+
+When the project is on a Flex Commit and the report frames savings against contract burndown, segment spend before phrasing. Field doctrine (May 2026): the Flex discount slider applies only to a subset of SKUs.
+
+| Discountable (slider applies) | Non-discountable (raw rate) |
+| ----------------------------- | --------------------------- |
+| Seats                         | Build CPU Minutes           |
+| Edge Requests                 | Fluid Active CPU            |
+| Fast Data Transfer            | Fluid Provisioned Memory    |
+| Fast Origin Transfer          | Raw Flex top-up             |
+| Image Optimization            |                             |
+| ISR Reads / Writes            |                             |
+| Observability Events          |                             |
+
+A recommendation that targets a non-discountable SKU should never frame savings as a percentage of contract; frame as absolute magnitude only. Conversely, a discountable-SKU recommendation may surface "applies to contract burndown" in the magnitude phrase.
+
+**Why magnitudes:**
+
+- Traffic varies. A "20% reduction in edge requests" is exact at today's traffic and meaningless next quarter.
+- Pricing changes. Vercel's billing rates move; precise dollar projections rot.
+- The user is smart. They'd rather see "hundreds of dollars per month" with a real metric backing it than `$340/mo` with a hand-wave behind it.
+- The `$-strip` sanitizer enforces this at output time. Any `$N` literal that slips into customer-facing fields is replaced with "the billed cost" before rendering.
+
+## `impactLabel` schema
+
+```ts
+type ImpactLabel = {
+  // PRECISE: performance recs
+  performance?: string;
+  // MAGNITUDE: cost recs
+  costMagnitude?: "negligible" | "small" | "medium" | "large" | "very-large";
+  costPhrase?: string;
+  billingDimension?: string; // 'Edge Requests' | 'Function Duration' | ...
+  fractionReduced?: number; // 0.2 = ~20% — internal only, NOT rendered
+};
+```
+
+Cost recs render `costPhrase`. Performance recs render `performance`. Reliability recs frame impact as observed error/timeout reduction (e.g., "Cuts 5xx rate from 0.4% to <0.1% based on current traffic").
+
+When a rec spans buckets — e.g., a caching fix that reduces both cost AND latency — render both lines.
+
+## Sort order and platform-rec cap
+
+Internal sort key (never rendered): `priority = currentDimensionCost × fractionReduced × confidence`.
+
+The list of recs the customer sees is sorted by this priority. The platform recommendations section is capped at 3, sorted the same way.
+
+## The customer-facing report template
+
+The agent renders this as the final output of Step 4. The shape is fixed; the content comes from the merged signals + verified recommendations + the `gated[]` list from Step 2.
+
+```markdown
+# Vercel Optimization Report — {projectName}
+
+**Stack**: {framework}@{frameworkVersion} | {router} | {orm}
+**Plan**: {plan.plan} ({plan.reason})
+**Period**: {usage.period.from} → {usage.period.to}
+**Observability**: {observability status}
+
+## Cost breakdown
+
+| Service                                                        | Usage | Billed Cost |
+| -------------------------------------------------------------- | ----- | ----------- |
+| (non-zero rows from usage.services, sorted by billedCost desc) |
+
+Total billed: {usage.totals.billedCost} (we render the precise current cost — we just don't project future precise savings)
+
+Omit zero-cost service rows from the table at the same cent precision shown to customers. If every row has `$0.00` billed cost but `effectiveCost` / USD `pricingQuantity` is non-zero, explain that net billed cost is `$0.00` after included credits or allotments and show the effective usage cost table instead. If both billed and effective costs are `$0.00`, replace the table with a concise note that `vercel usage` returned a billing payload but every reported service cost was `$0.00` for the window.
+
+If `vercel usage` was queried and unavailable, the cost breakdown is replaced by an observability-derived cost ranking from `metrics.fnGbHrByRoute` + `metrics.fnCpuMsByRoute` + `metrics.fdtByRoute` when those metrics exist. These don't translate directly to dollars — they show _which routes consume the billable units_ so the user knows what to attack first. If `usageError` is `NOT_COLLECTED_OBSERVABILITY_BLOCKED` or another `NOT_COLLECTED_*` value, say usage was not collected; do not describe it as a billing-plan or Costs-feature finding.
+
+Render Observability status from the actual collection state:
+
+- `Observability Plus enabled — per-route metrics included` when `observabilityPlusUsable=true`.
+- `Per-route metrics unavailable — audit paused before metric-backed route ranking` when an Observability Plus blocker stopped the run before billing/scanner collection.
+- `Per-route metrics unavailable — analysis based on billing + scanner findings` when the user accepted a limited audit and billing/scanner signals were collected.
+- `Per-route metrics unavailable — limited analysis based on scanner findings` when the user accepted a limited audit but billing usage was queried and unavailable.
+- `Not checked — audit paused at unsupported-framework preflight` when framework support stopped the run before the Observability Plus check.
+- `Not enabled — analysis based on billing + scanner findings` only for legacy/limited reports where Observability Plus is known false and billing/scanner signals exist.
+
+## Highest-impact recommendations
+
+For each high-priority rec, in order:
+
+1. **{route or file}** — {o11ySignal}
+1. **{readable candidate label}** — {readable metric labels}
+   - **What to do**: {rec.what}
+   - **Impact**: {impactLabel.performance ?? impactLabel.costPhrase}
+   - **Effort**: {rec.effort}
+   - **Citations**: {rec.citations}
+
+## Recommendations
+
+### High impact
+
+| #   | Bucket | What | Impact | Effort | Citations |
+| --- | ------ | ---- | ------ | ------ | --------- |
+
+### Medium impact
+
+### Low impact
+
+## Platform recommendations
+
+(account-level recs from gate, capped at 3)
+
+## Observations from investigation
+
+Non-recommendation findings from reconciliation or investigation: deployment regressions, route-error storms, metric mismatches, and other real signals that should not become speculative performance recommendations.
+
+Observations must not contain implementation-grade actions. If the suggested action says to enable, add, wrap, apply, move, configure, challenge, deny, or otherwise change code or project settings, the renderer must hold it back until it passes the ready-to-apply recommendation evidence bar. Customer-visible observations can ask for narrower evidence collection: inspect logs, compare deployments, check headers, or confirm cacheability.
+
+## Investigated, no change recommended
+
+Candidates that were checked but did not produce a supported recommendation. Use plain reasons; do not use "abstain" in customer-facing copy.
+
+| Candidate           | Why no recommendation shipped                  |
+| ------------------- | ---------------------------------------------- |
+| Slow route on /docs | Detailed metrics did not support a code change |
+
+## Not investigated in this run
+
+This section earns the user's trust. For every metric signal we considered but didn't act on, group by candidate type and reason:
+
+| Candidate type      | Why not investigated         | Targets                 | Count |
+| ------------------- | ---------------------------- | ----------------------- | ----: |
+| Low cache-hit route | hitRate 0.65 above threshold | /api/orders             |     1 |
+| Slow route          | left for a larger run        | /api/docs<br>/api/learn |     2 |
+
+## Strengths
+
+(what the project is doing right — caching is healthy on routes X/Y/Z; Fluid Compute is enabled; etc.)
+
+## Data gaps
+
+(what we couldn't measure — Observability Plus disabled means no per-route latency, etc.)
+```
+
+Common data gaps to call out when the underlying metric returned empty rows. If the metric query failed (`ok=false`), say the metric was not usable with the code; do not convert failed queries into "no measurements" or "not used" claims.
+
+- **Core Web Vitals empty.** The Speed Insights metric returned no measurements for the 14-day window. The `cwv_poor` gate stayed dormant; no claims about LCP/INP/CLS are made.
+- **ISR empty.** Project doesn't use Incremental Static Regeneration. The `isr_overrevalidation` gate stayed dormant.
+- **Middleware empty.** No `middleware.ts` (or matcher excludes all observed traffic). The `middleware_heavy` gate stayed dormant.
+- **Image transformations empty.** No `next/image` usage or no images served in the window.
+- **BotID checks empty.** BotID is disabled — see the `platform_bot_protection` recommendation for the toggle.
+- **Cold-start data near-zero.** Fluid Compute may already be enabled, or the project's traffic pattern keeps warm instances available; the `cold_start` gate evaluates the data but emits no candidate.
+
+The "Not investigated in this run" section is critical. It comes directly from `gate.json` produced by the gate. It tells the user we considered everything; we didn't just pick the easy targets.
+
+## Playbook selection matrix
+
+The recommender selects 0-2 playbooks based on the project's `stack.applicationProfile` (inferred from frameworks + deps) and the top billing dimensions.
+
+| Application profile                                  | Likely top dimensions                                 | Apply playbooks               |
+| ---------------------------------------------------- | ----------------------------------------------------- | ----------------------------- |
+| `ai-application` (AI SDK, AI Gateway, Sandbox usage) | AI Gateway, Sandbox Active Compute, Function Duration | `playbooks/ai-application.md` |
+| `ecommerce` (Stripe, Shopify, cart components)       | Edge Requests, Function Duration                      | `playbooks/ecommerce.md`      |
+| `saas` (auth, dashboards, multi-tenant)              | Function Duration, Bandwidth                          | `playbooks/saas.md`           |
+| `api-service` (mostly API routes, no UI)             | Function Duration, Edge Requests                      | `playbooks/api-service.md`    |
+| `content-site` (blog, docs, mostly static)           | Edge Requests, Image Optimization                     | `playbooks/content-site.md`   |
+| `marketing` (landing pages, A/B tests)               | Edge Requests, ISR Reads                              | `playbooks/marketing.md`      |
+
+`ai-application` is checked first in `inferPlaybook()` — an AI-heavy SaaS or AI commerce app shares the AI playbook's billing shape (AI Gateway dominant) and gotchas, not the dashboard or cart-checkout patterns.
+
+Playbooks shape phrasing and ordering of recommendations. They never invent claims — every rec must still trace back to verified findings.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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