opencode-skills-collection 3.0.35 → 3.0.37

package/bundled-skills/vercel-optimize/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: vercel-optimize
+description: "Audit deployed Vercel apps for cost and performance issues using metrics, project config, code scans, and version-aware recommendations."
+risk: safe
+source: "https://github.com/vercel-labs/agent-skills"
+date_added: "2026-06-02"
+---
+
+# Vercel Optimize
+
+Run an observability-first Vercel optimization audit. Do not inspect source files until `signals.json` exists and a deterministic gate points to a route, file, or project setting.
+
+Core doctrine: read [references/doctrine.md](references/doctrine.md) if any rule is unclear.
+
+- Metrics first. Recommendations start from Vercel production signals, not repo-wide grep.
+- Deterministic gates. `scripts/gate-investigations.mjs` decides what deserves investigation.
+- Candidate-bound scope. Read only files named by a candidate or a route-local import chain.
+- Version-aware citations. Use only `references/docs-library.json`; invalid or version-mismatched citations are stripped.
+- Customer copy. Read [references/voice.md](references/voice.md) before writing report text or chat output.
+
+## When to Use
+- Use this skill when the task matches this description: Audit deployed Vercel apps for cost and performance issues using metrics, project config, code scans, and version-aware recommendations.
+
+## Prerequisites
+
+- Vercel CLI v53+ with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api`.
+- Authenticated CLI session: `vercel login`.
+- Linked app directory: `vercel link`. `VERCEL_PROJECT_ID` can help resolve project config, but `vercel metrics` still requires directory linkage. The link or environment must include the intended project org/team/user scope so the collector can resolve a CLI-safe `--scope` and keep `vercel metrics`, `vercel usage`, and `vercel contract` on the same account.
+- Node.js 20+.
+- Observability Plus for route-level metric-backed recommendations.
+
+Never put auth tokens in shell commands. Do not type `VERCEL_TOKEN=...`, `--token ...`, or `Authorization: Bearer ...` into commands that may be echoed in chat.
+
+## Framework Support
+
+The preflight reads `package.json` and sets expectations before metric fan-out.
+
+| Framework | Status | Notes |
+|---|---|---|
+| Next.js App Router | supported | strongest route mapping, scanners, playbooks, citations |
+| Next.js Pages Router | supported | scoped to Pages Router idioms when detected |
+| SvelteKit | supported | route mapping for `src/routes` files and SvelteKit scanner |
+| Nuxt | supported | route mapping plus generic/platform checks; fewer framework-specific recs |
+| Astro | limited | route mapping plus generic checks; fewer framework-specific recs |
+| Hono / Remix / unknown | blocked by default | continue only if the user accepts a limited platform/code-only audit |
+
+If unsupported, stop and ask before scanning or gating:
+
+```text
+This project uses <framework>. Vercel Optimize supports metric-backed code recommendations for Next.js, SvelteKit, and Nuxt. Astro support is limited. For <framework>, I can still run a limited platform/scanner audit, but route-level Vercel metrics may not map back to source files.
+
+Do you want me to continue with the limited audit, or stop here?
+```
+
+If the user continues, rerun collection with `--continue-unsupported-framework`.
+
+## Run Directory
+
+Use a fresh run directory for every audit. Do not reuse briefs, sub-agent outputs, or reports across runs.
+
+```bash
+RUN_DIR="$(mktemp -d -t vercel-optimize-XXXXXX)"
+```
+
+## Pipeline
+
+### 1. Collect, scan, and merge signals
+
+Run from the linked app directory or pass `--cwd` where a script supports it. Keep stdout JSON separate from stderr logs. Do not combine streams.
+
+```bash
+node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
+node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "$RUN_DIR/vercel-signals.json"
+
+node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
+node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"
+```
+
+Collection details, schemas, metric IDs, and degradation behavior live in [references/data-collection.md](references/data-collection.md). The metric registry is [lib/queries.mjs](lib/queries.mjs); keep all queries on the shared 14-day window.
+
+`collect-signals.mjs` resolves the linked project owner to `commandScope.cliScope` and verifies that the resolved account can read the resolved project before it checks Observability Plus. Downstream scripts reuse that scope for every Vercel CLI command that accepts `--scope`. Do not run `vercel usage`, `vercel metrics`, or `vercel contract` manually without the same scope; unscoped usage can report the user's personal organization while route metrics come from the team project.
+
+If project or scope resolution is ambiguous, stop and ask the user which Vercel project and team/personal scope they want audited. Do not infer the intended scope from the current `vercel whoami` team, and do not proceed with metrics, usage, or contract collection until the link, an exact project match in `.vercel/repo.json`, or `VERCEL_PROJECT_ID` + `VERCEL_ORG_ID` identifies the intended account.
+
+Use this prompt for `PROJECT_SCOPE_UNRESOLVED`, `SCOPE_UNRESOLVED`, or `PROJECT_SCOPE_MISMATCH`:
+
+```text
+I can't safely identify the Vercel project and account for this audit yet.
+
+Please confirm the Vercel project name or ID and the team slug/name, or tell me it's under your personal account. Once confirmed, I'll relink or rerun collection against that exact scope before checking metrics.
+```
+
+### 1.1 Stop on blockers
+
+Check blockers before gating:
+
+```bash
+jq '{frameworkSupportBlocker, observabilityPlus, observabilityPlusUsable, observabilityPlusBlocker, observabilityPlusBlockerDetail}' "$RUN_DIR/signals.json"
+```
+
+Required actions:
+
+- `frameworkSupportBlocker === "unsupported_framework"`: use the unsupported-framework prompt above.
+- `PROJECT_SCOPE_UNRESOLVED`, `SCOPE_UNRESOLVED`, or `PROJECT_SCOPE_MISMATCH`: stop and ask which Vercel project and team/personal scope the user wants audited. For team projects, rerun after `vercel link --yes --project <project-name-or-id> --team <team-slug>`; for personal projects, rerun after linking under the intended user account or after setting both `VERCEL_PROJECT_ID` and `VERCEL_ORG_ID`.
+- `observabilityPlusBlocker === null`: continue.
+- `no_traffic`: tell the user route metrics are sparse; continue only if they accept limited output.
+- `payment_required` or `no_oplus_probe`: render [references/observability-plus.md](references/observability-plus.md) verbatim and ask.
+- `project_disabled`: tell the user to enable Observability Plus for the project or accept a limited audit.
+- `daily_quota_exceeded`: stop and tell the user the Observability query quota is exhausted; retry after the next UTC midnight reset, or ask whether to continue with a limited code-only audit.
+- `not_linked`: link the app directory, then rerun Step 1. If app path and project are known:
+
+```bash
+vercel link --yes --project <project-name-or-id> --cwd <app-dir>
+# add --team <team-id-or-slug> when known
+```
+
+- `forbidden` or `project_not_found`: fix auth/team scope. Do not pitch Observability Plus.
+- `all_failed_other`: show the raw error code and ask whether to continue in limited code-only mode.
+
+Do not silently fall back to code-only mode. If the user accepts a limited audit, rerun collection with:
+
+```bash
+node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"
+```
+
+Then scan and merge again.
+
+### 2. Gate candidates
+
+```bash
+node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"
+```
+
+Output shape:
+
+- `toLaunch`: code-scope candidates to investigate.
+- `platform`: project/account-scope recommendations.
+- `gated`: skipped, covered, or disqualified candidates that must still appear in the report.
+- `budget`: candidate budget and selection mode.
+
+Default budget is 6 code-scope candidates with a diversity guardrail. To expand:
+
+```bash
+node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates 12 > "$RUN_DIR/gate.json"
+node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" --max-candidates all > "$RUN_DIR/gate.json"
+```
+
+Generated candidate docs: [references/candidates.md](references/candidates.md).
+
+### 2.1 Ask about audit scope when needed
+
+Before deep-dive, run:
+
+```bash
+node scripts/budget-summary.mjs "$RUN_DIR/gate.json" --format json > "$RUN_DIR/budget-summary.json"
+```
+
+If `shouldAsk` is false, continue.
+
+If `shouldAsk` is true:
+
+1. Print `exactChatMessage.body` exactly as returned. Do not summarize, truncate, reorder, or rewrite it.
+2. Then ask `questionText` using `questionPayload` when the host supports structured questions.
+3. If the user chooses a different number, rerun the gate with `--max-candidates <choice>`.
+
+Never put the long preview inside the question field. The preview and the question are separate surfaces.
+
+### 2.2 Deep-dive and reconcile
+
+```bash
+node scripts/deep-dive.mjs "$RUN_DIR/signals.json" "$RUN_DIR/gate.json" --cwd <project-dir> > "$RUN_DIR/investigation-evidence.json"
+
+node scripts/reconcile-candidates.mjs "$RUN_DIR/investigation-evidence.json" \
+  --gate "$RUN_DIR/gate.json" \
+  --out "$RUN_DIR/reconciled-investigation.json"
+```
+
+`--cwd` must be the linked project directory so `deep-dive.mjs` can verify the same project link and reuse `signals.json.commandScope.cliScope` for any follow-up `vercel metrics` calls.
+
+Reconciliation deterministically converts disproven candidates into observations before any source investigation:
+
+- `metric_mismatch`
+- `error_storm`
+- `deployment_regression`
+- `scanner_only_no_metric`
+
+### 2.3 Generate briefs and investigate
+
+List the work:
+
+```bash
+node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" --list > "$RUN_DIR/briefs-manifest.json"
+```
+
+Generate one brief for every entry in `briefs-manifest.json.briefs`. The `group` can be `toLaunch` or `platform`; do not generate only `toLaunch` briefs.
+
+```bash
+mkdir -p "$RUN_DIR/briefs" "$RUN_DIR/sub-agent-outputs"
+node scripts/prepare-investigation-brief.mjs "$RUN_DIR/signals.json" "$RUN_DIR/reconciled-investigation.json" \
+  --group <brief.group> --index <brief.index> --out "$RUN_DIR/briefs/<brief.group>-<brief.index>.md"
+```
+
+Use `briefs-manifest.json.briefs[].label` for visible worker names, for example `Low cache-hit route on /docs/llm-digest/[...slug]`, not `toLaunch-7`.
+
+Fan-out rule:
+
+- 1-2 briefs: investigate inline.
+- 3+ briefs: spawn one sub-agent per brief when the host supports it.
+- Hosts without sub-agents: run inline serially.
+
+Sub-agent contract:
+
+- The brief is the whole prompt.
+- Read only files listed in the brief, plus route-local imports when needed.
+- Emit one JSON recommendation or one JSON no-change finding using [references/recommendations.md](references/recommendations.md).
+- Do not cite URLs outside the provided citation subset.
+- Do not recommend framework features unavailable in the detected version.
+
+If a sub-agent reaches for repo-wide grep, the candidate is malformed; drop or abstain rather than widening scope.
+
+### 2.4 Collect outputs
+
+Save each raw investigation result in `$RUN_DIR/sub-agent-outputs/`, then collect:
+
+```bash
+node scripts/collect-sub-agent-outputs.mjs \
+  --manifest "$RUN_DIR/briefs-manifest.json" \
+  --out "$RUN_DIR/recommendations.json" \
+  "$RUN_DIR/sub-agent-outputs/"
+```
+
+The collector extracts JSON, prepends pre-resolved records, enforces manifest order, and fails on missing, duplicate, unknown, or mismatched `candidateRef` values.
+
+### 3. Verify recommendations
+
+```bash
+node scripts/verify-and-regen.mjs "$RUN_DIR/recommendations.json" \
+  --signals "$RUN_DIR/signals.json" \
+  --repo-root <project-dir> \
+  --out "$RUN_DIR/verify.json"
+```
+
+This script extracts claims, verifies files/citations/version fit, grades quality, applies sanitizers, emits `verifiedRecommendations`, `withheldRecommendations`, `renderableRecommendations`, and creates `regenPlan` for failed or unsafe recommendations.
+
+Recommendation schema, writing rules, sanitizer order, and grading rules: [references/recommendations.md](references/recommendations.md). Verification rules: [references/verification.md](references/verification.md).
+
+For each `regenPlan` entry, rerun the same brief with a `Previous attempt failed these checks` section listing `topFailures`. Keep the regenerated output only if verification improves without gutting citations.
+
+### 4. Render report and final message
+
+```bash
+node scripts/render-report.mjs "$RUN_DIR/verify.json" "$RUN_DIR/gate.json" "$RUN_DIR/signals.json" \
+  --project <name> \
+  --out "$RUN_DIR/report.md" \
+  --message-out "$RUN_DIR/final-message.json"
+```
+
+Use `--debug-out "$RUN_DIR/debug.json"` only when developing the skill. Customer Markdown and chat output must not expose `passRate`, `quality`, sanitizer trails, raw sub-agent names, or other implementation fields.
+
+After rendering, print `final-message.json.body` verbatim and stop. Do not add highlights, debug notes, raw counts, sub-agent summaries, or extra explanation. Render-time dedupe, platform caps, and hard-safety drops can change the customer-visible count, so never summarize from raw `verify.json`.
+
+Report structure and impact framing: [references/scoring.md](references/scoring.md).
+
+## Recommendation Rules
+
+Every recommendation must:
+
+- Trace to a launched candidate, platform candidate, pre-resolved observation, or verified traffic-independent scanner finding.
+- Include observed metric evidence from `signals.json` or `evidence.deepDive`.
+- Cite verified files with line numbers when code is involved.
+- Include at least one allowed citation that applies to the detected framework/version.
+- Use precise observed performance numbers.
+- Use cost magnitude phrases only; never customer-facing `$N` savings.
+- Do not recommend duration reductions for Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`). These are generated orchestration routes for durable step/flow execution and should be hard-gated before investigation.
+- Workflow recommendations must name the boundary being changed. Valid examples: enqueue durable work and return a run ID instead of awaiting completion, fix stream replay/closure/locks, or reduce verified excess Workflow Steps/Storage. Do not infer cost savings from Workflow endpoint wall-clock duration.
+- For streaming, SSE, resumable chat, or other intentionally long-lived routes, do not frame wall-clock function duration as a problem by itself. Require evidence of avoidable pre-first-byte work, high active CPU, duplicate invocations, or post-response work that can move out of the user-visible path.
+- Name a specific cache policy when recommending caching.
+- Keep unsafe responses dynamic unless evidence proves they are safe to cache: auth-sensitive paths, errors, fallback responses, missing content, invalid requests, geolocation/device-varying output, and unversioned dynamic URLs.
+
+Never recommend "verify X is on" for facts already present in `signals.project`, including Fluid compute status, memory tier, regions, in-function concurrency, and timeout.
+
+## Scanner Rules
+
+Scanner findings are supplementary. Drop findings annotated `COLD-PATH` or `NO-ROUTE-MAPPING` unless the scanner declares `metadata.trafficIndependent === true`.
+
+Traffic-independent examples: middleware matcher, source maps, React Compiler config, build settings. Route-local cache or data-fetch patterns need route-level traffic evidence.
+
+Scanner docs: [references/scanner-patterns.md](references/scanner-patterns.md).
+
+## Final Customer Terms
+
+Use:
+
+- `recommendations ready`
+- `observations from investigation`
+- `investigated, no change recommended`
+- `not investigated in this run`
+
+Avoid:
+
+- `sub-agent`
+- `abstention`
+- `passRate`
+- `quality score`
+- `gate`
+- `LLM`
+
+## Failure Copy
+
+Use these messages without adding sales copy or process detail.
+
+**No traffic in the last 14 days:**
+
+> This project has no meaningful traffic in the last 14 days, so route-level metrics are sparse. I can still check traffic-independent scanner findings and project settings, but I cannot rank route fixes until traffic accumulates.
+
+**Route-level metrics unavailable:**
+
+> Use the verbatim choice template in [references/observability-plus.md](references/observability-plus.md). Do not silently fall back to code-only mode; present the two-path choice: enable Observability Plus and rerun the metric-backed audit, or accept a limited code-only run.
+
+**Project is not linked:**
+
+> This worktree is not linked to a Vercel project. Run `vercel link --yes --project <project-name-or-id> --cwd <app-dir>` and rerun the audit. If the team is known, add `--team <team-id-or-slug>`.
+
+**Most route-to-file mappings failed:**
+
+> The route inventory matched fewer than half of the routes we saw in observability. This is common in monorepos with custom routing. I've surfaced what I can match; the rest appear in the "Not investigated in this run" section.
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/vercel-optimize/lib/auth-route.mjs

