@nuxtseo/cli 0.1.3 → 0.2.0

package/dist/skill.d.ts

@@ -0,0 +1,22 @@
+import type { CliResult } from './failures.js';
+export declare const SKILL_NAME = "nuxtseo-cli";
+export declare const SKILL_AGENTS: readonly ['claude', 'codex'];
+export type SkillAgent = typeof SKILL_AGENTS[number];
+export interface SkillInstallation {
+    agent: SkillAgent;
+    source: string;
+    destination: string;
+}
+/**
+ * The skill shipped inside this package. A global install puts it outside the
+ * project, so the documented `cp -R node_modules/...` path does not exist for
+ * the user who most needs it. Resolve it from this module instead.
+ */
+export declare function skillSourceDirectory(moduleUrl?: string): string;
+export declare function skillDestination(homeDirectory: string, agent: SkillAgent): string;
+export declare function installSkill(options: {
+    agent: SkillAgent;
+    homeDirectory: string;
+    target?: string;
+    sourceDirectory?: string;
+}): Promise<CliResult<SkillInstallation>>;

package/dist/skill.js

@@ -0,0 +1,56 @@
+import { cp, mkdir, stat } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, relative } from 'pathe';
+import { EXIT_CODE, fail, ok } from './failures.js';
+export const SKILL_NAME = 'nuxtseo-cli';
+/**
+ * Directories inside the packaged skill that exist for this repository and not
+ * for the person installing it. `npm` keeps them out of the tarball through the
+ * `files` negation; this keeps them out of an installed skill directory too,
+ * because a negation cannot reach a recursive copy.
+ */
+const SKILL_LOCAL_ONLY = new Set(['evals']);
+export const SKILL_AGENTS = ['claude', 'codex'];
+const AGENT_DIRECTORIES = {
+    claude: '.claude',
+    codex: '.codex',
+};
+/**
+ * The skill shipped inside this package. A global install puts it outside the
+ * project, so the documented `cp -R node_modules/...` path does not exist for
+ * the user who most needs it. Resolve it from this module instead.
+ */
+export function skillSourceDirectory(moduleUrl = import.meta.url) {
+    return join(dirname(fileURLToPath(moduleUrl)), '..', 'skills', SKILL_NAME);
+}
+export function skillDestination(homeDirectory, agent) {
+    return join(homeDirectory, AGENT_DIRECTORIES[agent], 'skills', SKILL_NAME);
+}
+export async function installSkill(options) {
+    const source = options.sourceDirectory ?? skillSourceDirectory();
+    const readable = await stat(source).catch(() => {
+        // A missing directory and an unreadable one need the same repair, and the
+        // next line reports the path either way.
+        return null;
+    });
+    if (!readable?.isDirectory()) {
+        return fail(EXIT_CODE.infrastructure, `skill_source_missing: The packaged skill is missing at ${source}.\nReinstall @nuxtseo/cli, then run the command again.`);
+    }
+    const destination = options.target
+        ? join(options.target, SKILL_NAME)
+        : skillDestination(options.homeDirectory, options.agent);
+    const written = await mkdir(dirname(destination), { recursive: true })
+        .then(() => cp(source, destination, {
+        recursive: true,
+        force: true,
+        filter: (entry) => {
+            const [segment] = relative(source, entry).split('/');
+            return !segment || !SKILL_LOCAL_ONLY.has(segment);
+        },
+    }))
+        .then(() => ok(undefined))
+        .catch(cause => fail(EXIT_CODE.infrastructure, `skill_install_failed: Could not write the skill to ${destination}.\nCheck the directory permissions, then run the command again.`, cause));
+    if (written._tag === 'Err')
+        return written;
+    return ok({ agent: options.agent, source, destination });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Command line interface for the NuxtSEO public API.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com/pro",
@@ -25,26 +25,27 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "!skills/**/evals"
   ],
   "engines": {
     "node": ">=22"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
+    "@nuxtseo/sdk": "^0.2.0",
     "citty": "^0.2.2",
-    "pathe": "^2.0.3",
-    "@nuxtseo/sdk": "^0.1.3"
+    "pathe": "^2.0.3"
   },
   "optionalDependencies": {
-    "@napi-rs/keyring": "^1.3.0"
+    "@napi-rs/keyring": "^2.0.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@types/node": "^26.2.0",
+    "@nuxtseo/protocol": "0.2.0",
+    "@types/node": "^26.4.0",
     "publint": "^0.3.24",
-    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.10.tsgo.7.0.2",
-    "@nuxtseo/protocol": "0.1.3"
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.15.tsgo.7.0.2"
   },
   "publishConfig": {
     "access": "public"

package/skills/nuxtseo-cli/SKILL.md

@@ -1,75 +1,77 @@
 ---
 name: nuxtseo-cli
-description: Drive the `nuxtseo` CLI for Site triage, Search Console rows, keyword and competitor research, SERP analysis, rankings, link opportunities, Content Briefs, content decay, duplicate clusters, scans, 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 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.
 ---
 
 # 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 providers only through a declared public API operation.
+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 repo you are working in.
+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.
 
-## Data boundaries
+## Reference files
 
-Most commands read stored Site evidence. Three commands can start live research:
+Read each one before you act on its subject:
 
-- `research keywords`
-- `research serp`
-- `research rankings`
-
-These commands use the Team research allowance when the server misses its
-cache. Keyword JSON reports cache use in `evidence`. SERP and ranking JSON
-report `cached`.
-
-`search status` reads stored connection state. It never waits for Google.
-`search analytics` reads Search Console rows through the public API.
-`search indexing` reads retained URL Inspection coverage through the public API.
+- [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
-npx -y @nuxtseo/cli@latest --version    # no install
+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 itself, the package is
-not published, so run the built entry directly:
+Node 22 or newer is required.
+
+Inside the NuxtSEO monorepo the package is not published. Run the built entry
+directly:
 
 ```sh
 node packages/cli/dist/cli-entry.js --version
 ```
 
-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.
+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.
 
 ## Before the first command
 
 ```sh
-nuxtseo whoami --json          # validates the token, lists Site count
+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 instead.
+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.
+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` and always pass `--site <site-id>`.
+Always pass `--json` and `--site <site-id>`.
 
 ```sh
 nuxtseo actions list --site site_123 --json
@@ -79,96 +81,223 @@ nuxtseo actions list --site site_123 --json
 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, so a token whose role cannot list Sites
-still works. If more than one Site is accessible and `--site` is absent, the CLI
+`--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. |
+| `--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. Before parsing envelopes, paging, or
-handling failures, read [CLI protocol](references/protocol.md).
-
-## Commands
-
-| Command | Reads | Notes |
-| --- | --- | --- |
-| `whoami` | Token validity, API host, Site count | Cheapest health check |
-| `sites list` | Every accessible Site | Source of Site IDs |
-| `sites use <site-id>` | – | Persists a default Site for the human, not for you |
-| `usage` | Plan and meters | `--group integrations\|compute\|capacity` |
-| `actions list` | Server-ranked issues and opportunities | `--limit 1..25` (default 10), `--offset`. JSON carries `evidence.freshness`; `verdict: "aged"` means the observation is over a day old, so live-check before fixing |
-| `actions show <action-id>` | One issue or opportunity plus evidence | `--limit 1..100` (default 50), `--group-id`, `--cursor` |
-| `actions resolve <action-id>` | – | Mutation. Claims the issue or opportunity and starts server verification |
-| `backlinks recoverable` | Stored recoverable backlinks | `--limit 1..200`, `--offset` |
-| `mentions list` | Stored mentions | `--limit 1..200` |
-| `page inspect <url>` | Stored observations, Lighthouse, keywords | `--limit 1..200`, `--offset`, `--include-resolved`. JSON carries `observations.coverage`: `never-scanned` means no source recorded this Page, `scanned-clear` means recorded and all clear |
-| `page scan <url>` | – | Mutation. Starts mobile and desktop scans |
-| `performance` | Site performance overview | Medians for perf, a11y, SEO, LCP, TBT, CLS |
-| `search status` | Stored Search Console connection | Provider free |
-| `search analytics <pages\|keywords>` | Search Console Page or query rows | `--period`, `--limit`, `--page`, `--search` |
-| `search indexing <summary\|urls>` | Retained URL Inspection coverage | `summary` returns indexed counts; `urls` supports `--issue`, `--status`, `--limit`, `--offset` |
-| `research overview` | Stored Site and competitor research | Metrics, history, gaps, and quick wins |
-| `research keywords <topic>` | Live keyword ideas | Volume, difficulty, intent, and cost data |
-| `research serp <keyword>` | Live SERP snapshot | Results, features, and fetch time |
-| `research rankings <domain>` | Live domain rankings | Current keywords and domain metrics |
-| `audit link-opportunities` | Stored internal link opportunities | Includes crawl coverage |
-| `audit content-decay` | Stored decaying Pages | Includes Search Console loss evidence |
-| `audit duplicates` | Stored duplicate clusters | Includes members and keep candidate |
-| `content briefs list` | Content Brief summaries | `--status`, `--limit`, `--offset` |
-| `content briefs show <brief-id>` | One Content Brief | Includes its grounded payload |
-| `content briefs create <keyword>` | – | Mutation. `--target-page` is optional |
-| `config` | Local config path, API host, selected Site | Local only |
-
-`page inspect` and `page scan` take an absolute URL, for example
-`https://example.com/about`.
-
-`--help --json` returns a `CliHelp` value for one command level: its
-`arguments`, the inherited `globalOptions`, and its `subcommands` as names and
-descriptions only. To learn a subcommand's own flags, ask it directly, for
-example `nuxtseo actions list --help --json`. Use this instead of guessing a
-flag, and prefer the table above for anything it already answers.
+Parse JSON. Never scrape human output.
+
+Every `--json` run prints one envelope. For example, `status` returns this,
+abridged:
+
+```sh
+nuxtseo status --site site_01JXYZ --json
+```
+
+```json
+{
+  "data": {
+    "available": true,
+    "dataQuality": { "status": "complete", "reason": null },
+    "nextAction": { "kind": "action", "actionId": "act_01JXYZ" }
+  },
+  "meta": { "requestId": "req_01JXYZ", "version": "1.0" }
+}
+```
+
+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 is the sequence that turns CLI output into a code change:
-
-1. `nuxtseo actions list --site <id> --json` gives ranked work with an ID, a
-   diagnosis, an effort, and an affected page count. Check
-   `evidence.freshness` per row: `verdict: "aged"` with a large `ageHours`
-   means the evidence is old. Live-check a cheap sample before fixing, because
-   the site may have moved on since the observation.
-2. `nuxtseo actions show <action-id> --site <id> --json` gives the evidence:
-   which pages, which finding type, and when it was observed.
-3. Fix the cause in the repository. The evidence names URLs; map them back to
-   routes, components, or config.
-4. Deploy or preview the fix, then `nuxtseo page scan <url> --site <id> --yes
-   --json` to ask for fresh scans of a page you changed.
-5. `nuxtseo actions resolve <action-id> --site <id> --yes --json` claims the
-   action. The server verifies it; the CLI does not mark 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 2 and decide again.
+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
+```
+
+**Step 1. Read the Site verdict.**
+
+```sh
+nuxtseo status --site <site-id> --json
+```
+
+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.**
+
+```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.
+
+**Step 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:
+
+- `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.
+
+**Step 4. Fix the cause in the repository.**
+
+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:
+
+```sh
+nuxtseo page scan <url> --site <site-id> --yes --json
+```
+
+**Step 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.
+
+When the fix is a deliberate removal rather than a repair, dismiss instead of
+resolving:
+
+```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.
+
+**Step 7. Mark the day the fix shipped.**
+
+```sh
+nuxtseo annotations create --site <site-id> --date "$(date -u +%F)" --title "Fixed canonicals on /docs" --yes --json
+```
+
+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.
+
+## Route-family indexing: two lists, one claim
+
+`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.
+
+- `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.
+
+`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.
 
 ## Guardrails
 
-- Ask before you mutate. `actions resolve` and `page scan` consume quota and
-  change server state. `--yes` is consent you are borrowing from the user, so
-  get it first unless the user already asked for that exact action.
-- Do not loop over Pages, keywords, or domains unattended. Check `usage` first.
-- Live research can consume allowance. A cached result does not consume a unit.
-- Report failures as they are. The CLI has no MCP or private-route fallback.
-- Do not treat an empty result as clean. `page inspect` JSON says which empty
-  it is through `observations.coverage`; other commands may still have
-  incomplete evidence.
+- **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.