opencode-skills-collection 3.0.35 → 3.0.36

package/bundled-skills/vercel-optimize/references/recommendations.md

@@ -0,0 +1,203 @@
+# Recommendations
+
+How recommendations are shaped, written, sanitized, and graded.
+
+## Table of contents
+
+- [Schema](#schema)
+- [Writing rules](#writing-rules)
+- [The 12 sanitizers](#the-12-sanitizers)
+- [Envelope-unwrap recovery](#envelope-unwrap-recovery)
+- [Grading rubric](#grading-rubric)
+- [Next.js version awareness](#nextjs-version-awareness)
+
+## Schema
+
+Every recommendation is a JSON object matching this TypeScript shape:
+
+```ts
+interface Recommendation {
+  // Customer-facing
+  what: string;              // 1 line, lead with impact. Max 80 chars when feasible.
+  why: string;               // 1-2 sentences. Root cause. Cites codebase findings + counts.
+  fix: string;               // Step-by-step. Includes before/after code fences. Specific enough to implement.
+  bucket: 'cost' | 'performance' | 'reliability';
+  effort: 'low' | 'medium' | 'high';
+  affectedFiles: string[];   // Verified file paths, from candidate.files
+  currentBehavior: string;   // What the code does now (with snippet)
+  desiredBehavior: string;   // Target state (with snippet)
+  risk?: string;             // Optional: e.g., "Removing force-dynamic may serve stale data on /admin"
+  verify: string;            // How to confirm the fix worked. e.g., "Re-run `vercel metrics …` and watch p95"
+
+  // Impact (computed from impact-magnitude.mjs in Step 4)
+  impactLabel: {
+    performance?: string;    // PRECISE: "Reduce /api/products p95 from 850ms toward ~250-400ms"
+    costMagnitude?: 'negligible' | 'small' | 'medium' | 'large' | 'very-large';
+    costPhrase?: string;     // "hundreds of dollars per month at current traffic"
+    billingDimension?: string;
+    fractionReduced?: number;
+  };
+  impactTier: 'high' | 'medium' | 'low';
+  billingDimension?: 'edge-requests' | 'function-duration' | 'image-optimization' | 'isr-reads' | 'isr-writes' | 'bandwidth' | 'data-cache-reads' | 'cron-invocations' | string;
+
+  // Grounding
+  citations: string[];       // From references/docs-library.json allow-list. Required: ≥1 entry.
+  candidateRef?: string;     // The gate candidate this rec traces to (e.g., "uncached_route:/api/products")
+  findingRefs?: string[];    // File:line markers from verifiedFindings.json
+  appliesAlsoTo?: Array<{     // Added by dedup when matching recs collapse into one customer-facing item.
+    candidateRef?: string;
+    affectedFiles?: string[];
+    o11ySignal?: string;
+    what?: string;
+  }>;
+  corroborationCount?: number; // Number of matching verified recs folded into this item, including itself.
+
+  // Verifier output (computed in Step 3.6)
+  verification?: {
+    passRate: number;
+    failed: Array<{ type: string; text: string; reason: string }>;
+  };
+
+  // Sanitizer audit trail (computed in Step 3.4)
+  sanitizerTrail?: string[]; // ["$-strip:2", "version-mismatch:next@15+:1", ...]
+  needsReview?: boolean;     // Set when a sanitizer caught a hazard
+
+  // Grading (Step 3.5)
+  quality: {
+    specificity: number;     // 0-1
+    actionability: number;
+    grounding: number;
+    evidence: number;
+    overall: number;
+    grade: 'Excellent' | 'Good' | 'Fair' | 'Poor';
+  };
+}
+```
+
+## Writing rules
+
+The recommender prompt explicitly tells the agent to follow these rules. Sanitizers enforce them after generation.
+
+**Voice and tone** are governed by [`references/voice.md`](./voice.md). Read it before writing recommendation prose; it keeps reports direct, metric-grounded, and free of internal process terms.
+
+### Lead with impact
+
+The `what` field opens with the verb + the change, not the framing. Compare:
+
+- ❌ "Consider enabling caching on the /api/products route" (filler before substance)
+- ✅ "Add Cache-Control with s-maxage to /api/products" (verb-first, scope-explicit)
+
+### Cite codebase findings with line numbers
+
+The `why` must reference a verified finding from `verifiedFindings.json`:
+
+- ❌ "The route is uncached" (could apply anywhere)
+- ✅ "src/app/api/products/route.ts:22 returns Response without Cache-Control; observability shows 0% cache hit on 1.2M invocations/mo"
+
+### No $ literals in customer fields
+
+The user-mandated rule. `what`/`why`/`fix`/`impact`/`currentBehavior`/`desiredBehavior` must not contain `$N` money literals. Use magnitude framing from `impact-magnitude.mjs`.
+
+- ❌ "Save $340/mo by adding s-maxage"
+- ✅ "Hundreds of dollars per month at current traffic"
+- ✅ (precise performance) "Move 1.2M monthly invocations to the CDN; expect p95 to drop from 850ms toward ~50ms on cache hits"
+
+The `$-strip` sanitizer enforces this at output time, but the prompt should also instruct the LLM not to emit dollar literals in the first place.
+
+### Before/after code fences required
+
+`currentBehavior` shows the offending snippet. `desiredBehavior` shows the target. Language-tagged code fences. Keep both under ~20 lines.
+
+### Cite at least one URL from the library
+
+`citations[]` must contain at least one entry from `references/docs-library.json`. The `missing-citation` sanitizer drops uncited recs. The `unknown-citation` and `version-mismatch` sanitizers strip invalid citations.
+
+### Match the user's framework version
+
+Don't recommend `'use cache'` (Next 15+) to a Next 13 user. The recommender prompt receives only the citation subset valid for the user's stack — but the LLM can still hallucinate. The `version-mismatch` sanitizer catches stragglers.
+
+## The 12 sanitizers
+
+Each sanitizer records its action in `rec.sanitizerTrail` when it mutates a field. Tag format: `tag:detail`. Tags are lexically stable — downstream consumers grep them.
+
+| # | Sanitizer | Trigger | Action | Trail tag |
+|---|---|---|---|---|
+| 1 | `$-strip` | Money-literal regex in customer field | Replace with "the billed cost" | `$-strip:N` |
+| 2 | `vercel-directive-strip` | `stale-if-error` / `proxy-revalidate` in cache-control | Strip directive (Vercel CDN doesn't honor) | `vercel-directive-strip:directive` |
+| 3 | `rate-limit` | Concurrency × delay > known provider rate limit | Prepend caveat, set needsReview | `rate-limit:provider:prescribed/limit` |
+| 4 | `pre-release` | Fix enables `-rc`/`-beta`/`-canary` feature | Append "requires pre-release version" caveat | `pre-release:pkg@version` |
+| 5 | `middleware-conflict` | Rec targets route covered by middleware matcher | Append "Middleware {matcher} may intercept" caveat | `middleware-conflict:matcher` |
+| 6 | `undeclared-dep` | Fix imports a package not in package.json | Prepend "Add dependency first: npm i {pkg}" | `undeclared-dep:pkg` |
+| 7 | `count-correct` | Cited count > verified count, ground-truth known | Rewrite to "~N" with verified count | `count-correct:token:cited→actual` |
+| 8 | `count-strip` | Cited count > verified count, no ground truth | Rewrite to "a number of" | `count-strip:token` |
+| 9 | `rendering-mode-mislabel` | Rec blames ISR/SSR on a static page | Append warning, set needsReview | `rendering-mode-mislabel` |
+| 10 | `unknown-citation` | URL not in `references/docs-library.json` | Strip URL, set needsReview if all stripped | `unknown-citation:url` |
+| 11 | `version-mismatch` | URL's `applicableFrameworks` doesn't match stack | Strip URL, set needsReview if all stripped | `version-mismatch:url` |
+| 12 | `missing-citation` | `citations.length === 0` after other sanitizers | DROP rec entirely | (rec not emitted; counted at end) |
+
+The sanitizer order matters: dollar-strip runs first (cheap, deterministic), then content sanitizers, then citation sanitizers last. This guarantees citation count is computed against the final state.
+
+The `recordSanitizer(rec, tag)` helper is the single entry point — sanitizers MUST call it before mutating fields. Otherwise the audit trail rots.
+
+### Provider rate limits
+
+Used by sanitizer #3. These provider limits are public contract values:
+
+| Provider | Limit | Doc URL |
+|---|---|---|
+| Notion | 3 rps | https://developers.notion.com/reference/request-limits |
+| OpenAI | 30 rps | https://platform.openai.com/docs/guides/rate-limits |
+| Stripe | 100 rps | https://docs.stripe.com/rate-limits |
+| Anthropic | 10 rps | https://docs.anthropic.com/en/api/rate-limits |
+
+Tiers/plans differ; these are first-tier defaults. The sanitizer prepends a caveat if the rec prescribes higher concurrency.
+
+## Envelope-unwrap recovery
+
+Not a sanitizer — a recovery step. LLMs occasionally wrap their JSON output in an envelope:
+
+```json
+{ "data": { "recommendations": [...] } }
+{ "result": { "recommendations": [...] } }
+{ "insights": { "recommendations": [...] } }
+```
+
+`attemptManualRecovery` peels one wrapping layer before schema validation. Increments `hygieneCounters.envelopeUnwraps`. Logs the unwrap to the run log.
+
+This is the only "creative" parsing the skill does. Anything else that fails schema validation is rejected.
+
+## Grading rubric
+
+Each rec is scored on four axes, 0-1 each. Average → grade:
+
+| Axis | What it measures | Strong (1.0) signal |
+|---|---|---|
+| Specificity | Concrete files, line numbers, code snippets | Triple-backtick code fence OR inline code ≥10 chars + verified file path |
+| Actionability | Clear "do this then that" steps | Numbered steps; verbs present in each step; no "consider"/"might" |
+| Grounding | Claims trace to findings or metric data | `sourceIndex` matches a finding OR rec has affectedFiles + code fences (presumed evidence) |
+| Evidence | Numeric, observed claims | Count words (errors, queries, invocations) + units (% / ms / s / K / M) |
+
+Grade thresholds:
+- `Excellent` ≥ 0.85
+- `Good` 0.70 – 0.85
+- `Fair` 0.55 – 0.70
+- `Poor` < 0.55 → dropped at quality floor in Step 4
+
+## Next.js version awareness
+
+The recommender's citation library is filtered by `signals.json.stack.framework@frameworkVersion`. The agent should still self-check the version when picking which APIs to recommend:
+
+| Feature | Available | Notes |
+|---|---|---|
+| App Router | Next ≥ 13.0 | Default since 14 |
+| `generateStaticParams` | Next ≥ 13.0 | Replaces getStaticPaths for App Router |
+| Fetch `next: { revalidate }` | Next ≥ 13.0 | Note: default fetch caching flipped in Next 15 |
+| `unstable_cache` | Next 14-15 | Replaced by 'use cache' in 16 |
+| `'use cache'` directive | Next ≥ 15.0 | Persistent cache primitive |
+| `cacheLife()`, `cacheTag()` | Next ≥ 15.0 | Pairs with 'use cache' |
+| `after()` | Next ≥ 15.0 | Non-blocking post-response work |
+| Partial Prerendering | Next ≥ 15.0 | Stable target later — verify per release |
+| `revalidateTag` / `revalidatePath` | Next ≥ 13.4 | Tag-based on-demand invalidation |
+| `cookies()` / `headers()` async | Next ≥ 15.0 | Async pattern in 15+ |
+
+The skill's curated citation library encodes these constraints via `applicableFrameworks`. If a contributor adds a new Next.js feature URL, they MUST set the right semver range in `references/docs-library.json`.

package/bundled-skills/vercel-optimize/references/scanner-patterns.md

@@ -0,0 +1,251 @@
+<!-- THIS FILE IS GENERATED by scripts/build-docs.mjs. Do not edit by hand. -->
+<!-- To change scanner descriptions, edit lib/scanners/*.mjs metadata exports. -->
+<!-- To change gate thresholds, edit lib/gates/*.mjs metadata exports. -->
+
+# Scanner patterns
+
+AST/grep-style scanners run in parallel with metric-driven investigation. They find known anti-patterns. Findings on cold-path or unmappable files are dropped unless the scanner declares `trafficIndependent: true`.
+
+Total scanners: 15.
+
+## Patterns
+
+### `cache-components-suspense-dedupe` — 'use cache' with multiple Suspense boundaries on the same data
+
+- **Severity**: medium
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** 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 cost and inflating ISR write churn when the output is large.
+
+**Fix.** Hoist the promise to the page level (`const dataPromise = fetchData()` at the top, passed down to each Suspense child) OR move the shared fetch into a `'use cache: remote'` data-access layer so cross-request and cross-boundary dedupe applies.
+
+**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`
+
+---
+
+### `edge-heavy-import` — Heavy / node-only import inside edge-runtime file
+
+- **Severity**: high
+- **Billing dimension**: function-duration
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** Edge runtime is a constrained sandbox with no node: builtins and a much smaller cold-start budget than Node functions. Heavy SDKs (sharp, @aws-sdk/*, @prisma/client, pg, puppeteer) either fail at deploy or inflate cold-start latency. Move the import to a Node runtime function, or replace with an edge-compatible alternative (e.g., neon-driver instead of pg).
+
+**Fix.** Either (a) drop the `export const runtime = 'edge'` so the route runs on Node (default in 2026), or (b) replace the heavy import with an edge-compatible alternative. For DB: use @neondatabase/serverless or @planetscale/database instead of pg/mysql2. For image: do the work in a Node route handler. For auth signing: use jose (Web Crypto) instead of jsonwebtoken.
+
+**Citations:**
+- `https://vercel.com/docs/functions/runtimes/edge-runtime`
+- `https://vercel.com/docs/fluid-compute`
+
+---
+
+### `force-dynamic` — export const dynamic = 'force-dynamic'
+
+- **Severity**: medium
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** force-dynamic disables static + ISR rendering. The route runs the function on every request. Sometimes necessary (cookies, headers, real-time data), often a habit that costs function-duration and edge-requests at scale.
+
+**Fix.** Audit the route. If dynamic behavior comes from cookies()/headers()/searchParams, force-dynamic may be redundant — Next infers dynamic automatically. Consider revalidate / 'use cache' / generateStaticParams if any portion can be pre-rendered.
+
+**Citations:**
+- `https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config`
+
+---
+
+### `headers-in-page` — Dynamic API call forcing dynamic rendering
+
+- **Severity**: medium
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** headers(), cookies(), and draftMode() are dynamic APIs. Reading them in a page/layout makes the entire segment dynamic — no ISR, no static generation, and a function invocation on every request.
+
+**Fix.** Move the dynamic API call into a child Server Component that lives inside a Suspense boundary. The parent can stay static; only the leaf re-renders dynamically.
+
+**Citations:**
+- `https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config`
+- `https://nextjs.org/docs/app/building-your-application/caching`
+
+---
+
+### `large-static-asset` — Large file in public/
+
+- **Severity**: medium
+- **Billing dimension**: bandwidth
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** Static assets in `public/` over 500 KB ship as-is from the CDN. Whether the cost is meaningful depends on traffic, but the candidate is binary — the file is either needed at that size or it can be optimized (compressed image, video transcode, or moved off the critical path).
+
+**Fix.** Verify the asset is reachable on the customer-facing hot path. Then choose: (a) compress (convert PNG → AVIF/WebP; transcode MP4 to lower bitrate); (b) host externally (Vercel Blob, S3, or a media CDN with per-asset signed URLs); (c) lazy-load (defer to client-side fetch instead of bundling into initial HTML).
+
+**Citations:**
+- `https://vercel.com/docs/manage-cdn-usage`
+- `https://vercel.com/docs/image-optimization`
+
+---
+
+### `max-age-without-s-maxage` — Cache-Control: max-age without s-maxage
+
+- **Severity**: medium
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** max-age caches in the browser; s-maxage caches at the CDN. Without s-maxage, every uncached visitor request invokes the function. Adding s-maxage often cuts function invocations by 80%+ on read-heavy routes.
+
+**Fix.** Add s-maxage to the Cache-Control header. Example: Cache-Control: public, max-age=60, s-maxage=600, stale-while-revalidate=86400. Pair with explicit cache-bust strategy if content can change.
+
+**Citations:**
+- `https://vercel.com/docs/caching/cdn-cache`
+- `https://vercel.com/docs/caching/cache-control-headers`
+
+---
+
+### `middleware-broad-matcher` — Middleware matcher missing or too broad
+
+- **Severity**: high
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** middleware.ts without a config.matcher (or matcher: ["/(.*)"]) runs on every request including _next/static, _next/image, favicon.ico, and image asset fetches. Edge-request cost scales accordingly.
+
+**Fix.** Scope the matcher to actual application paths. Example: matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"]
+
+**Citations:**
+- `https://nextjs.org/docs/app/building-your-application/routing/middleware`
+
+---
+
+### `missing-cache-headers` — Cacheable route or fetch with no caching (Cache-Control absent or no-store)
+
+- **Severity**: medium
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Two antipatterns: (a) GET handlers without explicit Cache-Control headers serve uncached; (b) fetch() calls with cache:"no-store" or next:{revalidate:0} opt out of caching even on cacheable upstream data. For non-auth routes / fetches, both are leaving cache hits on the floor.
+
+**Fix.** For GET handlers: return a Response with Cache-Control: public, s-maxage=<seconds>, stale-while-revalidate=<window>. For fetch(): drop cache:"no-store" (use { next: { revalidate: <seconds> } } in Next.js) so the response is cached by the framework + CDN.
+
+**Citations:**
+- `https://vercel.com/docs/caching/cdn-cache`
+- `https://vercel.com/docs/caching/cache-control-headers`
+- `https://nextjs.org/docs/app/building-your-application/caching`
+
+---
+
+### `prisma-include-tree-bloat` — Deep Prisma include tree (3+ levels)
+
+- **Severity**: high
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Nested .include({ x: { include: { y: { include: { z: ... } } } } }) makes Prisma issue a single huge join that scales O(N*M*K). Function duration explodes, memory spikes, often causes timeouts.
+
+**Fix.** Replace with explicit .findMany() calls or scoped .include() of only what the consumer reads. Consider Prisma.select() to project specific fields. For lists, batch with DataLoader patterns.
+
+**Citations:**
+- `vercel-react-best-practices:server-parallel-fetching`
+
+---
+
+### `region-pin-in-config` — Function region pinned in config
+
+- **Severity**: low
+- **Billing dimension**: function-duration
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** vercel.json `regions` or per-route `preferredRegion` is set. If the pinned region is far from the dominant user geo (or far from a data source) p95 TTFB suffers. This scanner provides the configured-region signal so the region-misconfig gate can recommend an audit.
+
+**Fix.** Audit the pinned region against traffic geography (Speed Insights or Web Analytics by country) and data-source location. Consider multi-region if data lives in a fixed location and users are global; consider relocating if users are concentrated in one geography.
+
+**Citations:**
+- `https://vercel.com/docs/functions/configuring-functions/region`
+- `https://vercel.com/docs/functions/configuring-functions/region`
+
+---
+
+### `source-maps-production` — Source maps enabled in production
+
+- **Severity**: low
+- **Billing dimension**: edge-requests
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** productionBrowserSourceMaps: true ships .map files in the production bundle, increasing transfer size 30-100% per visitor. Useful for error reporting via Sentry; not useful for users.
+
+**Fix.** Keep source maps generation but exclude them from the public bundle. Upload to your error tracker via build-time CI step; do not serve them with the deployment.
+
+**Citations:**
+- `https://nextjs.org/docs/messages/improper-devtool`
+
+---
+
+### `sveltekit-prerender-missing` — SvelteKit page without explicit prerender / ISR config
+
+- **Severity**: low
+- **Billing dimension**: function-duration
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** SvelteKit page or +page.server.ts is missing an explicit `prerender`, `ssr`, or adapter `config.isr` declaration. Default is per-request function execution — investigate whether the route could be prerendered or ISR-cached.
+
+**Fix.** If the page is static (no per-user / per-request data), add `export const prerender = true` in +page.ts or +page.server.ts. If the data refreshes on a schedule, prefer adapter-vercel's ISR option via `export const config = { isr: { expiration: 60 } }`.
+
+**Citations:**
+- `https://kit.svelte.dev/docs/page-options`
+- `https://kit.svelte.dev/docs/adapter-vercel`
+- `https://vercel.com/docs/incremental-static-regeneration`
+
+---
+
+### `turbo-force-bypass` — Turborepo cache bypass on a monorepo
+
+- **Severity**: high
+- **Billing dimension**: build
+- **Traffic-independent**: yes (cold-path findings survive the doctrine drop)
+
+**Description.** Turborepo's per-task cache can be bypassed by an explicit force flag, a `cache: false` config, or missing build-skip configuration. Every commit can rebuild unchanged work; Build Minutes climb with project count.
+
+**Fix.** Remove `TURBO_FORCE=true` from build env/scripts unless intentional. Set `tasks.build.cache: true` in `turbo.json` (or remove the override), and include generated outputs in Turbo's cache contract. Prefer Vercel's skip-unaffected monorepo behavior when available; use `ignoreCommand` only when that setting cannot cover the project.
+
+**Citations:**
+- `https://vercel.com/docs/monorepos`
+- `https://vercel.com/docs/builds`
+- `https://turborepo.dev/docs/crafting-your-repository/caching`
+
+---
+
+### `unoptimized-image` — Image optimization gap (raw <img>, global flag, missing sizes, or SVG mis-routed)
+
+- **Severity**: high
+- **Billing dimension**: image-optimization
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** Four shapes of image-cost waste: raw <img> tags bypass the framework Image component; `images.unoptimized: true` disables Vercel image optimization globally; <Image fill> without `sizes` forces serving the largest source variant; <Image src=".svg"> without `unoptimized` routes vector data through the raster pipeline.
+
+**Fix.** For raw <img>: switch to next/image, enhanced-img (SvelteKit), <Image /> (Astro), or NuxtImg. For global unoptimized:true: remove the flag unless the project is hosted outside Vercel. For fill without sizes: add `sizes="(max-width: 768px) 100vw, 50vw"` or whatever matches your layout. For SVG: add `unoptimized` so the raw SVG ships instead of rastering it.
+
+**Citations:**
+- `https://nextjs.org/docs/app/api-reference/components/image`
+- `https://vercel.com/docs/image-optimization`
+
+---
+
+### `use-cache-date-stamp` — new Date() / Date.now() / Math.random() inside a 'use cache' file
+
+- **Severity**: high
+- **Billing dimension**: isr
+- **Traffic-independent**: no (cold-path findings get dropped)
+
+**Description.** `'use cache'` memoizes by argument identity AND prerender output. A timestamp baked into the cached output (`new Date().getFullYear()` in a footer, `Date.now()` in a payload field) forces a fresh ISR write on every regeneration even when the underlying data is unchanged. Random values have the same failure mode.
+
+**Fix.** Replace module-scope `new Date()` with a build-time constant (`const buildYear = new Date().getFullYear()`) or move per-request timestamps into a client component inside `useEffect`. Do not pass dates as arguments to `'use cache'` functions — they invalidate the cache every call.
+
+**Citations:**
+- `https://nextjs.org/docs/app/api-reference/directives/use-cache`
+- `https://nextjs.org/docs/app/api-reference/functions/cacheLife`
+
+---

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

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