@nuxtseo/cli 0.4.0 → 0.5.0

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')

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/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,19 +58,23 @@ 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],
             ['As of', data.asOf],
         ]),
-        `Evidence groups: ${data.evidenceGroups.length}`,
+        data.workPrompt ?? `Evidence groups: ${data.evidenceGroups.length}`,
     ].join('\n');
 }
 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');
@@ -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.0",
+  "version": "0.5.0",
   "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.0",
-    "@nuxtseo/sdk": "^0.4.0",
+    "@nuxtseo/protocol": "^0.5.0",
+    "@nuxtseo/sdk": "^0.5.0",
     "citty": "^0.2.2",
     "pathe": "^2.0.3"
   },

package/skills/nuxtseo-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nuxtseo-cli
-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.
+description: Required before you interpret any `nuxtseo` CLI output, exit code, or error, including pasted output, because several fields read like findings and are not. Drives the `nuxtseo` CLI for Site status, ranked actions, Search Console and indexing, Core Web Vitals, Lighthouse Scans, research, and backlinks. Use whenever the user mentions NuxtSEO, the `nuxtseo` command, or Nuxt SEO work.
 ---
 
 # `nuxtseo` CLI
@@ -31,10 +31,10 @@ Read the matching file before you act on its subject:
    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
+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,6 +107,11 @@ 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.
 - Read `dataQuality.status` before you quote the verdict. `degraded` means
   proofs were missing, so the verdict is Provisional. `unavailable` means it
   has not run.
@@ -135,8 +140,9 @@ Site may have changed since the observation.
 nuxtseo actions show <action-id> --site <site-id> --json
 ```
 
-It names the pages, the finding type, and when it was observed. Two reads go
-deeper:
+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:
 
 - `page issues --action-id <action-id>`: the raw observations, with URLs,
   status codes, redirect targets, and Lighthouse selectors. This is the
@@ -189,7 +195,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 |
 
@@ -199,9 +205,10 @@ 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", and do not
-retry unchanged.
+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
@@ -221,15 +228,25 @@ true` marks the list as a floor.
 - `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).
+- 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` 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.

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

@@ -120,7 +120,7 @@ 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 |
@@ -131,7 +131,7 @@ lines.
 | 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 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. Starts a mobile Scan and a desktop Scan |
 | `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) |
@@ -158,7 +158,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 |
@@ -215,9 +215,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 +254,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