@nuxtseo/cli 0.4.1 → 0.5.1

package/README.md

@@ -239,10 +239,14 @@ a different dataset: `vitals summary` and `vitals trend` read CrUX field p75,
 and `vitals findings` names the DOM element behind each failing vital.
 `status` reads the Site assessment: the verdict, the one ranked Next Action, and
 what changed. Start there. `status`, `page issues` and `search cohorts` refuse
-with exit `4` or `5` on an archived or paused Site.
+with exit `4` or `5` on a paused Site. Removed Sites return `not_found` with exit `8`.
 The four live `backlinks` reads need the Site to have a URL. Without one they
 exit `2`, and retrying will not help; set the Site URL first.
-`search cohorts` returns two lists. Only `established` is proven; `ranked` is
+`status` reports `assessment.scope`: `site` when the headline covers the whole
+Site, `route-family` when one family leads. `assessment.aggregate` always holds
+the whole-Site verdict.
+`search cohorts` returns `analysed: false` with `reason: sampled-index-state`
+when the not-indexed list is a sample. Otherwise it returns two lists. Only `established` is proven; `ranked` is
 ordered by raw rate with no significance test and is leads only.
 `backlinks summary`, `backlinks referring-domains`, `backlinks anchors`,
 `backlinks history`, `research domain-traffic` and `research domain-availability`
@@ -250,7 +254,7 @@ can use the Team research limit. Each response reports
 cache use in `evidence`; a cached response spends nothing. `backlinks recoverable`
 reads retained rows and spends nothing.
 `search status` reads stored connection state. It never waits for Google.
-`search indexing summary` reads retained URL Inspection coverage.
+`search indexing summary` reads retained URL Inspection coverage. `asOf` and `oldestCheckAt` bound the age of its verdicts.
 `search index-history` dates an indexing change against known releases.
 `search inspect <url>` reads Google's own verdict for one URL.
 `page inspect <url>` reads the Nuxt SEO observation store for the same URL.
@@ -331,3 +335,21 @@ and what to do for each exit code.
 The CLI prints the exact server error code. When available, stderr also includes
 the request ID, retry delay, rate limit, reset time, and structured details.
 The CLI never falls back to MCP, a private route, or cached feature data.
+
+### Claim response
+
+`actions resolve` saves your Claim. It returns before a requested scan finishes starting.
+`status: "open"` stays unchanged until the engine verifies the Action.
+Human output shows `Claimed, verifying` and the suggested check-back time.
+Claimed Actions leave `actions list`. Use `actions show <action-id>` to check them.
+
+Both `resolve` and `show` return these additive fields:
+
+| Field | Meaning |
+| --- | --- |
+| `markedAt` | ISO timestamp when your Claim was saved, or `null` before a Claim. |
+| `checkBackAt` | Suggested ISO timestamp to check again, or `null` when no automated check applies. |
+
+A check-back time does not promise a completed check.
+`scan-queued` can mean a re-assessment using scheduled crawl results, without a new scan.
+A self-resolved Claim returns `status: "verified"` and `verification: "user-resolved"`.

package/dist/cli-entry.js

@@ -12,6 +12,7 @@ function outputError(cause) {
 }
 process.once('SIGINT', abort);
 process.once('SIGTERM', abort);