@@ -0,0 +1,23 @@
+// Auth routes carry user state and must not be cached at CDN edge.
+
+export const AUTH_ROUTE_REGEX =
+  /(login|logout|auth|account|dashboard|checkout|cart|profile|session|me)(?:\/|$)/i;
+
+export function isAuthRoute(route) {
+  return AUTH_ROUTE_REGEX.test(String(route ?? ''));
+}
+
+// Non-cache candidates pass through — errors/slowness on auth routes still warrant investigation.
+export function applyAuthDisqualifier(candidate) {
+  const cacheKinds = new Set(['uncached_route', 'cache_header_gap']);
+  if (!cacheKinds.has(candidate.kind)) return candidate;
+  if (!candidate.route) return candidate;
+  if (isAuthRoute(candidate.route)) {
+    return {
+      ...candidate,
+      disqualified: true,
+      disqualifyReason: 'auth-like route — should not be cached at edge',
+    };
+  }
+  return candidate;
+}

package/bundled-skills/vercel-optimize/lib/budget-summary.mjs

@@ -0,0 +1,182 @@
+// Checkpoint between gate and deep-dive. Asks only when budget was default AND >=1 candidate got skipped — every question is a tax on the user.
+
+import { createHash } from 'node:crypto';
+import { formatCandidateLine } from './display-labels.mjs';
+
+const TOP_INVESTIGATING_PREVIEW = 5;
+const MAX_FULL_INVESTIGATING_PREVIEW = 10;
+export function buildBudgetSummary(gate) {
+  const toLaunch = Array.isArray(gate?.toLaunch) ? gate.toLaunch : [];
+  const gated = Array.isArray(gate?.gated) ? gate.gated : [];
+  const budgetSource = gate?.budget?.source ?? 'default';
+  const currentBudget =
+    typeof gate?.budget?.maxCandidates === 'number'
+      ? gate.budget.maxCandidates
+      : (gate?.budget?.maxCandidates === 'all' ? Infinity : 6);
+
+  // Only budget skips can be reached by raising the budget; disqualified/coveredBy can't.
+  const skippedByBudget = gated.filter((g) =>
+    typeof g.gatedReason === 'string' && g.gatedReason.startsWith('skippedByBudget')
+  );
+  const skipped = skippedByBudget.length;
+  const totalPassed = toLaunch.length + skipped;
+
+  const reasonParts = [];
+  if (budgetSource !== 'default') reasonParts.push(`user pre-set budget via ${budgetSource}`);
+  if (skipped === 0) reasonParts.push('no candidates skipped by budget');
+  const shouldAsk = budgetSource === 'default' && skipped > 0;
+  const reason = shouldAsk
+    ? `default budget skipped ${skipped} candidate(s); ask user whether to expand`
+    : reasonParts.join('; ') || 'no expansion possible';
+
+  const summarize = (c) => ({
+    kind: c.kind,
+    route: c.route ?? c.hostname ?? null,
+    displayRoute: c.displayRoute ?? null,
+    o11ySignal: c.o11ySignal ?? null,
+    priority: c.priority ?? null,
+  });
+
+  const investigatingPreviewCount = typeof currentBudget === 'number' && currentBudget <= MAX_FULL_INVESTIGATING_PREVIEW
+    ? currentBudget
+    : TOP_INVESTIGATING_PREVIEW;
+  const topInvestigating = toLaunch.slice(0, investigatingPreviewCount).map(summarize);
+  const topSkipped = skippedByBudget.map(summarize);
+  const options = buildOptions(toLaunch.length, skipped);
+  const questionText = buildQuestionText({ shouldAsk, totalPassed, currentBudget });
+  const printContract = shouldAsk
+    ? 'Print chatPreview verbatim by copying exactChatMessage.body as a chat message before asking questionText. Do not summarize, truncate, reorder, shorten, or rewrite options.'
+    : null;
+  const questionPayload = shouldAsk ? buildQuestionPayload(questionText, options) : null;
+  const chatPreview = buildChatPreview({ shouldAsk, totalPassed, currentBudget, skipped, topInvestigating, topSkipped, reason });
+  const exactChatMessage = buildExactChatMessage(chatPreview);
+  return {
+    shouldAsk,
+    reason,
+    totalPassed,
+    currentBudget: currentBudget === Infinity ? 'all' : currentBudget,
+    budgetSource,
+    skipped,
+    topInvestigating,
+    topSkipped,
+    options,
+    printContract,
+    chatPreview,
+    exactChatMessage,
+    printCheck: shouldAsk ? buildPrintCheck({ exactChatMessage, skipped }) : null,
+    questionText,
+    questionPayload,
+  };
+}
+
+function buildChatPreview({ shouldAsk, totalPassed, currentBudget, skipped, topInvestigating, topSkipped, reason }) {
+  if (!shouldAsk) return `Audit scope: no question needed — ${reason}.`;
+  const lines = [];
+  lines.push(`Found ${totalPassed} potential issue${totalPassed === 1 ? '' : 's'} worth checking. By default I'll inspect the ${currentBudget} strongest now; ${skipped} will stay in the report for a larger run.`);
+  lines.push(`Choose a larger scope if you want broader coverage. More checks take longer.`);
+  if (topInvestigating.length > 0) {
+    lines.push('');
+    lines.push(`Checking now${topInvestigating.length < currentBudget ? ` (${topInvestigating.length} shown)` : ''}:`);
+    topInvestigating.forEach((c, i) => lines.push(`  ${i + 1}. ${formatCandidateLine(c)}`));
+  }
+  if (topSkipped.length > 0) {
+    lines.push('');
+    lines.push(`Only checked if you expand this run (${topSkipped.length}):`);
+    topSkipped.forEach((c, i) => lines.push(`  ${i + 1}. ${formatCandidateLine(c)}`));
+  }
+  return lines.join('\n');
+}
+
+function buildExactChatMessage(body) {
+  return {
+    body,
+    lineCount: body.split('\n').length,
+    sha256: createHash('sha256').update(body).digest('hex'),
+  };
+}
+
+function buildPrintCheck({ exactChatMessage, skipped }) {
+  return {
+    bodyField: 'exactChatMessage.body',
+    sameAs: 'chatPreview',
+    requiredLineCount: exactChatMessage.lineCount,
+    requiredSha256: exactChatMessage.sha256,
+    requiredSkippedRows: skipped,
+    requiredSkippedHeading: `Only checked if you expand this run (${skipped}):`,
+    forbiddenSummaryPatterns: [
+      '\\btop skipped\\b',
+      '\\bmore (?:candidate|candidates|routes|entries|items|in gated list)\\b',
+      '\\b\\d+\\s*[-–—]\\s*\\d+\\.\\s+\\d+\\s+more\\b',
+      '\\betc\\.\\b',
+    ],
+    instruction: 'The budget message is valid only when every line from exactChatMessage.body is preserved exactly. If you cannot verify that, print exactChatMessage.body again before asking the question.',
+  };
+}
+
+function buildQuestionText({ shouldAsk, totalPassed, currentBudget }) {
+  if (!shouldAsk) return '';
+  return `How many potential issues should I check in this run?`;
+}
+
+function buildOptions(currentCount, skippedCount) {
+  if (skippedCount === 0) return [];
+  const total = currentCount + skippedCount;
+  return [
+    {
+      label: `Check ${currentCount} (default)`,
+      value: currentCount,
+      recommended: true,
+      description: 'Fastest first pass; checks the strongest cost and performance signals.',
+      rationale: 'fastest first pass; checks the strongest cost and performance signals',
+    },
+    {
+      label: `Check all ${total}`,
+      value: 'all',
+      recommended: false,
+      description: 'Most complete; takes longer because every flagged route is investigated.',
+      rationale: 'most complete; takes longer because every flagged route is investigated',
+    },
+    {
+      label: 'Pick a number',
+      value: 'custom',
+      recommended: false,
+      description: `Check more than ${currentCount} without running the full ${total}.`,
+      rationale: `checks more than ${currentCount} without running the full ${total}`,
+    },
+  ];
+}
+
+function buildQuestionPayload(questionText, options) {
+  return {
+    questions: [{
+      question: questionText,
+      header: 'Audit scope',
+      multiSelect: false,
+      options: options.map((o) => ({
+        label: o.label,
+        description: o.description ?? o.rationale,
+      })),
+    }],
+  };
+}
+
+export function renderBudgetSummaryMarkdown(s) {
+  const lines = [];
+  lines.push(`## Audit scope`);
+  lines.push('');
+  if (!s.shouldAsk) {
+    lines.push(`_No question needed — ${s.reason}._`);
+    return lines.join('\n');
+  }
+  for (const ln of s.chatPreview.split('\n')) lines.push(ln);
+  lines.push('');
+  lines.push('### Options');
+  lines.push('');
+  for (const o of s.options) {
+    const tag = o.recommended ? ' (recommended)' : '';
+    lines.push(`- **${o.label}${tag}** — ${o.rationale}`);
+  }
+  lines.push('');
+  lines.push(`**Question:** ${s.questionText}`);
+  return lines.join('\n');
+}

