@nuxtseo/cli 0.2.1 → 0.4.0

package/dist/update-check.js

@@ -1,4 +1,5 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { checkSkillVersion, skillNoticeLine } from './skill.js';
 import { VERSION } from './version.js';
 /** How long a registry answer stays authoritative, matching npm's update cache. */
 export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -85,13 +86,28 @@ export async function fetchRegistryLatest(url, signal) {
     const version = body.version;
     return typeof version === 'string' && version ? version : null;
 }
+async function emitSkillNotice(check, onDiagnostic) {
+    const notice = await check.catch(() => {
+        // A local read failure must never break a command. The run continues silently.
+        return null;
+    });
+    if (notice && onDiagnostic)
+        onDiagnostic(skillNoticeLine(notice));
+}
 export async function checkForUpdate(options) {
     if (updateCheckDisabled(options.env))
         return null;
+    // The installed agent skill is the other half of "is this install current".
+    // It runs beside the registry fetch so neither waits for the other.
+    const skillCheck = options.onDiagnostic
+        ? checkSkillVersion({ paths: options.paths, env: options.env, now: options.now })
+        : Promise.resolve(null);
     const now = options.now?.() ?? new Date();
     const cache = await readUpdateCheckCache(options.paths);
-    if (!updateCheckDue(cache, now))
+    if (!updateCheckDue(cache, now)) {
+        await emitSkillNotice(skillCheck, options.onDiagnostic);
         return updateNoticeFor(cache.latest, VERSION);
+    }
     const fetchLatest = options.fetch ?? fetchRegistryLatest;
     const latest = await fetchLatest(REGISTRY_LATEST_URL, AbortSignal.timeout(FETCH_TIMEOUT_MS)).catch(() => {
         // Registry reachability is best effort. The run continues without a hint.
@@ -99,6 +115,7 @@ export async function checkForUpdate(options) {
     });
     if (latest !== null)
         await writeUpdateCheckCache(options.paths, { lastCheckedAt: now.toISOString(), latest });
+    await emitSkillNotice(skillCheck, options.onDiagnostic);
     // A stale cached answer still beats no answer while the registry is unreachable.
     return updateNoticeFor(latest ?? cache?.latest ?? null, VERSION);
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.2.1",
-  "description": "Command line interface for the NuxtSEO public API.",
+  "version": "0.4.0",
+  "description": "Command line interface for the Nuxt SEO public API.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com/pro",
   "repository": {
@@ -33,8 +33,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.0",
-    "@nuxtseo/protocol": "^0.2.1",
-    "@nuxtseo/sdk": "^0.2.1",
+    "@nuxtseo/protocol": "^0.4.0",
+    "@nuxtseo/sdk": "^0.4.0",
     "citty": "^0.2.2",
     "pathe": "^2.0.3"
   },

package/skills/nuxtseo-cli/SKILL.md

@@ -1,110 +1,98 @@
 ---
 name: nuxtseo-cli
-description: Drives the `nuxtseo` CLI to triage a Site through the NuxtSEO public API: Site status and ranked issues, Search Console rows, route-family indexing, field and lab Core Web Vitals, Lighthouse Scans, Page Issues, keyword competitor and domain research, backlinks, SERP analysis, rankings, link opportunities, Content Briefs, content decay, duplicate clusters, chart annotations, and issue resolution. Use whenever the user mentions NuxtSEO, the `nuxtseo` command, Site SEO work, or NuxtSEO automation.
+description: Drives the `nuxtseo` CLI to triage a Site through the Nuxt SEO public API: Site status and ranked issues, Search Console rows, route-family indexing, field and lab Core Web Vitals, Lighthouse Scans, Page Issues, keyword competitor and domain research, backlinks, SERP analysis, rankings, link opportunities, content decay, duplicate clusters, chart annotations, and issue resolution. Use whenever the user mentions NuxtSEO, the `nuxtseo` command, Site SEO work, or Nuxt SEO automation.
 ---
 
-# NuxtSEO CLI
+# `nuxtseo` CLI
 
-`nuxtseo` reads a Site through the NuxtSEO public API. Every command goes
-through `@nuxtseo/sdk`. The CLI never calls MCP or private routes. Live
-research reaches a provider only through a declared public API operation.
-
-Use it to answer "what is wrong with this site, and what did I break". Then fix
-the code in the repository you are working in.
+`nuxtseo` reads a Site through the Nuxt SEO public API. Use it to answer "what
+is wrong with this site, and what did I break", then fix the cause in the
+repository you are working in. There is no MCP or private-route fallback.
 
 ## Reference files
 
-Read each one before you act on its subject:
-
-- [references/commands.md](references/commands.md): every command, with its
-  flags, ranges, and defaults. Read it instead of guessing a flag.
-- [references/protocol.md](references/protocol.md): response envelopes, paging,
-  and exit codes. Read it before you parse output or handle a failure.
-- [references/indexing.md](references/indexing.md): how to answer "is this
-  indexed". Read it before you report an indexed count, or name the URLs
-  Google indexed.
-
-## Get the binary
-
-```sh
-pnpm dlx @nuxtseo/cli@latest --version  # no install
-pnpm add -g @nuxtseo/cli                # or npm install --global
-```
-
-Node 22 or newer is required.
-
-Inside the NuxtSEO monorepo the package is not published. Run the built entry
-directly:
+Read the matching file before you act on its subject:
 
-```sh
-node packages/cli/dist/cli-entry.js --version
-```
+| File | Read it before you |
+| --- | --- |
+| [references/commands.md](references/commands.md) | use a flag, range, or default. Never guess a flag |
+| [references/protocol.md](references/protocol.md) | parse output, page through a list, or handle an exit code |
+| [references/indexing.md](references/indexing.md) | report an indexed count or name indexed URLs |
+
+## Setup
+
+1. **Binary.** Exit `127` means the CLI is absent. Install it, then continue:
+
+   ```sh
+   pnpm dlx @nuxtseo/cli@latest --version   # no install
+   pnpm add -g @nuxtseo/cli                 # global install, Node 22+
+   ```
+
+   Inside the Nuxt SEO monorepo, run `node packages/cli/dist/cli-entry.js`
+   instead.
+
+2. **Skill version.** Run `nuxtseo --version --json`. If stderr carries a line
+   like `skill 0.3.0 installed, CLI 0.4.0. Refresh with: nuxtseo skill install
+   --agent claude`, run that command and re-read this file. A stale skill hides
+   commands, so a missing command reads as a missing feature. If
+   `NUXTSEO_NO_UPDATE_CHECK` is set, the line never appears; compare this
+   file's frontmatter `version` with the binary instead.
+
+3. **Token.** Run `nuxtseo whoami --json`. It returns the Team, role, scopes,
+   and token expiry. Exit `3` means no working token. Ask the user to run
+   `nuxtseo login` themselves, because a person must approve it in a browser.
+   The other route is a token from
+   <https://nuxtseo.com/pro/dashboard/settings/api-tokens>, exported as
+   `NUXTSEO_TOKEN`. Never put a token in an argument, a file, or a commit.
+
+4. **Scopes.** Read `data.scopes` now, not when a step fails. A `viewer` token
+   carries every `*:read` scope plus `feedback:write`. It can run every read,
+   including live research, and no write:
+
+   | Write | Scope |
+   | --- | --- |
+   | `page scan` | `page:write` |
+   | `actions resolve`, `actions dismiss` | `actions:write` |
+   | `annotations` writes | `timeline:write` |
+   | `sitemaps submit`, `sitemaps delete` | `sites:write` |
+
+   If a write scope is missing, do the reads, then hand the user the exact
+   write commands. Do not discover the block one exit `4` at a time.
+
+5. **Site.** Run `nuxtseo sites list --json` once and reuse the ID. If more
+   than one Site is accessible and `--site` is absent, the CLI exits `5`
+   rather than guess.
+
+## Calling convention
+
+- Always pass `--json` and `--site <site-id>`. `feedback submit` needs no Site.
+- `--json` writes one envelope to stdout. Diagnostics go to stderr. Parse the
+  JSON; never scrape human output.
+- A mutation needs `--yes`. Without it, a non-interactive run exits `2`.
+- `--timeout-ms` raises the 30000 ms deadline, up to 300000.
+- An unknown option exits `2` before any network work.
+- Branch on the exit code, never on message text. The table is in
+  [references/protocol.md](references/protocol.md).
 
-Exit `127` or `command not found` means the CLI is absent. That is not exit
-`3`; no token has been checked yet. Install it, then continue.
+## The triage loop
 
-## Before the first command
+Copy this checklist and track your progress:
 
-```sh
-nuxtseo whoami --json          # validates the token and reports its scopes
 ```
-
-`whoami` returns the Team, the role, the granted scopes, and the token expiry.
-Read `data.scopes` before a write command. A missing scope is exit `4`, and the
-scope list tells you that before you spend the request.
-
-Exit `3` means there is no working token. Ask the user to run `nuxtseo login`
-themselves. It opens a browser, they approve the pairing, and the CLI stores
-the token. Do not run `login` for them. It needs a person at the browser, and
-in a non-interactive shell it falls back to reading a token from stdin.
-
-The alternative is a token created at
-<https://nuxtseo.com/pro/dashboard/settings/api-tokens> and exported as
-`NUXTSEO_TOKEN`. Either way the token is bound to a Team role, and that role
-gates what it can do.
-
-Never put a token in a command argument, a file you write, or a commit.
-`login` reads a token from a hidden prompt or stdin only.
-
-Resolve the Site once and reuse it. `nuxtseo sites list --json` prints every
-accessible Site with its ID.
-
-## How to call it as an agent
-
-Always pass `--json`. Pass `--site <site-id>` for Site commands.
-`feedback submit` needs no Site.
-
-```sh
-nuxtseo actions list --site site_123 --json
+Triage progress:
+- [ ] 1. status: read the verdict and the Next Action
+- [ ] 2. actions list: pick a ranked action, check its freshness
+- [ ] 3. actions show: read the evidence behind it
+- [ ] 4. Fix the cause in the repository
+- [ ] 5. page scan: re-scan a page you changed
+- [ ] 6. actions resolve: claim the action
+- [ ] 7. annotations create: mark the day the fix shipped
 ```
 
-`--json` writes the complete protocol envelope to stdout and one newline. It
-also disables prompts. Diagnostics, warnings, spinners, and failure messages go
-to stderr, so stdout stays parseable.
-
-`--site` matters for a second reason. An explicit Site ID goes straight to the
-operation and skips the Sites read. A token whose role cannot list Sites still
-works. If more than one Site is accessible and `--site` is absent, the CLI
-exits `5` rather than guessing.
-
-Other flags worth knowing:
-
-| Flag | Use it when |
-| --- | --- |
-| `--yes`, `-y` | The command mutates. Without it, a non-interactive run exits `2` |
-| `--timeout-ms <ms>` | The default 30000 ms deadline is too short. Maximum is 300000 |
-| `--api-url <url>` | Testing against a non-production host |
-| `--no-input` | Running in a TTY but no prompt is wanted. `--json` already implies this |
-
-Unknown options exit `2` before any network work, so a typo costs nothing.
-
-Parse JSON. Never scrape human output.
-
-Every `--json` run prints one envelope. For example, `status` returns this,
-abridged:
+**1. Read the verdict.**
 
 ```sh
-nuxtseo status --site site_01JXYZ --json
+nuxtseo status --site <site-id> --json
 ```
 
 ```json
@@ -118,104 +106,73 @@ nuxtseo status --site site_01JXYZ --json
 }
 ```
 
-Read `data.available` first; `false` means the first assessment has not run.
-Read `data.dataQuality.status` before you quote the verdict. Pass
-`data.nextAction.actionId` into `actions show`.
-
-## The triage loop
-
-This sequence turns CLI output into a code change. Copy the checklist and track
-your progress:
-
-```
-Triage progress:
-- [ ] 1. status: read the verdict and the Next Action
-- [ ] 2. actions list: pick a ranked action, check its freshness
-- [ ] 3. actions show: read the evidence behind it
-- [ ] 4. Fix the cause in the repository
-- [ ] 5. page scan: re-scan a page you changed
-- [ ] 6. actions resolve: claim the action
-- [ ] 7. annotations create: mark the day the fix shipped
-```
+- `available: false` means the first assessment has not run.
+- Read `dataQuality.status` before you quote the verdict. `degraded` means
+  proofs were missing, so the verdict is Provisional. `unavailable` means it
+  has not run.
+- If `nextAction.kind` is `action`, pass its `actionId` to step 3.
 
-**Step 1. Read the Site verdict.**
+For the whole Site instead of the next action, run one `pull`. It performs
+every spend-free Site read and writes one envelope per line:
 
 ```sh
-nuxtseo status --site <site-id> --json
+nuxtseo pull --site <site-id> --json > site.ndjson
 ```
 
-This is the cheapest orientation: the verdict, the single ranked Next Action,
-and what changed recently. Read `dataQuality.status` before quoting it.
-`degraded` means the assessment ran with proofs missing, so the verdict is real
-but Provisional. `unavailable` means it has not run. If `nextAction.kind` is
-`action`, its `actionId` goes straight into step 3.
-
-**Step 2. Pick a ranked action.**
+**2. Pick a ranked action.**
 
 ```sh
 nuxtseo actions list --site <site-id> --json
 ```
 
-Each row carries an ID, a diagnosis, an effort, and an affected page count.
-Check `evidence.freshness` per row. If `verdict` is `aged` with a large
-`ageHours`, live-check a cheap sample before fixing. The site may have moved on
-since the observation.
+Keep server order. Check `evidence.freshness` on each row. If `verdict` is
+`aged` with a large `ageHours`, live-check a cheap sample before you fix. The
+Site may have changed since the observation.
 
-**Step 3. Read the evidence.**
+**3. Read the evidence.**
 
 ```sh
 nuxtseo actions show <action-id> --site <site-id> --json
 ```
 
-This returns which pages, which finding type, and when it was observed.
-
-Two reads deepen this step when the action's own evidence is not enough:
+It names the pages, the finding type, and when it was observed. Two reads go
+deeper:
 
-- `nuxtseo page issues --action-id <action-id> --site <site-id> --json` returns
-  the raw observations behind that action: the exact URLs, status codes,
-  redirect targets, and for a Lighthouse row the failing selectors and DOM
-  snippets. These are the mutable observation store, never canonical action
-  membership.
-- `nuxtseo scans show <scan-id> --site <site-id> --json` returns the failing
-  checks behind a Lighthouse score, so you can locate the cause without
-  re-scanning.
+- `page issues --action-id <action-id>`: the raw observations, with URLs,
+  status codes, redirect targets, and Lighthouse selectors. This is the
+  mutable observation store, never canonical action membership.
+- `scans show <scan-id>`: the failing checks behind a Lighthouse score.
 
-**Step 4. Fix the cause in the repository.**
+**4. Fix the cause.** Map the URLs in the evidence to routes, components, or
+config.
 
-The evidence names URLs. Map them back to routes, components, or config.
-
-**Step 5. Re-scan a page you changed.**
-
-Deploy or preview the fix first. Then ask for fresh Scans:
+**5. Re-scan.** Deploy or preview the fix first:
 
 ```sh
 nuxtseo page scan <url> --site <site-id> --yes --json
 ```
 
-**Step 6. Claim the action.**
+**6. Claim the action.**
 
 ```sh
 nuxtseo actions resolve <action-id> --site <site-id> --yes --json
 ```
 
-The server verifies it. The CLI never marks anything fixed by itself. Resolve
-reads the action first and sends the current `artifactVersion` for you. Do not
-construct that field by hand. If the evidence moved under you, the command
-exits `5` with `stale_evidence`. Re-run step 3 and decide again.
+The server verifies the claim; the CLI never marks anything fixed. Resolve
+sends the current `artifactVersion` for you. If the evidence moved, it exits
+`5` with `stale_evidence`: re-run step 3 and decide again.
 
-When the fix is a deliberate removal rather than a repair, dismiss instead of
-resolving:
+If the fix is a deliberate removal, dismiss instead. Read `artifactVersion`
+from `actions show`, then:
 
 ```sh
-nuxtseo actions show <action-id> --site <site-id> --json    # read artifactVersion
 nuxtseo actions dismiss <action-id> --site <site-id> --artifact-version <v> --yes --json
 ```
 
-Dismiss is admitted only for a broken-page action with complete 404 or 410
-evidence and no internal referrers. Anything else is rejected, so it cannot be
-used to hide work.
+The server admits a dismiss only for a broken-page action with complete 404 or
+410 evidence and no internal referrers.
 
-**Step 7. Mark the day the fix shipped.**
+**7. Mark the day.**
 
 ```sh
 nuxtseo annotations create --site <site-id> --date "$(date -u +%F)" --title "Fixed canonicals on /docs" --yes --json
@@ -223,117 +180,93 @@ nuxtseo annotations create --site <site-id> --date "$(date -u +%F)" --title "Fix
 
 The next traffic move then has a cause beside it.
 
-## Datasets that must not be conflated
-
-Two datasets share the word "vitals":
-
-- `performance` and `scans *` read Lighthouse **lab** Scans.
-- `vitals summary`, `vitals trend`, and `vitals findings` read **field**
-  (real-user) data. `vitals` reads CrUX. `vitals findings` reads the Site's own
-  Web Analytics provider.
-
-A lab score and a field p75 disagreeing is normal, not a fault.
-
-Two commands inspect the same URL and answer different questions. `page inspect`
-reads the NuxtSEO observation store. `search inspect` reads Google's index
-verdict.
-
-`status`, `performance`, and `vitals` answer different questions. `status` is
-the verdict. `performance` is the lab score. `vitals` is what real users
-measured. Never substitute one for another.
-
-The Search Console reads also split:
-
-- `search status` reads stored connection state. It never waits for Google.
-- `search analytics`, `search indexing`, `search index-history`, and
-  `search inspect` read retained Search Console evidence through the public API.
-- `sitemaps submit` and `sitemaps delete` reach Google through the Site's
-  stored Search Console credential. Both are mutations.
+## Reading results correctly
 
-## Route-family indexing: two lists, one claim
+**Empty is not clean.** Each read names its own kind of empty. Say which one
+you got:
 
-`search cohorts` answers "which template is Google declining" in one read,
-instead of N page-level findings. Read it before you list individual
-not-indexed URLs. Its output holds two lists that mean different things. Never
-merge them.
+| Command | Empty signal |
+| --- | --- |
+| `page inspect` | `observations.coverage` |
+| `page issues` | `availableKeys` |
+| `search cohorts` | `analysed: false`: no completed crawl, or no Google index state |
+| `vitals summary` | `available: false` |
+| `research keywords`, `research rankings`, `research domain-*`, `page issues`, `search cohorts`, `vitals findings` | `data.message`, and `data.tip` for the repair |
+
+Read `data.message` before the list. For example, `research keywords` refuses
+a seed over three words, still exits `0`, and returns `keywords: []` with
+`evidence._tag: "no-provider"`. That is a refused argument, not zero demand.
+
+**A refusal is not an empty Site.** Exit `4` is a plan, scope, or entitlement
+blocker, for example `entitlement_required`. Exit `5` on `status`, `page
+issues`, or `search cohorts` can mean an archived or paused Site. Report the
+blocker and stop. Do not read it as "no data" or "nothing wrong", and do not
+retry unchanged.
+
+**Quote the count the result ships.** Never quote the length of a list. Use
+`data.total` from `page issues`, and `coverage.accessibilityChecksTotal` and
+`coverage.bestPracticesChecksTotal` from `scans show`. `possiblyTruncated:
+true` marks the list as a floor.
+
+**Keep these datasets apart:**
+
+- `performance` and `scans *` read Lighthouse **lab** Scans. `vitals summary`
+  and `vitals trend` read CrUX **field** data. `vitals findings` reads the
+  Site's own Web Analytics provider. A lab score and a field p75 that disagree
+  is normal.
+- `status` is the verdict, `performance` the lab score, `vitals` what real
+  users measured. Never substitute one for another.
+- `page inspect` reads the Nuxt SEO observation store. `search inspect` reads
+  Google's index verdict for the same URL.
+- `search status` reads the stored connection and never waits for Google.
+  `search analytics`, `search indexing`, `search index-history`, and
+  `search inspect` read retained Search Console evidence.
+- An indexed count comes from `search indexing`, never from analytics rows.
+  See [references/indexing.md](references/indexing.md).
+
+**Route families: `established` versus `ranked`.** Read `search cohorts`
+before you list single not-indexed URLs. Never merge its two lists:
+
+- `established` holds only families whose not-indexed rate is significant
+  against the rest of the Site, after a Bonferroni correction. Only these rows
+  are a finding or a cause.
+- `ranked` orders every family by raw rate, with no significance test. A row
+  with `statisticallyEstablished: false` is a lead to verify, for example by
+  inspecting its URLs. Presenting it as a cause is a hard failure.
 
-- `established` holds only families whose Wilson score interval clears the
-  not-indexed rate of their **own complement** after a Bonferroni correction.
-  These are the only rows you may report as a finding or a cause.
-- `ranked` orders every family by raw rate, with **no significance test**. It
-  always answers "where is indexing worst", even when nothing is provable. A
-  row with `statisticallyEstablished: false` is a lead to verify, never a
-  conclusion. Presenting one as established is a hard failure.
+## Guardrails
 
-`analysed: false` means there is no completed crawl, or no Google index state
-to join against. That is a coverage gap, not healthy indexing. Say which.
+- **Get consent before a mutation.** `page scan`, `actions resolve`, `actions
+  dismiss`, `sitemaps submit`, `sitemaps delete`, and the `annotations` writes
+  change server state. `sitemaps` writes also reach Google. `--yes` is consent
+  you borrow from the user, so ask first unless they asked for that exact
+  action.
+- **Spend limits.** `page scan` spends Lighthouse limit. `research *` and the
+  `backlinks` reads spend the Team research limit, except `backlinks
+  recoverable` and `mentions list`, which read retained rows. A `cache` or
+  `no-provider` evidence tag, or `cached: true`, means nothing was spent.
+  Check `usage` before any run over many Pages, keywords, or domains.
+- **No shell loops.** Use `pull` for Site reads and `--all` for paging. `--all`
+  stops at 50 requests with exit `9`; treat that as a stop and resume with the
+  argument stderr names.
 
 ## Report CLI feedback
 
-If CLI behavior blocks or slows your work, submit feedback once per distinct problem during the task.
-Report confusing output, missing context, incorrect help, unexpected failures, and useful workarounds.
-Continue the user's task after reporting.
+If the CLI blocks or slows your work, report it once per distinct problem, then
+continue the task. This skill authorizes that; no confirmation is needed unless
+the user forbids reporting.
 
 ```sh
-nuxtseo feedback submit --command "search cohorts" --agent "Codex" \
-  --comment "Agent report by Codex. Expected a reason for missing data. Received an empty list. Used search status instead." \
+nuxtseo feedback submit --command "search cohorts" --agent "<your agent name>" \
+  --comment "Agent report by <your agent name>. Expected a reason for missing data. Received an empty list. Used search status instead." \
   --yes --json
 ```
 
-Use your actual agent name. Start the comment with an agent disclosure.
-Include reproduction steps, expected behavior, actual behavior, and any workaround.
-Use `--intent improvement` for suggestions. The default is `bug`.
-If the affected response has a request ID, pass it with `--request-id`.
-The CLI adds its version automatically.
-
-Send sanitized details only. Remove tokens, cookies, personal data, private URLs, and customer content.
-Use command names and placeholder arguments. Never paste raw logs or full response bodies.
-
-Self-reporting sanitized CLI feedback is authorized by this skill. No separate confirmation is needed.
-This permission covers feedback only. Respect any user instruction that forbids reporting.
-The endpoint requires a working credential with `feedback:write`, available to every Team role.
-It uses no paid limit and allows ten reports per credential each hour.
-
-Success returns `data.id` and `data.status: "new"`. Keep the ID with your task notes.
-If reporting fails, mention the failure and continue. Never retry uncertain submissions or report failures recursively.
-If authentication is broken, describe the feedback to the user. Do not invent another endpoint.
-
-Reports use the existing feedback queue through `POST /api/v1/account/feedback`.
-Health checks show unresolved reports across all dates.
-Operators use **Pro feedback** in admin to record a fix reference and set `fixed` after verification.
-Fixed, replied, closed, and ignored reports leave the health check list. Reopening restores them.
-
-## Guardrails
-
-- **Get consent before a mutation.** `actions resolve`, `actions dismiss`,
-  `page scan`, `sitemaps submit`, `sitemaps delete`, `content briefs create`,
-  and the `annotations` writes all change server state. `page scan` also spends
-  against the Lighthouse limit. `--yes` is consent you borrow from the user, so
-  ask first, unless the user already asked for that exact action. `actions
-  dismiss` says the page stays removed, so use it only when that is the
-  decision.
-- **Live research spends against the Team research limit.** `research
-  keywords`, `research serp`, `research rankings`, `research domain-traffic`,
-  `research domain-availability`, and the `backlinks` reads other than
-  `backlinks recoverable` can all start it. Each one reports what it did.
-  Keyword, domain, and backlink JSON report cache use in `evidence`; a `cache`
-  or `no-provider` tag means nothing was spent. SERP and ranking JSON report
-  `cached`. `backlinks recoverable` and `mentions list` read retained rows and
-  spend nothing.
-- **Never loop unattended.** Check `usage` before any run over Pages, keywords,
-  or domains. Use `--all` rather than your own offset loop. It writes one
-  envelope per line and stops at 50 requests with exit `9`. Treat exit `9` as a
-  stop, then resume with the argument stderr names.
-- **Report the result as the CLI gave it.** Report failures as they are; there
-  is no MCP or private-route fallback. Never treat an empty result as clean:
-  `page inspect` names the kind of empty through `observations.coverage`,
-  `page issues` through `availableKeys`, `search cohorts` through
-  `analysed: false`, and `vitals summary` through `available: false`. A refusal
-  reads differently again: `status`, `page issues` and `search cohorts` exit
-  `4` or `5` on an archived or paused Site, which is never an empty Site. Other
-  commands may still return Provisional evidence. Quote the counts a result
-  ships with, never the length of its list: `data.total` from `page issues`,
-  then `coverage.accessibilityChecksTotal` and
-  `coverage.bestPracticesChecksTotal` from `scans show`. Neither command
-  reports the dropped row count, so `possiblyTruncated: true` marks the list as
-  a floor.
+- Start the comment with an agent disclosure. Give reproduction steps, the
+  expected and actual behaviour, and any workaround.
+- Pass `--request-id` when the response had one. Use `--intent improvement`
+  for a suggestion; the default is `bug`.
+- Send sanitized details only: no tokens, cookies, personal data, private URLs,
+  customer content, raw logs, or full response bodies.
+- The limit is ten reports per credential per hour. If a report fails, say so
+  and continue. Never retry it or report the failure.