+// stdout writes can finish after runCli returns. Keep this handler for the process lifetime.
 process.stdout.once('error', outputError);
 async function readStdin() {
     process.stdin.setEncoding('utf8');
@@ -38,4 +39,3 @@ process.exitCode = await runCli(process.argv.slice(2), {
 });
 process.removeListener('SIGINT', abort);
 process.removeListener('SIGTERM', abort);
-process.stdout.removeListener('error', outputError);

package/dist/commands.js

@@ -175,10 +175,11 @@ async function login(runtime, globals, options) {
     const apiUrl = await resolveApiUrl({ apiUrl: globals.apiUrl, env: runtime.env, paths: runtime.paths });
     if (apiUrl._tag === 'Err')
         return fromStateError(apiUrl.error);
-    // Pairing needs a browser and a person. Without an interactive terminal the
-    // old paste path is the only one that can complete, so CI keeps working
-    // unchanged.
-    const token = options.withToken || !runtime.interactive
+    // Pairing needs a person to approve it, and `--no-browser` says that person
+    // will open the printed URL themselves, so it is available on a headless
+    // machine too. Without the flag a non-interactive terminal keeps the paste
+    // path, so CI keeps working unchanged.
+    const token = options.withToken || (!runtime.interactive && !options.noBrowser)
         ? await readLoginToken(runtime)
         : await pairInBrowser(runtime, apiUrl.value.apiUrl, { openBrowser: !options.noBrowser });
     if (token._tag === 'Err')
@@ -1222,7 +1223,11 @@ async function actionDismiss(runtime, globals, args) {
         return fail(EXIT_CODE.invalidInput, 'Pass the action id to dismiss.', undefined, 'invalid_cli_input');
     if (!args.artifactVersion)
         return fail(EXIT_CODE.invalidInput, 'Pass --artifact-version, the artifactVersion returned with this action.', undefined, 'invalid_cli_input');
-    const confirmed = await confirmMutation(runtime, globals, `Dismiss action ${args.actionId}? The page stays removed.`);
+    if (args.note !== undefined && (!args.note.trim() || args.note.trim().length > 2000))
+        return fail(EXIT_CODE.invalidInput, 'Pass --note with 1 to 2000 characters.', undefined, 'invalid_cli_input');
+    const confirmed = await confirmMutation(runtime, globals, args.note
+        ? `Dismiss action ${args.actionId}? Your note records this decision. No fix is verified.`
+        : `Dismiss action ${args.actionId}? The page stays removed.`);
     if (confirmed._tag === 'Err')
         return confirmed;
     if (!confirmed.value) {
@@ -1234,7 +1239,7 @@ async function actionDismiss(runtime, globals, args) {
         return resolved;
     const response = await withSpinner(runtime, 'Dismissing action', () => resolved.value.api.client.actions.dismiss({
         params: { siteId: resolved.value.siteId, actionId: args.actionId },
-        body: { artifactVersion: args.artifactVersion },
+        body: { artifactVersion: args.artifactVersion, ...(args.note !== undefined ? { note: args.note.trim() } : {}) },
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderActionDismissal(value.data));
 }
@@ -1558,14 +1563,16 @@ export function createRootCommand(runtime, globals, execution) {
                 run: ({ args }) => capture(execution, () => actionsResolve(runtime, globals, args.actionId), args._, 1)(),
             }),
             dismiss: defineCommand({
-                meta: { name: 'dismiss', description: 'Dismiss a broken-page action so the page stays removed' },
+                meta: { name: 'dismiss', description: 'Dismiss reviewed work with a note, or confirm an unlinked page removal' },
                 args: {
                     'actionId': positional('action-id', 'Action ID'),
                     'artifact-version': { type: 'string', description: 'The artifactVersion returned with this action' },
+                    'note': { type: 'string', description: 'Why this action is intentional or incorrect, 1 to 2000 characters' },
                 },
                 run: ({ args }) => capture(execution, () => actionDismiss(runtime, globals, {
                     actionId: args.actionId,
                     artifactVersion: args['artifact-version'],
+                    note: args.note,
                 }), args._, 1)(),
             }),
         },

package/dist/failures.js

@@ -41,7 +41,7 @@ function defaultFailureCode(exitCode) {
 export function fail(exitCode, message, cause, code = defaultFailureCode(exitCode)) {
     return { _tag: 'Err', error: { _tag: 'CliFailure', code, exitCode, message, cause } };
 }
-function apiExitCode(code, retryable) {
+function apiExitCode(code, retryable, details = {}) {
     switch (code) {
         case 'invalid_request':
             return EXIT_CODE.invalidInput;
@@ -57,8 +57,14 @@ function apiExitCode(code, retryable) {
             return EXIT_CODE.conflict;
         case 'rate_limited':
         case 'quota_exhausted':
-        case 'provider_unavailable':
             return EXIT_CODE.retryable;
+        case 'provider_unavailable':
+            // A provider that refuses to serve until its own billing is settled
+            // cannot be retried into working, so the caller must not treat it as a
+            // transient outage.
+            return details.providerCode === 'provider_payment_required'
+                ? EXIT_CODE.authorization
+                : EXIT_CODE.retryable;
         case 'not_found':
             return EXIT_CODE.notFound;
         case 'contract_violation':
@@ -201,7 +207,7 @@ export function fromSdkFailure(error) {
                 error: {
                     _tag: 'CliFailure',
                     code: error.code,
-                    exitCode: apiExitCode(error.code, error.retryable),
+                    exitCode: apiExitCode(error.code, error.retryable, error.details),
                     message: [
                         `${error.code}: ${error.message}`,
                         ...metadataLines(error),

package/dist/pull.js

@@ -325,6 +325,11 @@ export async function runPull(runtime, globals, args, resolve, catalogue = PULL_
         if (outcome.exitCode === EXIT_CODE.authentication || outcome.exitCode === EXIT_CODE.interrupted)
             stopped = true;
         writeDiagnostic(runtime, `[${completed}/${operations.length}] ${candidate.name} ${outcome.failure ? `failed: ${outcome.failure.code}` : 'ok'}`);
+        if (outcome.failure?.code === 'request_timeout' && timeoutMs < 300_000) {
+            const retryTimeout = Math.min(timeoutMs * 2, 300_000);
+            // Retry only this read. Repeating a full paid pull can spend twice.
+            writeDiagnostic(runtime, `Retry: nuxtseo pull --site ${resolved.value.siteId} --include ${JSON.stringify(candidate.name)} --period ${period.value} --timeout-ms ${retryTimeout}${candidate.spendsResearch ? ' --with-research' : ''} --json`);
+        }
     });
     const failed = exitCodes.filter(code => code !== EXIT_CODE.success).length;
     writeDiagnostic(runtime, [

package/dist/render.d.ts

@@ -3,7 +3,7 @@ import type { AccountTokenData } from '@nuxtseo/protocol/v1/account';
 import type { ActionDismiss, ActionList, ActionResolve, ActionShow } from '@nuxtseo/protocol/v1/actions';
 import type { AnalyticsQueryData, AnalyticsView } from '@nuxtseo/protocol/v1/analytics';
 import type { AuditChanges, AuditContentDecay, AuditDuplicateClusters, AuditLinkOpportunities, AuditLinkStructure } from '@nuxtseo/protocol/v1/audit';
-import type { BacklinkAnchors, BacklinksHistory, BacklinksSummary, MentionsData, RecoverableBacklinksData, ReferringDomains } from '@nuxtseo/protocol/v1/backlinks';
+import type { BacklinkAnchorsData, BacklinksHistory, BacklinksSummaryData, MentionsData, RecoverableBacklinksData, ReferringDomainsData } from '@nuxtseo/protocol/v1/backlinks';
 import type { IndexCohorts, IndexingDiagnosticsData, IndexingHistoryData, SearchAnalyticsData, SearchStatusData, UrlInspectionData } from '@nuxtseo/protocol/v1/gsc';
 import type { PageInspectData, PageIssues, PageScan } from '@nuxtseo/protocol/v1/pages';
 import type { FieldVitalFindings, FieldVitals, MonitoredPages, PerformanceScanDetail, PerformanceScans, SitePerformanceOverview } from '@nuxtseo/protocol/v1/performance';
@@ -46,9 +46,14 @@ export declare function renderRecoverableBacklinks(data: RecoverableBacklinksDat
 export declare function renderMentions(data: MentionsData): string;
 export declare function renderFieldVitals(data: FieldVitals): string;
 export declare function renderFieldVitalFindings(data: FieldVitalFindings): string;
-export declare function renderBacklinksSummary(data: BacklinksSummary): string;
-export declare function renderReferringDomains(data: ReferringDomains): string;
-export declare function renderBacklinkAnchors(data: BacklinkAnchors): string;
+/**
+ * With Link Spam Networks, the two profile counts print without them, and each
+ * count says how many more the networks hold. `linkSpamNetworks` is absent from
+ * an API that predates it, and the summary then prints as it always did.
+ */
+export declare function renderBacklinksSummary(data: BacklinksSummaryData): string;
+export declare function renderReferringDomains(data: ReferringDomainsData): string;
+export declare function renderBacklinkAnchors(data: BacklinkAnchorsData): string;
 export declare function renderBacklinksHistory(data: BacklinksHistory): string;
 export declare function renderSiteStatus(data: SiteStatus): string;
 export declare function renderActionDismissal(data: ActionDismiss): string;

package/dist/render.js

@@ -58,7 +58,9 @@ export function renderAction(data) {
     return [
         fields([
             ['Action', data.id],
-            ['Status', data.status],
+            ['Status', data.markedAt && data.status === 'open' ? 'Claimed, verifying' : data.status],
+            ['Claimed at', data.markedAt ?? ''],
+            ['Check back at', data.checkBackAt ?? ''],
             ['Diagnosis', data.diagnosis],
             ['Do', data.action],
             ['Finding', data.findingType],
@@ -70,7 +72,9 @@ export function renderAction(data) {
 export function renderActionResolution(data) {
     return fields([
         ['Action', data.actionId],
-        ['Status', data.status],
+        ['Status', data.markedAt && data.status === 'open' ? 'Claimed, verifying' : data.status],
+        ['Claimed at', data.markedAt ?? ''],
+        ['Check back at', data.checkBackAt ?? ''],
         ['Verification', data.verification],
     ]);
 }
@@ -429,7 +433,11 @@ export function renderIndexingDiagnostics(data) {
                 ['Indexed', data.indexed],
                 ['Not indexed', Math.max(0, data.totalUrls - data.indexed)],
                 ['Indexed rate', indexedPercent],
+                ['Oldest check', data.oldestCheckAt],
                 ['As of', data.asOf],
+                ['As of source', data.asOfSource],
+                ['Verdicts older than 7d', data.verdictFreshness ? `${data.verdictFreshness.olderThan7dPercent}%` : null],
+                ['Verdicts older than 30d', data.verdictFreshness ? `${data.verdictFreshness.olderThan30dPercent}%` : null],
             ]),
             ...(issues.length > 0 ? ['Issues', ...issues] : []),
         ].join('\n');
@@ -437,7 +445,7 @@ export function renderIndexingDiagnostics(data) {
     if (data.urls.length === 0)
         return 'No Search Console indexing URLs match these filters.';
     return [
-        `Search Console indexing URLs (${data.urls.length} of ${data.total})`,
+        `Search Console indexing URLs (${data.urls.length} of ${data.totalSemantics === 'lower-bound' ? 'at least ' : ''}${data.total})`,
         ...data.urls.map(row => `${row.verdict ?? 'unknown'}  ${row.coverageState ?? 'unknown'}\n  ${row.url}`),
         data.hasMore ? `More URLs available after offset ${data.offset + data.limit}.` : '',
     ].filter(Boolean).join('\n');
@@ -618,12 +626,53 @@ export function renderFieldVitalFindings(data) {
 function spendLine(evidence) {
     return ['Source', `${evidence._tag} (${evidence.spend.units} unit)`];
 }
+function counted(count, one, many) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+/**
+ * The anchor is third-party text. JSON quoting keeps a network on one line and
+ * prints a control character, such as a terminal escape, as an escape code.
+ */
+function linkSpamNetworkLine(network) {
+    return [
+        counted(network.referringDomains, 'domain', 'domains'),
+        JSON.stringify(network.anchor),
+        network.linkingPath === null ? '' : `from ${network.linkingPath}`,
+        network.otherSites > 0 ? `on ${counted(network.otherSites, 'other Site', 'other Sites')}` : '',
+    ].filter(Boolean).join('  ');
+}
+/**
+ * The two profile counts without the networks, each followed by the part of the
+ * total the networks hold, so the two numbers add up to the total. The server
+ * never subtracts below the stored domains outside every network, so that part
+ * can be smaller than the networks' own counts.
+ */
+function countsWithoutNetworks(data, without, networks) {
+    const width = Math.max(String(without.backlinks).length, String(without.referringDomains).length);
+    const inNetworks = counted(networks.length, 'link spam network', 'link spam networks');
+    const count = (total, own, networkCount) => {
+        const held = total === null ? networkCount : Math.max(total - own, 0);
+        return `${String(own).padEnd(width)}  (${held} more in ${inNetworks})`;
+    };
+    return {
+        backlinks: count(data.backlinks, without.backlinks, networks.reduce((sum, network) => sum + network.backlinks, 0)),
+        referringDomains: count(data.referringDomains, without.referringDomains, networks.reduce((sum, network) => sum + network.referringDomains, 0)),
+    };
+}
+/**
+ * With Link Spam Networks, the two profile counts print without them, and each
+ * count says how many more the networks hold. `linkSpamNetworks` is absent from
+ * an API that predates it, and the summary then prints as it always did.
+ */
 export function renderBacklinksSummary(data) {
-    return fields([
+    const networks = data.linkSpamNetworks ?? [];
+    const without = networks.length > 0 ? data.withoutLinkSpamNetworks ?? null : null;
+    const counts = without ? countsWithoutNetworks(data, without, networks) : data;
+    const totals = fields([
         ['Target', data.target],
         ['Domain rank', data.rank],
-        ['Backlinks', data.backlinks],
-        ['Referring domains', data.referringDomains],
+        ['Backlinks', counts.backlinks],
+        ['Referring domains', counts.referringDomains],
         ['Referring main domains', data.referringMainDomains],
         ['Referring pages', data.referringPages],
         ['Broken backlinks', data.brokenBacklinks],
@@ -631,6 +680,30 @@ export function renderBacklinksSummary(data) {
         ['Spam score', data.spamScore],
         spendLine(data.evidence),
     ]);
+    if (networks.length === 0)
+        return totals;
+    return [
+        totals,
+        [`Link spam networks (${networks.length})`, ...networks.map(network => `  ${linkSpamNetworkLine(network)}`)].join('\n'),
+    ].join('\n\n');
+}
+const LINK_SPAM_NETWORK_MARK = '  (link spam network)';
+/**
+ * A row the server tagged as a Link Spam Network member ends with a marker, and
+ * one line under the list counts them. An untagged row is not known to be in a
+ * network, which is never "verified clean". An API that predates the field
+ * tags nothing, and the list prints as it always did.
+ */
+function networkMark(item) {
+    return item.linkSpamNetworkId ? LINK_SPAM_NETWORK_MARK : '';
+}
+function linkSpamNetworkFooter(items) {
+    const tagged = items.filter(item => item.linkSpamNetworkId).length;
+    if (tagged === 0)
+        return [];
+    return [tagged === 1
+            ? '1 row is in a link spam network. Google ignores most links like these.'
+            : `${tagged} rows are in link spam networks. Google ignores most links like these.`];
 }
 export function renderReferringDomains(data) {
     if (data.items.length === 0)
@@ -638,17 +711,17 @@ export function renderReferringDomains(data) {
     return [
         `Referring domains for ${data.target} (${data.items.length} of ${data.total})`,
         ...data.items.map(item => [
-            `${item.domain}`,
+            `${item.domain}${networkMark(item)}`,
             `  ${fields([
                 ['rank', item.rank],
                 ['backlinks', item.backlinks],
                 ['referring pages', item.referringPages],
                 ['broken backlinks', item.brokenBacklinks],
-                ['spam score', item.spamScore],
                 ['sessions (90d)', item.sessions],
                 ['first seen', item.firstSeen],
             ]).split('\n').join('\n  ')}`,
         ].join('\n')),
+        ...linkSpamNetworkFooter(data.items),
         fields([spendLine(data.evidence)]),
     ].join('\n');
 }
@@ -658,7 +731,7 @@ export function renderBacklinkAnchors(data) {
     return [
         `Backlink anchors for ${data.target} (${data.items.length} of ${data.total})`,
         ...data.items.map(item => [
-            `${item.anchor || '(empty anchor)'}`,
+            `${item.anchor || '(empty anchor)'}${networkMark(item)}`,
             `  ${fields([
                 ['backlinks', item.backlinks],
                 ['referring domains', item.referringDomains],
@@ -667,6 +740,7 @@ export function renderBacklinkAnchors(data) {
                 ['first seen', item.firstSeen],
             ]).split('\n').join('\n  ')}`,
         ].join('\n')),
+        ...linkSpamNetworkFooter(data.items),
         fields([spendLine(data.evidence)]),
     ].join('\n');
 }
@@ -687,12 +761,16 @@ export function renderSiteStatus(data) {
         blocks.push([
             data.assessment.summary,
             `  ${data.assessment.recommendation}`,
+            ...(data.assessment.scope === 'route-family' && data.assessment.aggregate
+                ? [`Whole Site: ${data.assessment.aggregate.summary}`]
+                : []),
         ].join('\n'));
     }
     blocks.push(fields([
         ['Site', data.site],
         ['Reach', data.assessment?.reachStage],
         ['Health', data.assessment?.healthStage],
+        ['Headline scope', data.assessment?.scope],
         ['Assessed', data.assessment?.assessedAt],
         ['Data quality', data.dataQuality.status === 'complete'
                 ? 'complete'

package/dist/skill.js

@@ -211,6 +211,22 @@ export function skillNoticeFor(installed, current, agent) {
 }
 export function skillNoticeLine(notice) {
     const installed = notice.installed === null ? 'skill version unknown' : `skill ${notice.installed} installed`;
+    if (notice.installed !== null) {
+        const installedParts = /^(\d+)\.(\d+)\.(\d+)$/.exec(notice.installed);
+        const currentParts = /^(\d+)\.(\d+)\.(\d+)$/.exec(notice.current);
+        if (installedParts && currentParts) {
+            for (let part = 1; part <= 3; part++) {
+                const difference = Number(installedParts[part]) - Number(currentParts[part]);
+                if (difference > 0)
+                    return `${installed}, CLI ${notice.current}. Update CLI before refreshing the skill: pnpm add -g @nuxtseo/cli`;
+                if (difference < 0)
+                    break;
+            }
+        }
+        else {
+            return `${installed}, CLI ${notice.current}. Check which version is newer before refreshing the skill.`;
+        }
+    }
     return `${installed}, CLI ${notice.current}. Refresh with: nuxtseo skill install --agent ${notice.agent}`;
 }
 export function parseSkillCheckCache(content) {

package/package.json

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

package/skills/nuxtseo-cli/SKILL.md

@@ -28,13 +28,23 @@ Read the matching file before you act on its subject:
    pnpm add -g @nuxtseo/cli                 # global install, Node 22+
    ```
 
-   Inside the Nuxt SEO monorepo, run `node packages/cli/dist/cli-entry.js`
-   instead.
+   Inside the Nuxt SEO monorepo, build the workspace dependencies in order
+   before using `node packages/cli/dist/cli-entry.js`:
 
-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
+   ```sh
+   pnpm --filter @nuxtseo/protocol build
+   pnpm --filter @nuxtseo/sdk build
+   pnpm --filter @nuxtseo/cli build
+   node packages/cli/dist/cli-entry.js --version --json
+   ```
+
+   Use a task-owned worktree. Missing `dist` files and missing named exports
+   can mean stale builds. Rebuild all three packages before diagnosing source.
+
+2. **Skill version.** Run `nuxtseo --version --json`. Compare the CLI version
+   with this file's frontmatter version. If the CLI is older, update the CLI
+   first. If the skill is older, run `nuxtseo skill install --agent claude` and
+   re-read this file. An older skill hides commands. If
    `NUXTSEO_NO_UPDATE_CHECK` is set, the line never appears; compare this
    file's frontmatter `version` with the binary instead.
 
@@ -107,10 +117,25 @@ nuxtseo status --site <site-id> --json
 ```
 
 - `available: false` means the first assessment has not run.
+- Read `assessment.scope` before you quote `assessment.summary`. `site` means
+  the headline describes the whole Site. `route-family` means it describes one
+  Route family: a lead to check, never the Site verdict. `assessment.aggregate`
+  is always the whole-Site verdict. If `healthStage` is `quality_rejection`,
+  the whole Site is affected, whatever a route family shows.
+  `quality_rejection` is a broad indexing stage. It includes discovery gaps.
+  Read the summary and Google coverage reasons before blaming content quality.
+  It does not prove that Google crawled and rejected the pages.
+  The stored assessment and retained indexing summary have separate clocks.
+  Compare `assessment.assessedAt` with indexing `asOf` before comparing their counts.
 - 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.
+- `openCount` counts open and in-progress Actions. `actions list` returns the
+  admitted, unclaimed worklist. These counts can differ. A stored Next Action
+  can still be readable through `actions show` when the worklist omits it.
+- A `candidate:` finding with diagnosis `Shadow observation` is a canary,
+  not a verified repair cause. Inspect its details before proposing work.
 
 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:
@@ -119,6 +144,18 @@ every spend-free Site read and writes one envelope per line:
 nuxtseo pull --site <site-id> --json > site.ndjson
 ```
 
+Inspect every line's `command` and `error`. If one read times out, retry that
+read with the suggested timeout. Do not repeat successful or paid reads.
+If the longer request returns a provider failure, report the request ID.
+Retained `page issues` rows can name URLs, but do not replace Google's verdict.
+
+For full analytics exports, use `--all --limit 100`. Each run stops after
+50 requests. If it exits with `paging_cap_reached`, preserve the arguments
+and continue with the printed resume argument. Save each run separately.
+Check row keys for repeats across pages. Repeated keyword rows can indicate
+unstable upstream ordering. Report that gap instead of claiming complete
+keyword coverage. Use Site timeseries totals for the Site-wide comparison.
+
 **2. Pick a ranked action.**
 
 ```sh
@@ -128,6 +165,10 @@ nuxtseo actions list --site <site-id> --json
 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.
+If freshness `confidence` is `reasserted`, its age dates the repeated finding.
+It does not date the underlying page observation. Read evidence group source
+clocks in `actions show`. Live-check affected pages when those clocks are
+unknown or old, even when the finding was recently reasserted.
 
 **3. Read the evidence.**
 
@@ -137,7 +178,11 @@ nuxtseo actions show <action-id> --site <site-id> --json
 
 It names the pages, the finding type, and when it was observed. If
 `data.workPrompt` is not null, it is the Work Prompt: the task for this action,
-grounded in its evidence. Start the fix from it. Two reads go deeper:
+grounded in its evidence. Start the fix from it.
+The Work Prompt serves several clients and may name MCP alternatives.
+Use its CLI commands in this workflow. Never switch to MCP as a fallback.
+
+Two reads go deeper:
 
 - `page issues --action-id <action-id>`: the raw observations, with URLs,
   status codes, redirect targets, and Lighthouse selectors. This is the
@@ -170,8 +215,14 @@ from `actions show`, then:
 nuxtseo actions dismiss <action-id> --site <site-id> --artifact-version <v> --yes --json
 ```
 
-The server admits a dismiss only for a broken-page action with complete 404 or
-410 evidence and no internal referrers.
+Without a note, the server admits a dismiss only for a broken-page action with
+complete 404 or 410 evidence and no internal referrers.
+
+If the owner confirms an action is intentional or incorrect, record that
+decision with `--note "<reason>"`. Review the exact scope first. A note dismisses
+the whole action, so never use it to hide a mix of intentional and broken URLs.
+Dismissal keeps the observations and does not verify a fix. The dashboard can
+restore the action later.
 
 **7. Mark the day.**
 
@@ -190,7 +241,7 @@ you got:
 | --- | --- |
 | `page inspect` | `observations.coverage` |
 | `page issues` | `availableKeys` |
-| `search cohorts` | `analysed: false`: no completed crawl, or no Google index state |
+| `search cohorts` | `analysed: false`: no completed crawl, no Google index state, or `reason: "sampled-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 |
 
@@ -200,15 +251,23 @@ a seed over three words, still exits `0`, and returns `keywords: []` with
 
 **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". Do not
-retry unchanged, and do not route around it with `pull` or another read.
+issues`, or `search cohorts` can mean a paused Site.
+Removed Sites return `not_found` with exit `8`. Report the blocker and stop.
+Do not read it as "no data" or "nothing wrong". Do not retry unchanged,
+and do not route around it with `pull` or another read.
 
 **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.
 
+For `search indexing urls`, read `totalSemantics` before quoting `total`.
+`lower-bound` means the provider used lookahead instead of counting every URL.
+The total can rise between pages without a filter change. Follow `hasMore` or
+use `--all`. A nonempty terminal page reports `exact` for that retained URL population.
+An empty page beyond offset zero reports `unknown`; its total can equal the requested offset.
+Do not compare this population with a summary or cohort from another capture.
+
 **Keep these datasets apart:**
 
 - `performance` and `scans *` read Lighthouse **lab** Scans. `vitals summary`
@@ -224,20 +283,40 @@ true` marks the list as a floor.
   `search inspect` read retained Search Console evidence.
 - An indexed count comes from `search indexing summary`, never from analytics
   rows. It counts retained URL Inspection evidence as of `data.asOf`, not
-  Google's live index. Name that source, quote `asOf`, and never label the
-  figure current or "right now", even in a summary line. See
+  Google's live index. Name that source, quote `asOf` with `oldestCheckAt`
+  (the evidence range), and never label the figure current or "right now",
+  even in a summary line. 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:
+before you list single not-indexed URLs. If it returns `analysed: false` with
+`reason: "sampled-index-state"`, the not-indexed list is a capped sample of the
+count Search Console reports. No family rate exists. Read `search indexing
+summary` instead, and never infer that unlisted URLs are indexed. 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.
+- `coverage.notIndexedNotInCrawl` counts not-indexed URLs that the Nuxt SEO
+  crawl did not reach. It does not count pages Google never crawled.
 - `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.
 
+**Compare equal windows.** Read `search analytics timeseries` for the Site's
+current and previous totals. `audit content-decay` ships its own `window`.
+It may span three months even when `pull --period 28d` selects 28-day analytics.
+Quote that window separately. Never present its losses as the 28-day decline.
+Content decay and duplicate reports return fixed shortlists. If `total` exceeds the returned
+row count, disclose both counts, even when `page.hasMore` is false. That flag
+does not promise the shortlist includes every Finding.
+
+**Check alternate formats.** A `.md` URL can serve the HTML page's content
+with a `Link: <html-url>; rel="canonical"` response header. Compare HTML
+siblings with HTML siblings. Do not remove a valid header canonical or add
+`noindex` just to clear a missing HTML canonical warning.
+
 ## Guardrails
 
 - **Get consent before a mutation.** `page scan`, `actions resolve`, `actions

package/skills/nuxtseo-cli/references/commands.md

@@ -120,19 +120,19 @@ lines.
 
 | Command | What it returns, and its flags |
 | --- | --- |
-| `status` | The Site assessment in one read: verdict, the single ranked Next Action, open and verified counts, degraded pipeline steps, recent changes, Receipts. `available: false` means the first assessment has not run. If the Site is archived or paused, this exits `4` or `5` rather than answering |
+| `status` | The Site assessment in one read: verdict, the single ranked Next Action, open and verified counts, degraded pipeline steps, recent changes, Receipts. `assessment.scope` says whether the headline covers the whole Site (`site`) or one route family (`route-family`); `assessment.aggregate` is always the whole-Site verdict. `available: false` means the first assessment has not run. Paused Sites exit `4` or `5`. Removed Sites return `not_found` with exit `8` |
 | `actions list` | Server-ranked issues and opportunities. `--limit 1..25` (default 10), `--offset`. Each row 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 its evidence. `--limit 1..100` (default 50), `--group-id`, `--cursor` |
 | `actions resolve <action-id>` | Mutation. Claims the issue or opportunity and starts server verification. Reads the action first and sends `artifactVersion` for you |
-| `actions dismiss <action-id>` | Mutation. Says the page stays removed. Needs `--artifact-version`, read from `actions show`. Admitted only for a broken-page action with complete 404 or 410 evidence and no internal referrers |
+| `actions dismiss <action-id>` | Mutation. Needs `--artifact-version`, read from `actions show`. `--note` records why the owner considers the action intentional or incorrect. Without a note, complete unlinked 404 or 410 evidence is required. Dismissal preserves observations and never verifies a fix |
 
 ## Pages, Scans, and lab performance
 
 | Command | What it returns, and its flags |
 | --- | --- |
 | `page inspect <url>` | Stored observations, Lighthouse rows and keywords for one Page. `--limit 1..200`, `--offset`, `--include-resolved`. Carries `observations.coverage`: `never-scanned` means no source recorded this Page, `scanned-clear` means recorded and all clear |
-| `page issues` | Raw Page Issue rows. Pass `--action-id`, or pass both `--source` and `--issue`. Passing both selectors exits `2`. `--url`, `--path-prefix`, `--include-resolved`, `--limit 1..200`, `--offset`. When the selector matches nothing, `availableKeys` lists the pairs this Site does have. If the Site is archived or paused, this exits `4` or `5` rather than answering |
-| `page scan <url>` | Mutation. Starts a mobile Scan and a desktop Scan |
+| `page issues` | Raw Page Issue rows. Pass `--action-id`, or pass both `--source` and `--issue`. Passing both selectors exits `2`. `--url`, `--path-prefix`, `--include-resolved`, `--limit 1..200`, `--offset`. When the selector matches nothing, `availableKeys` lists the pairs this Site does have. Paused Sites exit `4` or `5`. Removed Sites return `not_found` with exit `8` |
+| `page scan <url>` | Mutation. Adds or re-enables the URL as a monitored Page, then starts mobile and desktop Scans |
 | `performance` | Stored Lighthouse lab overview for the Site: medians for perf, a11y, SEO, LCP, TBT, CLS. Lab Scans, never real-user field data |
 | `scans list` | Retained Lighthouse Scans, newest first, with scores, lab vitals, and the error on a failed Scan. `--limit 1..100` (default 25) |
 | `scans show <scan-id>` | One Scan, and the evidence behind its scores: wasteful assets, repeat-visit cache policy, third-party scripts, the LCP element, and every failing accessibility and best-practices check with its CSS selectors and DOM snippets. Read `coverage` before quoting a total |
@@ -141,6 +141,17 @@ lines.
 `page inspect` and `page scan` take an absolute URL, for example
 `https://example.com/about`.
 
+`page scan` enables recurring monitoring.
+Read `scans pages` before scanning many new URLs. The server refuses a new
+Page when five monitored Pages are already enabled. That limit comes from
+the Page scan service, not the Team plan.
+
+`pageCreated: true` means a monitored Page was created. The URL may already
+have retained Scans. Automatic homepage assessment Scans use a separate
+slot without a monitored Page. A manual homepage Scan can therefore create
+a monitored Page while older homepage assessment Scans exist.
+The monitored Page then follows its own recurring schedule.
+
 ## Field Core Web Vitals
 
 | Command | What it returns, and its flags |
@@ -158,7 +169,7 @@ lines.
 | `search indexing <summary\|urls>` | Retained URL Inspection coverage. `summary` returns indexed counts. `urls` supports `--issue`, `--status`, `--limit 1..500` (default 50), `--offset` |
 | `search index-history` | Retained indexing changes and candidate causes. `--url`, `--field`, `--days 1..730`. Dates a regression against a release |
 | `search inspect <url>` | Google's own verdict for one URL. Takes an absolute URL or a site-relative path |
-| `search cohorts` | Not-indexed rate per route family. `--limit 1..50` (default 12), `--min-pages 1..500` (default 5). If the Site is archived or paused, this exits `4` or `5` rather than answering |
+| `search cohorts` | Not-indexed rate per route family. Returns `analysed: false` when the not-indexed list is a sample (`reason: sampled-index-state`). `--limit 1..50` (default 12), `--min-pages 1..500` (default 5). Paused Sites exit `4` or `5`. Removed Sites return `not_found` with exit `8` |
 | `sitemaps list` | Search Console sitemap snapshot: errors, warnings, URL counts, sync status |
 | `sitemaps urls` | Sitemap URL membership. `--generation-id`, `--feedpath`, `--cursor`, `--limit 1..1000` |
 | `sitemaps submit <sitemap-url>` | Mutation. Submits one sitemap through the Site's stored Search Console credential |
@@ -177,23 +188,33 @@ different numbers. Read the one that answers your question.
 | Field | What it counts |
 | --- | --- |
 | `total` | The number of rows the query matched, not clicks or impressions |
-| `totals` | Clicks, impressions, CTR and position for the full upstream query population. `totalsScope` says so in words. It may include rows outside this page. `null` when the server has no total |
+| `totals` | Upstream period totals from a separate read without grouping dimensions. These can include anonymized queries. Read `totalsScope`. `null` means unavailable |
 | `representedTotals` | Clicks and impressions for the rows in this response only, after local filtering. `representedTotalsScope` says so in words |
 
-So `representedTotals` is at or below `totals`, and raising `--limit` moves
-`representedTotals` while leaving `totals` still. Never sum `rows` by hand when
-`totals` is present.
+Raising `--limit` changes `representedTotals` while `totals` covers the full window.
+Grouped Page impressions can exceed whole-Site impressions when several Pages appear in one search.
+Do not assume `representedTotals` is at or below `totals`.
+Use `totals` for traffic totals, and `representedTotals` for the returned rows.
+Neither row filters nor pagination make `totals` a sum of the returned rows.
+
+Keyword lists omit `site:` and `inurl:` search operators after upstream paging.
+`total` and `page` still count upstream rows.
+Even `--all` can return fewer keyword rows than `total`.
 
-### Never compare a keyword total with a page total
+### Read keyword coverage separately
 
-Google suppresses query rows below a privacy threshold. So the `keywords` view
-sees a fraction of the traffic the `pages` view sees. On a typical property
-that is roughly half the impressions. Query-dimension totals are therefore
-always at or below page-dimension totals for the same Site and period. Never
-compare the two, and never report one as the Site total.
+Google suppresses query rows below a privacy threshold.
+Keyword rows therefore omit some traffic, even after `--all`.
+Their `representedTotals` measure only the returned keywords.
 
-Read the `pages` view for "how much traffic". Read the `keywords` view for
-"which terms are visible". A missing query row is never evidence of no demand.
+The engine can read dimensionless totals that include anonymized traffic.
+Then `keywords.totals` can equal `pages.totals` for the same Site and period.
+Do not assume `keywords.totals` is the sum of visible keyword rows.
+
+Read `timeseries.totals` for whole-Site traffic, `pages` rows for landing pages,
+and `keywords` rows for visible terms. Use `prevTotals` to compare Site traffic
+across periods.
+A missing query row is never evidence of no demand.
 
 ## Web Analytics
 
@@ -215,9 +236,9 @@ research boundary in SKILL.md first.
 | `research rankings <domain>` | Live domain rankings: current keywords and domain metrics. `--limit 1..100` (default 50), `--min-position 1..100` (default 1), `--max-position 1..100` (default 20), `--location-code` (default 2840), `--order position\|traffic` (default `position`). So a default run returns only the top 20 positions. If `--max-position` is under `--min-position`, the run exits `2`. An unusable domain also exits `2`, with `invalid_request`. An empty `data.keywords` with exit `0` carries the reason in `data.message`. `data.cached` reports cache use |
 | `research domain-traffic <domain>` | A live organic traffic estimate for any domain: trend, top pages, top countries. The domain does not have to be one of your Sites |
 | `research domain-availability <domains>` | Registration status. One comma-separated positional, up to 10 domains |
-| `backlinks summary` | Whole-domain inbound link totals for the Site's own domain: `backlinks`, `referringDomains`, `referringPages`, `brokenBacklinks`, `brokenPages`, `crawledPages`, `spamScore`, `rank`. Takes no flags; it always reads the registered Site URL, so use `research domain-traffic` for any other domain. Every count is nullable. A `null` count means the provider returned no value. Never read it as zero. `evidence` reports cache use. Needs a Site URL |
-| `backlinks referring-domains` | Domains that link to the Site. `--limit 1..1000` (default 100). `sessions` is 90-day referral traffic, or null when no Web Analytics property is linked. Needs a Site URL |
-| `backlinks anchors` | Anchor text distribution of inbound links. `--limit 1..1000` (default 100). Needs a Site URL |
+| `backlinks summary` | Whole-domain inbound link totals for the Site's own domain: `backlinks`, `referringDomains`, `referringPages`, `brokenBacklinks`, `brokenPages`, `crawledPages`, `spamScore`, `rank`. Takes no flags; it always reads the registered Site URL, so use `research domain-traffic` for any other domain. Every count is nullable. A `null` count means the provider returned no value. Never read it as zero. `linkSpamNetworks` groups referring domains that each place one generated anchor with the Site's host in it. Google ignores most links like these. `withoutLinkSpamNetworks` gives `referringDomains` and `backlinks` without them, or `null` when there is no network or no total. `evidence` reports cache use. Needs a Site URL |
+| `backlinks referring-domains` | Domains that link to the Site. `--limit 1..1000` (default 100). `sessions` is 90-day referral traffic, or null when no Web Analytics property is linked. `linkSpamNetworkId` names the link spam network of a known member domain; null means not known, never verified clean. Needs a Site URL |
+| `backlinks anchors` | Anchor text distribution of inbound links. `--limit 1..1000` (default 100). `linkSpamNetworkId` names the link spam network whose generated anchor the row is; null means not known, never verified clean. Needs a Site URL |
 | `backlinks history` | A monthly inbound link series. `--from YYYY-MM-DD`. Defaults to about twelve months. Needs a Site URL |
 | `backlinks recoverable` | Stored recoverable backlinks. `--limit 1..200`, `--offset`. Reads retained rows |
 | `mentions list` | Stored mentions. `--limit 1..200` (default 100), `--include-filtered` to keep the Mentions AI triage marked a false positive. Reads retained rows |
@@ -254,3 +275,21 @@ nuxtseo actions list --help --json
 
 Use it instead of guessing a flag. Prefer the tables above for anything they
 already answer.
+
+### Claim response
+
+`actions resolve` saves your Claim. It returns before a requested scan finishes starting.
+`status: "open"` stays unchanged until the engine verifies the Action.
+Human output shows `Claimed, verifying` and the suggested check-back time.
+Claimed Actions leave `actions list`. Use `actions show <action-id>` to check them.
+
+Both `resolve` and `show` return these additive fields:
+
+| Field | Meaning |
+| --- | --- |
+| `markedAt` | ISO timestamp when your Claim was saved, or `null` before a Claim. |
+| `checkBackAt` | Suggested ISO timestamp to check again, or `null` when no automated check applies. |
+
+A check-back time does not promise a completed check.
+`scan-queued` can mean a re-assessment using scheduled crawl results, without a new scan.
+A self-resolved Claim returns `status: "verified"` and `verification: "user-resolved"`.

package/skills/nuxtseo-cli/references/indexing.md

@@ -11,11 +11,17 @@ Start with the retained URL Inspection summary:
 nuxtseo search indexing summary --site <site-id> --json
 ```
 
-Report `data.totalUrls`, `data.indexed`, and `data.asOf`. These are exact for
-the retained URL Inspection evidence at that timestamp. They are not a live
-count of Google's whole index. State that boundary with the result. If
-`data.asOf` is null, say the retained snapshot time is unavailable. Never call
-that result current or live.
+Report `data.totalUrls`, `data.indexed`, `data.oldestCheckAt`, and
+`data.asOf`. These are exact for the retained URL Inspection evidence in that
+date range. `data.asOf` is when gscdump counted the verdicts, or the newest
+check (`data.asOfSource` names it: `capture`, `rollup`, or `newest-check`). The
+verdicts run back to `data.oldestCheckAt`, so quote both. When
+`data.verdictFreshness` is set, quote it too: a fresh count can rest on old
+verdicts, and `olderThan30dPercent` says how many. They are not a live
+count of Google's whole index. The retained set can be far smaller than the
+Search Console UI totals. State that boundary with the result. If `data.asOf`
+is null, say the evidence age is unknown. Never call that result current or
+live.
 
 Use the URL view when the user asks which URLs hold a verdict:
 
@@ -54,7 +60,7 @@ Keep these reads separate:
 
 | Question | Command | Report |
 | --- | --- | --- |
-| What is the indexed count for retained URLs? | `search indexing summary` | `totalUrls`, `indexed`, `asOf` |
+| What is the indexed count for retained URLs? | `search indexing summary` | `totalUrls`, `indexed`, `oldestCheckAt`, `asOf` |
 | Which retained URLs are indexed or not indexed? | `search indexing urls` | `total`, then the complete `urls` stream |
 | Which URLs appeared in the current period? | `search analytics pages` | Rows with `impressions > 0`, then each `url` |
 | What does Google say about one URL now? | `search inspect <url>` | The returned URL Inspection verdict |

package/skills/nuxtseo-cli/references/protocol.md

@@ -34,7 +34,7 @@ These fields carry the reason:
 | `research domain-traffic` | `data.message` |
 | `research domain-availability` | `data.message` |
 | `page issues` | `data.message`, plus `availableKeys` |
-| `search cohorts` | `data.message`, plus `reason` |
+| `search cohorts` | `data.message`, plus `reason` (`no-completed-crawl`, `no-inspection-join`, or `sampled-index-state`) |
 | `vitals findings` | `data.message`, plus `source` |
 
 `evidence._tag: "no-provider"` does not prove the data is absent. On `research