package/bundled-skills/vercel-optimize/lib/citations.mjs

@@ -0,0 +1,139 @@
+// Curated doc library — the allow-list for recommender citations.
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const LIBRARY_PATH = join(HERE, '..', 'references', 'docs-library.json');
+
+let cached;
+
+export async function loadLibrary() {
+  if (cached) return cached;
+  const raw = await readFile(LIBRARY_PATH, 'utf-8');
+  cached = JSON.parse(raw);
+  return cached;
+}
+
+export async function isKnownUrl(url) {
+  const lib = await loadLibrary();
+  return lib.urls.some(e => e.url === url);
+}
+
+export async function lookupUrl(url) {
+  const lib = await loadLibrary();
+  return lib.urls.find(e => e.url === url);
+}
+
+export async function lookupSkillRule(ref) {
+  const lib = await loadLibrary();
+  const m = ref.match(/^([\w-]+):([\w-]+)$/);
+  if (!m) return undefined;
+  return lib.ruleSkillRefs.find(r => r.skill === m[1] && r.rule === m[2]);
+}
+
+// Narrow semver subset: "*", "fw@*", "fw@14", "fw@>=15.0.0", "fw@<X", "fw@X.Y", "fw@X.Y.Z", "a || b".
+export function matchesFrameworkVersion(pattern, framework, version) {
+  if (pattern === '*') return true;
+
+  if (pattern.includes('||')) {
+    return pattern.split('||').map(p => p.trim()).some(p =>
+      matchesFrameworkVersion(p, framework, version)
+    );
+  }
+
+  const m = pattern.match(/^([\w-]+)@(.+)$/);
+  if (!m) return false;
+  const [, fw, range] = m;
+
+  if (fw !== framework) return false;
+  if (range === '*') return true;
+
+  const verParts = parseVersion(version);
+  if (!verParts) return false;
+
+  let m2 = range.match(/^>=\s*(.+)$/);
+  if (m2) {
+    const min = parseVersion(m2[1]);
+    return min ? compareVersion(verParts, min) >= 0 : false;
+  }
+
+  m2 = range.match(/^<\s*(.+)$/);
+  if (m2) {
+    const max = parseVersion(m2[1]);
+    return max ? compareVersion(verParts, max) < 0 : false;
+  }
+
+  if (/^\d+$/.test(range)) {
+    return verParts[0] === Number(range);
+  }
+
+  m2 = range.match(/^(\d+)\.(\d+)$/);
+  if (m2) {
+    return verParts[0] === Number(m2[1]) && verParts[1] === Number(m2[2]);
+  }
+
+  const exact = parseVersion(range);
+  if (exact) return compareVersion(verParts, exact) === 0;
+
+  return false;
+}
+
+function parseVersion(v) {
+  const m = String(v).replace(/^[v^~]+/, '').match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!m) return null;
+  return [Number(m[1]) || 0, Number(m[2]) || 0, Number(m[3]) || 0];
+}
+
+function compareVersion(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}
+
+// Filtered subset embedded in recommender prompt — LLM never sees URLs for features not in user's stack.
+export async function libraryForStack(framework, version) {
+  const lib = await loadLibrary();
+  const matches = (frameworks) =>
+    frameworks.some(p => matchesFrameworkVersion(p, framework, version) || p === '*');
+  return {
+    urls: lib.urls.filter(e => matches(e.applicableFrameworks)),
+    ruleSkillRefs: lib.ruleSkillRefs.filter(r => matches(r.applicableFrameworks)),
+  };
+}
+
+export async function sanitizeCitations(rec, framework, version) {
+  const lib = await loadLibrary();
+  const strippedUnknown = [];
+  const strippedVersion = [];
+  const kept = [];
+
+  for (const cite of rec.citations ?? []) {
+    const ruleRef = await lookupSkillRule(cite);
+    if (ruleRef) {
+      if (matchesFrameworkVersion(ruleRef.applicableFrameworks.join(' || '), framework, version) || ruleRef.applicableFrameworks.includes('*')) {
+        kept.push(cite);
+      } else {
+        strippedVersion.push(cite);
+      }
+      continue;
+    }
+
+    const entry = lib.urls.find(e => e.url === cite);
+    if (!entry) {
+      strippedUnknown.push(cite);
+      continue;
+    }
+    if (entry.applicableFrameworks.includes('*') ||
+        entry.applicableFrameworks.some(p => matchesFrameworkVersion(p, framework, version))) {
+      kept.push(cite);
+    } else {
+      strippedVersion.push(cite);
+    }
+  }
+
+  rec.citations = kept;
+  return { rec, strippedUnknown, strippedVersion };
+}