@oriro/orirocli 0.1.11 → 0.1.12

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

@@ -1,108 +1,108 @@
-# Doctrine
-
-The four non-negotiable rules that shape every action this skill takes. If a future change conflicts with one of these, the change is wrong.
-
-## Rule 1: Observability before investigation
-
-The skill never reads a source file without an observability signal pointing at it. Step 1 (`node scripts/collect-signals.mjs`) is always first. Nothing reads source code until `signals.json` exists.
-
-**Why this fails when skipped:** without metrics, the skill defaults to "grep the repo for known anti-patterns and complain." That produces noisy, low-impact recs that aren't tied to traffic, cost, or user pain. Metrics-first investigation keeps the skill focused on observed traffic, cost, and reliability signals.
-
-### Four-check first-pass (Enterprise)
-
-When `plan === 'enterprise'`, the gate run must surface these four checks before code-level recommendations. Field engineers confirm these are the highest-leverage account-level levers across every renewal audit:
-
-1. **Observability Plus enabled?** From `signals.observabilityPlus`. If false, the whole audit degrades; surface as a top-of-report item.
-2. **Reverse proxy in front?** Heuristic from response headers / CNAME chain (when collected). A non-Vercel CDN over Vercel ISR is usually a "dumb pipe" — wasted spend.
-3. **WAF rules enabled?** From `signals.project.security`. BotID + managed rules absent on a project with bot evidence is the most common cost spike.
-4. **ISR read:write ratio.** From `metrics.isrReadsByRoute` + `metrics.isrWritesByRoute`. Include CDN-tier reads (see [data-collection.md](data-collection.md)) before flagging "writes > reads."
-
-These checks anchor the Enterprise-tier report's opening narrative; code-level recs follow.
-
-## Rule 2: Deterministic gate before every sub-agent investigation
-
-`node scripts/gate-investigations.mjs` is a pure-JS, LLM-free function. It reads `signals.json` and outputs `{toLaunch, platform, gated}`. Same input always produces byte-identical output (modulo `appliedAt`).
-
-Every kind of candidate (uncached route, slow route, errors, cold starts, scanner findings, platform-level recs) has its threshold expression encoded as a `gate(signals) → Candidate[]` function in `lib/gates/<kind>.mjs`.
-
-**Failed gates surface in the final report**, under "Not investigated in this run," with the exact reason they were held back. This is the user-facing trust mechanism: you see what we considered and chose to skip, and the reason.
-
-**Why this matters:** the agent never decides "should I look at this route?" via LLM judgment. The threshold is mechanical. This eliminates the entire failure mode where the agent investigates routes it shouldn't (cold-path) and recommends fixes for routes that don't need them.
-
-## Rule 3: Candidate-bound investigation scope
-
-When the gate emits a candidate with `files: ['src/app/api/products/route.ts']`, the agent reads ONLY that file (and its imports as the chain unfolds). It does NOT `grep -r` across the repo.
-
-If you find yourself wanting to grep the whole codebase, stop and re-read the current candidate's `question` field. If the question doesn't constrain the search, the candidate is malformed — log it as `gated` and skip. Do NOT compensate with a wider search.
-
-**Why this matters:** the agent's job is to verify and explain the metric anomaly the gate found, not to do a general code review. Wandering investigations produce drift, hallucination, and recommendations untied to the cost and performance data.
-
-### Scanner findings (the supplementary signal)
-
-Static AST-grep scanners run in parallel with the metric-driven investigations. Their output is annotated with the per-file observability signal (`function invocations: 1.2M; 95th percentile duration: 850ms; cache hit rate: 0%` if the file maps to a hot route, `COLD-PATH` if it maps to a route with no traffic, `NO-ROUTE-MAPPING` if the file doesn't map to any route).
-
-**Default rule:** scanner findings on `COLD-PATH` or `NO-ROUTE-MAPPING` files are dropped. They become recs only if the pattern is _traffic-independent_: build configuration, middleware matcher, source maps in production, raw script tags, React Compiler config. These don't care about traffic — they affect every request equally or affect the build itself.
-
-The traffic-independent allow-list lives in each scanner's `metadata.trafficIndependent: boolean` field. Set it to `true` only when you can defend the claim.
-
-## Rule 4: Doc-grounded, version-aware recommendations — no hallucinations
-
-Every recommendation must carry at least one citation from `references/docs-library.json`. Anything else is dropped at sanitizer time.
-
-The library has two parts:
-
-- **URLs** — Vercel docs, Next.js docs, SvelteKit docs, etc. Each declares `applicableFrameworks` (e.g., `["next@>=15.0.0"]`).
-- **Cross-skill rule references** — by name only (`vercel-react-best-practices:async-parallel`). The agent's host resolves these.
-
-Three sanitizers enforce this:
-
-- `missing-citation` — drops recs with empty `citations[]`.
-- `unknown-citation` — strips URLs not in the library, marks `needsReview=true`.
-- `version-mismatch` — strips URLs whose `applicableFrameworks` doesn't match the project's framework@version (parsed from `package.json`).
-
-Two verifier claim types check it: `citation_in_library` (URL ∈ allow-list) and `citation_applies_to_version` (semver match).
-
-**Why this matters:** LLMs cite plausible-looking URLs that 404, or recommend Next 15 features to Next 13 users. Both are trust-killers. The allow-list closes the first failure mode; the `applicableFrameworks` field closes the second.
-
-### Performance citations cite observed data
-
-Every performance claim cites the actual observability datum from `signals.json` — e.g., `functionRoutes[/api/products].p95Ms=850`. Estimated improvements are framed as ranges grounded in the observed baseline: `"Reduce /api/products 95th percentile duration from 850ms toward ~250-400ms based on similar cached routes."` Never an unanchored claim.
-
-### Cost framing is magnitude, never precise
-
-Cost claims like `$340/mo` are forbidden. The dollar noise floor on projections is too high to justify precision. The `impactMagnitude({currentCost, impactTier})` helper maps to phrases like `"hundreds of dollars per month at current traffic"` (computed against the user's actual `vercel usage` data).
-
-The `$-strip` sanitizer enforces this at output time — any `$N` literal in customer-facing fields is stripped.
-
-Performance numbers stay precise because they're observed, not extrapolated. We trust observed metrics; we don't trust dollar projections.
-
-## What good looks like
-
-A good run produces:
-
-- A small number (5-15) of recommendations.
-- Every rec ties to a specific route or file plus a specific metric signal.
-- Every rec carries before/after code and ≥1 citation matching the user's framework version.
-- Cost framing uses magnitude phrases. Performance framing uses precise observed numbers.
-- The "Not investigated in this run" section explains every other signal we saw and why we chose not to dig (cache hit rate was below threshold, 95th percentile duration was already healthy, etc.).
-- No `$N/mo` strings, no fabricated URLs, no Next.js 15 features recommended to a Next.js 13 user.
-
-## What bad looks like (anti-patterns we will not ship)
-
-- Recommendations from grepping the repo for known anti-patterns, without checking traffic.
-- "Enable Fluid Compute" without a cold-start signal.
-- "Add caching to /api/users" when the route has cookies() and is auth-gated.
-- "Reduce the duration of `/.well-known/workflow/v1/step`" because a Workflow step is long-running. Workflow runtime endpoints are generated orchestration routes; high wall-clock duration there is expected unless a separate reliability/error signal points elsewhere.
-- "Fix `/api/chat/[id]/stream` because it has high duration" without proving the stream does avoidable pre-first-byte work, high active CPU, duplicate invocations, or movable post-response work.
-- "Save $340/mo by doing X" — invented precision.
-- Citations to URLs that don't exist or that describe Next.js features the user's version doesn't have.
-- Long lists of recs the user can't act on; every rec needs an evidence chain.
-
-## Out of scope
-
-The skill is bounded to runtime cost and performance optimization on Vercel-hosted projects. The following are explicit non-goals; if signals or scanner findings surface in these areas, route them out:
-
-- **Deployment artifact size** in isolation. Bundle size matters only when it shows up as runtime cost (cold start, FDT) or performance (LCP, INP). If the only effect is "the .next directory is large," it's not in scope.
-- **Build-time issues without runtime impact.** Slow builds, build-cache misses, monorepo build fan-out — these only enter scope when they show up as Build Minutes billing pressure (then they go through the `build-minutes-fanout` gate). A 6-minute build that completes successfully and ships a small artifact is not a target.
-- **Security advisories and credential rotation.** RCE in `next-mdx-remote`, leaked env vars, OIDC vs explicit-key auth hygiene — refer to a security skill, not this one. Exception: when a security setting is also a documented cost lever (BotID = bot traffic = edge cost), it enters via the `platform_bot_protection` gate.
-- **Commercial / billing-process trivia.** Discount sliders, seat reconciliation, contract renewal mechanics. The skill can quantify which SKU is expensive; it does not negotiate.
+# Doctrine
+
+The four non-negotiable rules that shape every action this skill takes. If a future change conflicts with one of these, the change is wrong.
+
+## Rule 1: Observability before investigation
+
+The skill never reads a source file without an observability signal pointing at it. Step 1 (`node scripts/collect-signals.mjs`) is always first. Nothing reads source code until `signals.json` exists.
+
+**Why this fails when skipped:** without metrics, the skill defaults to "grep the repo for known anti-patterns and complain." That produces noisy, low-impact recs that aren't tied to traffic, cost, or user pain. Metrics-first investigation keeps the skill focused on observed traffic, cost, and reliability signals.
+
+### Four-check first-pass (Enterprise)
+
+When `plan === 'enterprise'`, the gate run must surface these four checks before code-level recommendations. Field engineers confirm these are the highest-leverage account-level levers across every renewal audit:
+
+1. **Observability Plus enabled?** From `signals.observabilityPlus`. If false, the whole audit degrades; surface as a top-of-report item.
+2. **Reverse proxy in front?** Heuristic from response headers / CNAME chain (when collected). A non-Vercel CDN over Vercel ISR is usually a "dumb pipe" — wasted spend.
+3. **WAF rules enabled?** From `signals.project.security`. BotID + managed rules absent on a project with bot evidence is the most common cost spike.
+4. **ISR read:write ratio.** From `metrics.isrReadsByRoute` + `metrics.isrWritesByRoute`. Include CDN-tier reads (see [data-collection.md](data-collection.md)) before flagging "writes > reads."
+
+These checks anchor the Enterprise-tier report's opening narrative; code-level recs follow.
+
+## Rule 2: Deterministic gate before every sub-agent investigation
+
+`node scripts/gate-investigations.mjs` is a pure-JS, LLM-free function. It reads `signals.json` and outputs `{toLaunch, platform, gated}`. Same input always produces byte-identical output (modulo `appliedAt`).
+
+Every kind of candidate (uncached route, slow route, errors, cold starts, scanner findings, platform-level recs) has its threshold expression encoded as a `gate(signals) → Candidate[]` function in `lib/gates/<kind>.mjs`.
+
+**Failed gates surface in the final report**, under "Not investigated in this run," with the exact reason they were held back. This is the user-facing trust mechanism: you see what we considered and chose to skip, and the reason.
+
+**Why this matters:** the agent never decides "should I look at this route?" via LLM judgment. The threshold is mechanical. This eliminates the entire failure mode where the agent investigates routes it shouldn't (cold-path) and recommends fixes for routes that don't need them.
+
+## Rule 3: Candidate-bound investigation scope
+
+When the gate emits a candidate with `files: ['src/app/api/products/route.ts']`, the agent reads ONLY that file (and its imports as the chain unfolds). It does NOT `grep -r` across the repo.
+
+If you find yourself wanting to grep the whole codebase, stop and re-read the current candidate's `question` field. If the question doesn't constrain the search, the candidate is malformed — log it as `gated` and skip. Do NOT compensate with a wider search.
+
+**Why this matters:** the agent's job is to verify and explain the metric anomaly the gate found, not to do a general code review. Wandering investigations produce drift, hallucination, and recommendations untied to the cost and performance data.
+
+### Scanner findings (the supplementary signal)
+
+Static AST-grep scanners run in parallel with the metric-driven investigations. Their output is annotated with the per-file observability signal (`function invocations: 1.2M; 95th percentile duration: 850ms; cache hit rate: 0%` if the file maps to a hot route, `COLD-PATH` if it maps to a route with no traffic, `NO-ROUTE-MAPPING` if the file doesn't map to any route).
+
+**Default rule:** scanner findings on `COLD-PATH` or `NO-ROUTE-MAPPING` files are dropped. They become recs only if the pattern is _traffic-independent_: build configuration, middleware matcher, source maps in production, raw script tags, React Compiler config. These don't care about traffic — they affect every request equally or affect the build itself.
+
+The traffic-independent allow-list lives in each scanner's `metadata.trafficIndependent: boolean` field. Set it to `true` only when you can defend the claim.
+
+## Rule 4: Doc-grounded, version-aware recommendations — no hallucinations
+
+Every recommendation must carry at least one citation from `references/docs-library.json`. Anything else is dropped at sanitizer time.
+
+The library has two parts:
+
+- **URLs** — Vercel docs, Next.js docs, SvelteKit docs, etc. Each declares `applicableFrameworks` (e.g., `["next@>=15.0.0"]`).
+- **Cross-skill rule references** — by name only (`vercel-react-best-practices:async-parallel`). The agent's host resolves these.
+
+Three sanitizers enforce this:
+
+- `missing-citation` — drops recs with empty `citations[]`.
+- `unknown-citation` — strips URLs not in the library, marks `needsReview=true`.
+- `version-mismatch` — strips URLs whose `applicableFrameworks` doesn't match the project's framework@version (parsed from `package.json`).
+
+Two verifier claim types check it: `citation_in_library` (URL ∈ allow-list) and `citation_applies_to_version` (semver match).
+
+**Why this matters:** LLMs cite plausible-looking URLs that 404, or recommend Next 15 features to Next 13 users. Both are trust-killers. The allow-list closes the first failure mode; the `applicableFrameworks` field closes the second.
+
+### Performance citations cite observed data
+
+Every performance claim cites the actual observability datum from `signals.json` — e.g., `functionRoutes[/api/products].p95Ms=850`. Estimated improvements are framed as ranges grounded in the observed baseline: `"Reduce /api/products 95th percentile duration from 850ms toward ~250-400ms based on similar cached routes."` Never an unanchored claim.
+
+### Cost framing is magnitude, never precise
+
+Cost claims like `$340/mo` are forbidden. The dollar noise floor on projections is too high to justify precision. The `impactMagnitude({currentCost, impactTier})` helper maps to phrases like `"hundreds of dollars per month at current traffic"` (computed against the user's actual `vercel usage` data).
+
+The `$-strip` sanitizer enforces this at output time — any `$N` literal in customer-facing fields is stripped.
+
+Performance numbers stay precise because they're observed, not extrapolated. We trust observed metrics; we don't trust dollar projections.
+
+## What good looks like
+
+A good run produces:
+
+- A small number (5-15) of recommendations.
+- Every rec ties to a specific route or file plus a specific metric signal.
+- Every rec carries before/after code and ≥1 citation matching the user's framework version.
+- Cost framing uses magnitude phrases. Performance framing uses precise observed numbers.
+- The "Not investigated in this run" section explains every other signal we saw and why we chose not to dig (cache hit rate was below threshold, 95th percentile duration was already healthy, etc.).
+- No `$N/mo` strings, no fabricated URLs, no Next.js 15 features recommended to a Next.js 13 user.
+
+## What bad looks like (anti-patterns we will not ship)
+
+- Recommendations from grepping the repo for known anti-patterns, without checking traffic.
+- "Enable Fluid Compute" without a cold-start signal.
+- "Add caching to /api/users" when the route has cookies() and is auth-gated.
+- "Reduce the duration of `/.well-known/workflow/v1/step`" because a Workflow step is long-running. Workflow runtime endpoints are generated orchestration routes; high wall-clock duration there is expected unless a separate reliability/error signal points elsewhere.
+- "Fix `/api/chat/[id]/stream` because it has high duration" without proving the stream does avoidable pre-first-byte work, high active CPU, duplicate invocations, or movable post-response work.
+- "Save $340/mo by doing X" — invented precision.
+- Citations to URLs that don't exist or that describe Next.js features the user's version doesn't have.
+- Long lists of recs the user can't act on; every rec needs an evidence chain.
+
+## Out of scope
+
+The skill is bounded to runtime cost and performance optimization on Vercel-hosted projects. The following are explicit non-goals; if signals or scanner findings surface in these areas, route them out:
+
+- **Deployment artifact size** in isolation. Bundle size matters only when it shows up as runtime cost (cold start, FDT) or performance (LCP, INP). If the only effect is "the .next directory is large," it's not in scope.
+- **Build-time issues without runtime impact.** Slow builds, build-cache misses, monorepo build fan-out — these only enter scope when they show up as Build Minutes billing pressure (then they go through the `build-minutes-fanout` gate). A 6-minute build that completes successfully and ships a small artifact is not a target.
+- **Security advisories and credential rotation.** RCE in `next-mdx-remote`, leaked env vars, OIDC vs explicit-key auth hygiene — refer to a security skill, not this one. Exception: when a security setting is also a documented cost lever (BotID = bot traffic = edge cost), it enters via the `platform_bot_protection` gate.
+- **Commercial / billing-process trivia.** Discount sliders, seat reconciliation, contract renewal mechanics. The skill can quantify which SKU is expensive; it does not negotiate.

package/skills/craft/vercel-optimize/references/observability-plus.md

@@ -1,109 +1,109 @@
-# Observability Plus Stop-And-Ask
-
-Use this file only when `signals.observabilityPlusBlocker` is set. Do not silently continue into scanner-only mode unless the user chooses that path.
-
-## Why This Check Exists
-
-This is a data dependency, not an upgrade pitch. The skill ranks work by observed route behavior so it can separate hot, expensive paths from code that only looks suspicious. These gates need per-route metrics:
-
-| Gate                      | Required signal                                 |
-| ------------------------- | ----------------------------------------------- |
-| `slow_route`              | Function duration and invocation count by route |
-| `uncached_route`          | Cache result and request count by route         |
-| `cold_start`              | Function start type by route                    |
-| `route_errors`            | Function status by route                        |
-| `isr_overrevalidation`    | ISR reads and writes by route                   |
-| `middleware_heavy`        | Middleware invocations and duration             |
-| `cwv_poor`                | Core Web Vitals by route                        |
-| `platform_bot_protection` | Fast Data Transfer by bot category              |
-
-Scanner-only mode can still catch traffic-independent code issues, but it cannot rank the hottest routes or prove cost impact. Make that tradeoff explicit before continuing.
-
-## User Template
-
-Render this template first, then wait for the user's choice. Replace only `<detail>`. Do not add a preface; the heading is the opening line.
-
-```md
-**Per-route metrics are unavailable.**
-
-<detail>
-
-This audit needs route-level metrics to rank fixes by observed latency, cache hit rate, error rate, cold-start rate, and Incremental Static Regeneration reads and writes. Without them, I can run a scanner-only audit for traffic-independent code issues, but I cannot tell which routes matter most or prove cost impact.
-
-Docs: https://vercel.com/docs/observability/observability-plus
-
-Choose one:
-
-1. Enable Observability Plus, then re-run the metric-backed audit.
-2. Continue in scanner-only mode for a limited audit.
-```
-
-If the host supports a structured question tool, use this exact customer-facing copy. Do not rewrite it.
-
-```json
-{
-  "question": "Enable Observability Plus and re-run, or continue with a limited scanner-only audit?",
-  "header": "Observability Plus",
-  "options": [
-    {
-      "label": "Enable and re-run",
-      "description": "Use route-level metrics to rank the routes that matter most for cost and performance."
-    },
-    {
-      "label": "Run scanner-only",
-      "description": "Check traffic-independent code patterns without route ranking or proven cost impact."
-    }
-  ]
-}
-```
-
-Use the full product name in this question. Do not abbreviate product names or metrics in customer-facing blocker copy.
-
-## After The User Chooses
-
-If the user chooses **Enable and re-run**, stop after this short response:
-
-```md
-Enable Observability Plus from the Vercel dashboard's Observability tab, then tell me to rerun. I'll restart the metric-backed audit once route-level metrics are available.
-```
-
-Do not include raw team IDs, org IDs, project IDs, pricing language, dashboard screenshots, or extra persuasion. The docs link in the blocker message already covers availability and billing details.
-
-If the user chooses **Run scanner-only**, continue with the scanner-only steps below.
-
-## Blocker Copy
-
-| Blocker             | Detail                                                                                                  |
-| ------------------- | ------------------------------------------------------------------------------------------------------- |
-| `payment_required`  | `Detected: route-level metrics were recognized for this team, but these metric queries are not usable.` |
-| `no_oplus_probe`    | `Detected: this team does not expose the route-level metrics this audit needs.`                         |
-| `not_linked`        | `Detected: this app directory is not linked to a Vercel project.`                                       |
-| `forbidden`         | `Detected: the Vercel CLI is authenticated to a team that cannot read this project.`                    |
-| `project_not_found` | `Detected: the project ID is not visible to the authenticated team.`                                    |
-| `project_disabled`  | `Detected: route-level metrics are enabled for the team but disabled for this project.`                 |
-| `all_failed_other`  | `Detected: every per-route metric query failed. Error code: <code>.`                                    |
-
-For `not_linked`, do not use the Observability Plus template. Link the app directory first:
-
-```bash
-vercel link --yes --project <project-name-or-id> --cwd <app-dir>
-```
-
-Add `--team <team-id-or-slug>` when the team is known. If the user supplied both app path and project name, run the link command instead of asking them what to do.
-
-For `forbidden` and `project_not_found`, ask the user to confirm the exact Vercel project and team/personal scope before presenting the Observability Plus choice.
-
-For `project_disabled`, do not present it as a team subscription problem. Ask the user to enable Observability Plus for this project, then re-run.
-
-For `no_traffic`, do not use this template. Tell the user the project has no meaningful traffic in the 14-day window, then ask whether to run scanner-only mode now or come back after traffic accumulates.
-
-## Scanner-Only Mode
-
-If the user picks scanner-only mode:
-
-1. Re-run `node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"` if the current `signals.json` stopped at the fast blocker (`usageError=NOT_COLLECTED_OBSERVABILITY_BLOCKED` or `project=null`).
-2. Run code scanners.
-3. Launch only traffic-independent findings.
-4. Render a clear data gap: per-route metric gates were skipped because Observability Plus data was unavailable.
-
-Do not imply the scanner-only report is a complete optimization audit.
+# Observability Plus Stop-And-Ask
+
+Use this file only when `signals.observabilityPlusBlocker` is set. Do not silently continue into scanner-only mode unless the user chooses that path.
+
+## Why This Check Exists
+
+This is a data dependency, not an upgrade pitch. The skill ranks work by observed route behavior so it can separate hot, expensive paths from code that only looks suspicious. These gates need per-route metrics:
+
+| Gate                      | Required signal                                 |
+| ------------------------- | ----------------------------------------------- |
+| `slow_route`              | Function duration and invocation count by route |
+| `uncached_route`          | Cache result and request count by route         |
+| `cold_start`              | Function start type by route                    |
+| `route_errors`            | Function status by route                        |
+| `isr_overrevalidation`    | ISR reads and writes by route                   |
+| `middleware_heavy`        | Middleware invocations and duration             |
+| `cwv_poor`                | Core Web Vitals by route                        |
+| `platform_bot_protection` | Fast Data Transfer by bot category              |
+
+Scanner-only mode can still catch traffic-independent code issues, but it cannot rank the hottest routes or prove cost impact. Make that tradeoff explicit before continuing.
+
+## User Template
+
+Render this template first, then wait for the user's choice. Replace only `<detail>`. Do not add a preface; the heading is the opening line.
+
+```md
+**Per-route metrics are unavailable.**
+
+<detail>
+
+This audit needs route-level metrics to rank fixes by observed latency, cache hit rate, error rate, cold-start rate, and Incremental Static Regeneration reads and writes. Without them, I can run a scanner-only audit for traffic-independent code issues, but I cannot tell which routes matter most or prove cost impact.
+
+Docs: https://vercel.com/docs/observability/observability-plus
+
+Choose one:
+
+1. Enable Observability Plus, then re-run the metric-backed audit.
+2. Continue in scanner-only mode for a limited audit.
+```
+
+If the host supports a structured question tool, use this exact customer-facing copy. Do not rewrite it.
+
+```json
+{
+  "question": "Enable Observability Plus and re-run, or continue with a limited scanner-only audit?",
+  "header": "Observability Plus",
+  "options": [
+    {
+      "label": "Enable and re-run",
+      "description": "Use route-level metrics to rank the routes that matter most for cost and performance."
+    },
+    {
+      "label": "Run scanner-only",
+      "description": "Check traffic-independent code patterns without route ranking or proven cost impact."
+    }
+  ]
+}
+```
+
+Use the full product name in this question. Do not abbreviate product names or metrics in customer-facing blocker copy.
+
+## After The User Chooses
+
+If the user chooses **Enable and re-run**, stop after this short response:
+
+```md
+Enable Observability Plus from the Vercel dashboard's Observability tab, then tell me to rerun. I'll restart the metric-backed audit once route-level metrics are available.
+```
+
+Do not include raw team IDs, org IDs, project IDs, pricing language, dashboard screenshots, or extra persuasion. The docs link in the blocker message already covers availability and billing details.
+
+If the user chooses **Run scanner-only**, continue with the scanner-only steps below.
+
+## Blocker Copy
+
+| Blocker             | Detail                                                                                                  |
+| ------------------- | ------------------------------------------------------------------------------------------------------- |
+| `payment_required`  | `Detected: route-level metrics were recognized for this team, but these metric queries are not usable.` |
+| `no_oplus_probe`    | `Detected: this team does not expose the route-level metrics this audit needs.`                         |
+| `not_linked`        | `Detected: this app directory is not linked to a Vercel project.`                                       |
+| `forbidden`         | `Detected: the Vercel CLI is authenticated to a team that cannot read this project.`                    |
+| `project_not_found` | `Detected: the project ID is not visible to the authenticated team.`                                    |
+| `project_disabled`  | `Detected: route-level metrics are enabled for the team but disabled for this project.`                 |
+| `all_failed_other`  | `Detected: every per-route metric query failed. Error code: <code>.`                                    |
+
+For `not_linked`, do not use the Observability Plus template. Link the app directory first:
+
+```bash
+vercel link --yes --project <project-name-or-id> --cwd <app-dir>
+```
+
+Add `--team <team-id-or-slug>` when the team is known. If the user supplied both app path and project name, run the link command instead of asking them what to do.
+
+For `forbidden` and `project_not_found`, ask the user to confirm the exact Vercel project and team/personal scope before presenting the Observability Plus choice.
+
+For `project_disabled`, do not present it as a team subscription problem. Ask the user to enable Observability Plus for this project, then re-run.
+
+For `no_traffic`, do not use this template. Tell the user the project has no meaningful traffic in the 14-day window, then ask whether to run scanner-only mode now or come back after traffic accumulates.
+
+## Scanner-Only Mode
+
+If the user picks scanner-only mode:
+
+1. Re-run `node scripts/collect-signals.mjs [projectId] --continue-without-observability > "$RUN_DIR/vercel-signals.json" 2> "$RUN_DIR/collect.stderr"` if the current `signals.json` stopped at the fast blocker (`usageError=NOT_COLLECTED_OBSERVABILITY_BLOCKED` or `project=null`).
+2. Run code scanners.
+3. Launch only traffic-independent findings.
+4. Render a clear data gap: per-route metric gates were skipped because Observability Plus data was unavailable.
+
+Do not imply the scanner-only report is a complete optimization audit.

package/skills/craft/vercel-optimize/references/playbooks/README.md

@@ -1,57 +1,57 @@
-# Playbooks
-
-Application-profile-specific advice that shapes how recommendations are phrased and ordered. Playbooks never invent claims — every rec still traces to a verified candidate or finding. They tell the recommender what to emphasize when a project matches a profile.
-
-## How a playbook gets applied
-
-1. Step 1 detects the project's stack + dependencies.
-2. The recommender heuristics infer an application profile (best guess from frameworks + dep signals).
-3. The matching playbook(s) are included in the recommender's context.
-4. Recommendations are shaped: ordering tilts toward the profile's priority list; phrasing nods to profile-specific concerns.
-
-## Profile detection (best-effort heuristics)
-
-| Signals →                                                                                                                       | Profile          |
-| ------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
-| `@vercel/sandbox`, `@ai-sdk/*`, `ai`, `openai`, `@anthropic-ai/sdk` deps OR AI Gateway / Sandbox SKU active in `usage.services` | `ai-application` |
-| `stripe`, `@shopify/*`, `react-stripe-js`, "cart"/"checkout" routes                                                             | `ecommerce`      |
-| `next-auth`, `clerk`, dashboard routes, multi-tenant headers                                                                    | `saas`           |
-| Only `pages/api/**` or `app/api/**`, no UI routes                                                                               | `api-service`    |
-| Heavy MDX / markdown, mostly static routes                                                                                      | `content-site`   |
-| Lots of `/(marketing)/` route groups, A/B test deps                                                                             | `marketing`      |
-
-`ai-application` is checked first — AI-shaped customers often share routes with SaaS/ecommerce surfaces, but the billing shape (AI Gateway dominant) and remediation set (provider failover, sandbox reuse, OIDC keyless) belong to this profile.
-
-When detection is uncertain, no playbook is applied. The recommender works fine without one — the playbook is a tilt, not a requirement.
-
-## Playbook schema
-
-Each playbook is a Markdown file with a fixed shape so the recommender can parse it reliably. Required sections:
-
-```markdown
-# {Profile name}
-
-## Typical billing shape
-
-(Which dimensions dominate — e.g., "Edge Requests > Function Duration > Image Optimization")
-
-## Priority patterns
-
-(Ordered list of patterns this profile particularly benefits from)
-
-## Frequent gotchas
-
-(Anti-patterns specific to this profile)
-
-## Cross-references
-
-(Rec IDs from recommendations.md or rule names from vercel-react-best-practices)
-```
-
-## Contributing a new playbook
-
-1. Identify a clear application profile and one or two representative project profiles that exemplify it.
-2. Create `references/playbooks/<profile>.md` matching the schema.
-3. Add detection signals to the table above (the heuristics live in the recommender code; document them here).
-4. Update the playbook selection matrix in `references/scoring.md`.
-5. Run `node --test packages/vercel-optimize-tests/test/support-topics.test.mjs packages/vercel-optimize-tests/test/investigation-brief.test.mjs`. No tests directly cover playbooks (they're content), but the schema validator runs in CI.
+# Playbooks
+
+Application-profile-specific advice that shapes how recommendations are phrased and ordered. Playbooks never invent claims — every rec still traces to a verified candidate or finding. They tell the recommender what to emphasize when a project matches a profile.
+
+## How a playbook gets applied
+
+1. Step 1 detects the project's stack + dependencies.
+2. The recommender heuristics infer an application profile (best guess from frameworks + dep signals).
+3. The matching playbook(s) are included in the recommender's context.
+4. Recommendations are shaped: ordering tilts toward the profile's priority list; phrasing nods to profile-specific concerns.
+
+## Profile detection (best-effort heuristics)
+
+| Signals →                                                                                                                       | Profile          |
+| ------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| `@vercel/sandbox`, `@ai-sdk/*`, `ai`, `openai`, `@anthropic-ai/sdk` deps OR AI Gateway / Sandbox SKU active in `usage.services` | `ai-application` |
+| `stripe`, `@shopify/*`, `react-stripe-js`, "cart"/"checkout" routes                                                             | `ecommerce`      |
+| `next-auth`, `clerk`, dashboard routes, multi-tenant headers                                                                    | `saas`           |
+| Only `pages/api/**` or `app/api/**`, no UI routes                                                                               | `api-service`    |
+| Heavy MDX / markdown, mostly static routes                                                                                      | `content-site`   |
+| Lots of `/(marketing)/` route groups, A/B test deps                                                                             | `marketing`      |
+
+`ai-application` is checked first — AI-shaped customers often share routes with SaaS/ecommerce surfaces, but the billing shape (AI Gateway dominant) and remediation set (provider failover, sandbox reuse, OIDC keyless) belong to this profile.
+
+When detection is uncertain, no playbook is applied. The recommender works fine without one — the playbook is a tilt, not a requirement.
+
+## Playbook schema
+
+Each playbook is a Markdown file with a fixed shape so the recommender can parse it reliably. Required sections:
+
+```markdown
+# {Profile name}
+
+## Typical billing shape
+
+(Which dimensions dominate — e.g., "Edge Requests > Function Duration > Image Optimization")
+
+## Priority patterns
+
+(Ordered list of patterns this profile particularly benefits from)
+
+## Frequent gotchas
+
+(Anti-patterns specific to this profile)
+
+## Cross-references
+
+(Rec IDs from recommendations.md or rule names from vercel-react-best-practices)
+```
+
+## Contributing a new playbook
+
+1. Identify a clear application profile and one or two representative project profiles that exemplify it.
+2. Create `references/playbooks/<profile>.md` matching the schema.
+3. Add detection signals to the table above (the heuristics live in the recommender code; document them here).
+4. Update the playbook selection matrix in `references/scoring.md`.
+5. Run `node --test packages/vercel-optimize-tests/test/support-topics.test.mjs packages/vercel-optimize-tests/test/investigation-brief.test.mjs`. No tests directly cover playbooks (they're content), but the schema validator runs in CI.