natureco-cli 5.18.3 → 5.20.0

package/skills/vercel-cli-with-tokens/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: vercel-cli-with-tokens
+description: Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. "deploy to vercel", "set up vercel", "add environment variables to vercel".
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel CLI with Tokens
+
+Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on `vercel login`.
+
+## Step 1: Locate the Vercel Token
+
+Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
+
+### A) `VERCEL_TOKEN` is already set in the environment
+
+```bash
+printenv VERCEL_TOKEN
+```
+
+If this returns a value, you're ready. Skip to Step 2.
+
+### B) Token is in a `.env` file under `VERCEL_TOKEN`
+
+```bash
+grep '^VERCEL_TOKEN=' .env 2>/dev/null
+```
+
+If found, export it:
+
+```bash
+export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
+```
+
+### C) Token is in a `.env` file under a different name
+
+Look for any variable that looks like a Vercel token (Vercel tokens typically start with `vca_`):
+
+```bash
+grep -i 'vercel' .env 2>/dev/null
+```
+
+Inspect the output to identify which variable holds the token, then export it as `VERCEL_TOKEN`:
+
+```bash
+export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
+```
+
+### D) No token found — ask the user
+
+If none of the above yield a token, ask the user to provide one. They can create a Vercel access token at vercel.com/account/tokens.
+
+---
+
+**Important:** Once `VERCEL_TOKEN` is exported as an environment variable, the Vercel CLI reads it natively — **do not pass it as a `--token` flag**. Putting secrets in command-line arguments exposes them in shell history and process listings.
+
+```bash
+# Bad — token visible in shell history and process listings
+vercel deploy --token "vca_abc123"
+
+# Good — CLI reads VERCEL_TOKEN from the environment
+export VERCEL_TOKEN="vca_abc123"
+vercel deploy
+```
+
+## Step 2: Locate the Project and Team
+
+Similarly, check for the project ID and team scope. These let the CLI target the right project without needing `vercel link`.
+
+```bash
+# Check environment
+printenv VERCEL_PROJECT_ID
+printenv VERCEL_ORG_ID
+
+# Or check .env
+grep -i 'vercel' .env 2>/dev/null
+```
+
+**If you have a project URL** (e.g. `https://vercel.com/my-team/my-project`), extract the team slug:
+
+```bash
+# e.g. "my-team" from "https://vercel.com/my-team/my-project"
+echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1
+```
+
+**If you have both `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` in your environment**, export them — the CLI will use these automatically and skip any `.vercel/` directory:
+
+```bash
+export VERCEL_ORG_ID="<org-id>"
+export VERCEL_PROJECT_ID="<project-id>"
+```
+
+Note: `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` must be set together — setting only one causes an error.
+
+## CLI Setup
+
+Ensure the Vercel CLI is installed and up to date:
+
+```bash
+npm install -g vercel
+vercel --version
+```
+
+## Deploying a Project
+
+Always deploy as **preview** unless the user explicitly requests production. Choose a method based on what you have available.
+
+### Quick Deploy (have project ID — no linking needed)
+
+When `VERCEL_TOKEN` and `VERCEL_PROJECT_ID` are set in the environment, deploy directly:
+
+```bash
+vercel deploy -y --no-wait
+```
+
+With a team scope (either via `VERCEL_ORG_ID` or `--scope`):
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Production (only when explicitly requested):
+
+```bash
+vercel deploy --prod --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Full Deploy Flow (no project ID — need to link)
+
+Use this when you have a token and team but no pre-existing project ID.
+
+#### Check project state first
+
+```bash
+# Does the project have a git remote?
+git remote get-url origin 2>/dev/null
+
+# Is it already linked to a Vercel project?
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+```
+
+#### Link the project
+
+**With git remote (preferred):**
+
+```bash
+vercel link --repo --scope <team-slug> -y
+```
+
+Reads the git remote and connects to the matching Vercel project. Creates `.vercel/repo.json`. More reliable than plain `vercel link`, which matches by directory name.
+
+**Without git remote:**
+
+```bash
+vercel link --scope <team-slug> -y
+```
+
+Creates `.vercel/project.json`.
+
+**Link to a specific project by name:**
+
+```bash
+vercel link --project <project-name> --scope <team-slug> -y
+```
+
+If the project is already linked, check `orgId` in `.vercel/project.json` or `.vercel/repo.json` to verify it matches the intended team.
+
+#### Deploy after linking
+
+**A) Git Push Deploy — has git remote (preferred)**
+
+Git pushes trigger automatic Vercel deployments.
+
+1. **Ask the user before pushing.** Never push without explicit approval.
+2. Commit and push:
+   ```bash
+   git add .
+   git commit -m "deploy: <description of changes>"
+   git push
+   ```
+3. Vercel builds automatically. Non-production branches get preview deployments.
+4. Retrieve the deployment URL:
+   ```bash
+   sleep 5
+   vercel ls --format json --scope <team-slug>
+   ```
+   Find the latest entry in the `deployments` array.
+
+**B) CLI Deploy — no git remote**
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Deploying from a Remote Repository (code not cloned locally)
+
+1. Clone the repository:
+   ```bash
+   git clone <repo-url>
+   cd <repo-name>
+   ```
+2. Link to Vercel:
+   ```bash
+   vercel link --repo --scope <team-slug> -y
+   ```
+3. Deploy via git push (if you have push access) or CLI deploy.
+
+### About `.vercel/` Directory
+
+A linked project has either:
+- `.vercel/project.json` — from `vercel link`. Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — from `vercel link --repo`. Contains `orgId`, `remoteName`, and a `projects` map.
+
+Not needed when `VERCEL_ORG_ID` + `VERCEL_PROJECT_ID` are both set in the environment.
+
+**Do NOT** run `vercel project inspect` or `vercel link` in an unlinked directory to detect state — they will interactively prompt or silently link as a side-effect. `vercel ls` is safe (in an unlinked directory it defaults to showing all deployments for the scope). `vercel whoami` is safe anywhere.
+
+## Managing Environment Variables
+
+```bash
+# Set for all environments
+echo "value" | vercel env add VAR_NAME --scope <team-slug>
+
+# Set for a specific environment (production, preview, development)
+echo "value" | vercel env add VAR_NAME production --scope <team-slug>
+
+# List environment variables
+vercel env ls --scope <team-slug>
+
+# Pull env vars to local .env.local file
+vercel env pull --scope <team-slug>
+
+# Remove a variable
+vercel env rm VAR_NAME --scope <team-slug> -y
+```
+
+## Inspecting Deployments
+
+```bash
+# List recent deployments
+vercel ls --format json --scope <team-slug>
+
+# Inspect a specific deployment
+vercel inspect <deployment-url>
+
+# View build logs (requires Vercel CLI v35+)
+vercel inspect <deployment-url> --logs
+
+# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)
+vercel logs <deployment-url>
+```
+
+## Managing Domains
+
+```bash
+# List domains
+vercel domains ls --scope <team-slug>
+
+# Add a domain to the project — linked or env-linked directory (1 arg)
+vercel domains add <domain> --scope <team-slug>
+
+# Add a domain — unlinked directory (requires <project> positional)
+vercel domains add <domain> <project> --scope <team-slug>
+```
+
+## Stripe Projects Plan Changes
+
+If this project is managed by Stripe Projects. **Ask the user before running any paid or destructive plan change** — upgrades bill a real card, downgrades remove seats.
+
+First run `stripe projects status --json` to confirm the Vercel resource's local name. The examples below assume the default (`vercel-plan`); substitute the actual name if it was renamed at `stripe projects add` time.
+
+- **Upgrade to Pro:** `stripe projects add vercel/pro` (or `stripe projects upgrade vercel-plan pro`)
+- **Downgrade to Hobby:** `stripe projects downgrade vercel-plan hobby`
+
+### What Pro gives you
+
+- $20/month platform fee, includes $20/month of usage credit.
+- Turbo build machines (30 vCPUs, 60 GB memory) by default for new projects — significantly faster builds than Hobby.
+- 1 deploying seat + unlimited free Viewer seats (read-only collaborators, preview comments).
+- Higher included allocations (1 TB Fast Data Transfer, 10M Edge Requests per month).
+- Paid add-ons available: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.
+
+Full details: https://vercel.com/docs/plans/pro-plan
+
+## Working Agreement
+
+- **Never pass `VERCEL_TOKEN` as a `--token` flag.** Export it as an environment variable and let the CLI read it natively.
+- **Check the environment for tokens before asking the user.** Look in the current env and `.env` files first.
+- **Default to preview deployments.** Only deploy to production when explicitly asked.
+- **Ask before pushing to git.** Never push commits without the user's approval.
+- **Do not modify `.vercel/` files directly.** The CLI manages this directory. Reading them (e.g. to verify `orgId`) is fine.
+- **Do not curl/fetch deployed URLs to verify.** Just return the link to the user.
+- **Use `--format json`** when structured output will help with follow-up steps.
+- **Use `-y`** on commands that prompt for confirmation to avoid interactive blocking.
+
+## Troubleshooting
+
+### Token not found
+
+Check the environment and any `.env` files present:
+
+```bash
+printenv | grep -i vercel
+grep -i vercel .env 2>/dev/null
+```
+
+### Authentication error
+
+If the CLI fails with `Authentication required`:
+- The token may be expired or invalid.
+- Verify: `vercel whoami` (uses `VERCEL_TOKEN` from environment).
+- Ask the user for a fresh token.
+
+### Wrong team
+
+Verify the scope is correct:
+
+```bash
+vercel whoami --scope <team-slug>
+```
+
+### Build failure
+
+Check the build logs:
+
+```bash
+vercel inspect <deployment-url> --logs
+```
+
+Common causes:
+- Missing dependencies — ensure `package.json` is complete and committed.
+- Missing environment variables — add with `vercel env add`.
+- Framework misconfiguration — check `vercel.json`. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from `package.json`; override with `vercel.json` if detection is wrong.
+
+### CLI not installed
+
+```bash
+npm install -g vercel
+```

package/skills/vercel-optimize/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: vercel-optimize
+description: "Use for Vercel cost and performance optimization on deployed projects, especially Next.js, SvelteKit, Nuxt, and limited Astro apps. Collect Vercel metrics, usage, project config, and code scan results first; investigate only metric-backed candidates; produce ranked recommendations grounded in verified files and version-aware Vercel/framework docs. Trigger for Vercel bill reduction, slow or expensive routes, caching opportunities, Function Invocations, Build Minutes, Fast Data Transfer, Core Web Vitals, Bot Management, Fluid compute, or cost breakdown requests."
+metadata:
+  version: "1.2.0"
+---
+
+# 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.
+
+## 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.