@nuxtseo/cli 0.5.9 → 0.5.11

package/README.md

@@ -195,6 +195,8 @@ nuxtseo annotations create
 nuxtseo annotations update <annotation-id>
 nuxtseo annotations delete <annotation-id>
 nuxtseo analytics <view>
+nuxtseo bot-traffic --crawler googlebot
+nuxtseo bot-traffic --crawler bingbot
 nuxtseo search status
 nuxtseo search analytics <view>
 nuxtseo search indexing <summary|urls>
@@ -343,9 +345,9 @@ 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.
+`actions resolve` saves your Claim. It returns before verification completes.
 `status: "open"` stays unchanged until the engine verifies the Action.
-Human output shows `Claimed, verifying` and the suggested check-back time.
+Human output shows `Claimed, verifying`.
 Claimed Actions leave `actions list`. Use `actions show <action-id>` to check them.
 
 Both `resolve` and `show` return these additive fields:
@@ -353,8 +355,12 @@ 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.
+| `checkBackAt` | Supported ISO timestamp to check again, or `null` when the schedule is unknown. |
+
+`recheck-queued` requests a fresh check of the cited URLs.
+`scan-queued` means a source refresh is queued or already running.
+`next-assessment` waits for a site check, which can reuse stored results.
+An assessment can already be queued without requesting fresh Crawl collection.
+Unknown check times stay null, including retries and later reads.
+A supported check-back time does not promise completed verification.
 A self-resolved Claim returns `status: "verified"` and `verification: "user-resolved"`.

package/dist/commands.js

@@ -9,7 +9,7 @@ import { EXIT_CODE, fail, fromSdkFailure, ok } from './failures.js';
 import { awaitPairingApproval, createCliPairingClient, startPairing } from './pairing.js';
 import { parseAbsolutePageUrl, parseChoice, parseInteger, parsePageUrlOrPath, parseRatio } from './parse.js';
 import { PULL_PERIODS, runPull } from './pull.js';
-import { renderAccountToken, renderAction, renderActionDismissal, renderActionResolution, renderActions, renderAnalytics, renderAnnotation, renderAnnotationDeleted, renderAnnotations, renderAuditChanges, renderBacklinkAnchors, renderBacklinksHistory, renderBacklinksSummary, renderContentDecay, renderDomainAvailability, renderDomainTraffic, renderDuplicateClusters, renderFieldVitalFindings, renderFieldVitals, renderIndexCohorts, renderIndexingDiagnostics, renderIndexingHistory, renderIndexingWatches, renderKeywordResearch, renderLinkOpportunities, renderLinkStructure, renderMentions, renderMonitoredPages, renderPageInspection, renderPageIssues, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderReferringDomains, renderResearchOverview, renderScanDetail, renderScans, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSitemapAction, renderSitemapEvidence, renderSitemaps, renderSitemapSubmission, renderSitemapUrls, renderSites, renderSiteStatus, renderTimeline, renderUrlInspection, renderUrlInspectionRefresh, renderUsage, } from './render.js';
+import { renderAccountToken, renderAction, renderActionDismissal, renderActionResolution, renderActions, renderAnalytics, renderAnnotation, renderAnnotationDeleted, renderAnnotations, renderAuditChanges, renderBacklinkAnchors, renderBacklinksHistory, renderBacklinksSummary, renderBotTraffic, renderContentDecay, renderDomainAvailability, renderDomainTraffic, renderDuplicateClusters, renderFieldVitalFindings, renderFieldVitals, renderIndexCohorts, renderIndexingDiagnostics, renderIndexingHistory, renderIndexingWatches, renderKeywordResearch, renderLinkOpportunities, renderLinkStructure, renderMentions, renderMonitoredPages, renderPageInspection, renderPageIssues, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderReferringDomains, renderResearchOverview, renderScanDetail, renderScans, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSitemapAction, renderSitemapEvidence, renderSitemaps, renderSitemapSubmission, renderSitemapUrls, renderSites, renderSiteStatus, renderTimeline, renderUrlInspection, renderUrlInspectionRefresh, renderUsage, } from './render.js';
 import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { resolveSite } from './site.js';
 import { installSkill, SKILL_AGENTS } from './skill.js';
@@ -1360,6 +1360,22 @@ async function backlinksHistory(runtime, globals, args) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderBacklinksHistory(value.data));
 }
+async function googlebotActivity(runtime, globals, args) {
+    const days = parseInteger(args.days, { name: '--days', minimum: 1, maximum: 90, defaultValue: 28 });
+    if (days._tag === 'Err')
+        return days;
+    const crawler = parseChoice(args.crawler, { name: '--crawler', choices: ['googlebot', 'bingbot'], defaultValue: 'googlebot' });
+    if (crawler._tag === 'Err')
+        return crawler;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Bot Traffic', () => resolved.value.api.client.analytics.botActivity({
+        params: { siteId: resolved.value.siteId },
+        query: { days: days.value, crawler: crawler.value },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderBotTraffic(value.data));
+}
 async function siteStatus(runtime, globals) {
     const resolved = await apiAndSite(runtime, globals);
     if (resolved._tag === 'Err')
@@ -2319,7 +2335,7 @@ export function createRootCommand(runtime, globals, execution) {
             'yes': { type: 'boolean', alias: 'y', description: 'Confirm a mutation without prompting' },
         },
         subCommands: {
-            login: defineCommand({
+            'login': defineCommand({
                 meta: { name: 'login', description: 'Approve this machine in a browser and store the Team API token it mints' },
                 args: {
                     'with-token': { type: 'boolean', description: 'Paste an existing Team API token instead of pairing' },
@@ -2332,20 +2348,20 @@ export function createRootCommand(runtime, globals, execution) {
                     noBrowser: args.browser === false,
                 }), args._, 0)(),
             }),
-            logout: defineCommand({
+            'logout': defineCommand({
                 meta: { name: 'logout', description: 'Remove the local credential' },
                 run: ({ args }) => capture(execution, () => logout(runtime, globals), args._, 0)(),
             }),
-            whoami: defineCommand({
+            'whoami': defineCommand({
                 meta: { name: 'whoami', description: 'Validate and describe the active credential' },
                 run: ({ args }) => capture(execution, () => whoami(runtime, globals), args._, 0)(),
             }),
-            config: defineCommand({
+            'config': defineCommand({
                 meta: { name: 'config', description: 'Show or edit local configuration' },
                 run: ({ args }) => capture(execution, () => config(runtime, globals), args._, 0)(),
             }),
             sites,
-            feedback: defineCommand({
+            'feedback': defineCommand({
                 meta: { name: 'feedback', description: 'Report CLI problems to Nuxt SEO' },
                 subCommands: {
                     submit: defineCommand({
@@ -2367,7 +2383,7 @@ export function createRootCommand(runtime, globals, execution) {
                     }),
                 },
             }),
-            usage: defineCommand({
+            'usage': defineCommand({
                 meta: { name: 'usage', description: 'Read Team usage' },
                 args: {
                     group: {
@@ -2383,22 +2399,27 @@ export function createRootCommand(runtime, globals, execution) {
             backlinks,
             mentions,
             page,
-            performance: defineCommand({
+            'performance': defineCommand({
                 meta: { name: 'performance', description: 'Read the stored Site performance overview' },
                 run: ({ args }) => capture(execution, () => performance(runtime, globals), args._, 0)(),
             }),
             annotations,
+            'bot-traffic': defineCommand({
+                meta: { name: 'bot-traffic', description: 'Read verified search engine requests from the Site\'s Cloudflare zone' },
+                args: { days: { type: 'string', description: 'UTC days to read, 1 to 90, today included' }, crawler: { type: 'string', description: 'googlebot or bingbot', default: 'googlebot' } },
+                run: ({ args }) => capture(execution, () => googlebotActivity(runtime, globals, { days: args.days, crawler: args.crawler }), args._, 0)(),
+            }),
             pull,
             research,
             scans,
             search,
             sitemaps,
-            status: defineCommand({
+            'status': defineCommand({
                 meta: { name: 'status', description: 'Read the Site assessment and the one thing to do next' },
                 run: ({ args }) => capture(execution, () => siteStatus(runtime, globals), args._, 0)(),
             }),
             vitals,
-            analytics: defineCommand({
+            'analytics': defineCommand({
                 meta: { name: 'analytics', description: 'Read Web Analytics for the selected Site' },
                 args: {
                     'view': positional('view', ANALYTICS_VIEWS.join(', ')),

package/dist/render.d.ts

@@ -1,7 +1,7 @@
 import type { AccountUsageResponse, SitesListResponse, SiteStatus } from '@nuxtseo/protocol/v1';
 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 { AnalyticsQueryData, AnalyticsView, BotActivity } from '@nuxtseo/protocol/v1/analytics';
 import type { AuditChanges, AuditContentDecay, AuditDuplicateClusters, AuditLinkOpportunities, AuditLinkStructure } from '@nuxtseo/protocol/v1/audit';
 import type { BacklinkAnchorsData, BacklinksHistory, BacklinksSummaryData, MentionsData, RecoverableBacklinksData, ReferringDomainsData } from '@nuxtseo/protocol/v1/backlinks';
 import type { IndexCohorts, IndexingDiagnosticsData, IndexingHistoryData, IndexingWatchesData, SearchAnalyticsData, SearchStatusData, UrlInspectionData, UrlInspectionRefreshData } from '@nuxtseo/protocol/v1/gsc';
@@ -31,10 +31,7 @@ export declare function renderIndexingWatches(data: IndexingWatchesData): string
 export declare function renderSitemaps(data: SiteSitemapsResponse['data']): string;
 export declare function renderSitemapUrls(data: SiteSitemapUrlsResponse['data']): string;
 export declare function renderSitemapAction(data: SiteSitemapActionResponse['data']): string;
-/**
- * Web Analytics rows differ per view and share no discriminant field, so the
- * requested view selects the projection instead of the payload.
- */
+export declare function renderBotTraffic(data: BotActivity): string;
 export declare function renderAnalytics(view: AnalyticsView, data: AnalyticsQueryData): string;
 export declare function renderAccountToken(data: AccountTokenData): string;
 export declare function renderIndexingDiagnostics(data: IndexingDiagnosticsData): string;

package/dist/render.js

@@ -433,6 +433,48 @@ export function renderSitemapAction(data) {
  * Web Analytics rows differ per view and share no discriminant field, so the
  * requested view selects the projection instead of the payload.
  */
+function percent(share) {
+    return share === null ? 'none' : `${(share * 100).toFixed(1)}%`;
+}
+function googlebotAccessLines(access) {
+    if (access._tag === 'zone_access_missing') {
+        return [
+            `Collection stopped: ${access.message}`,
+            `Grant: ${access.permissions.join(', ')} (OAuth: ${access.oauthScopes.join(', ')})`,
+        ];
+    }
+    if (access._tag === 'collection_failed')
+        return [`Collection stopped (${access.reason}): ${access.message}`];
+    return [];
+}
+export function renderBotTraffic(data) {
+    const access = googlebotAccessLines(data.access);
+    const crawler = data.crawler === 'googlebot' ? 'Googlebot' : 'Bingbot';
+    if (data.collection === null)
+        return [...access, `No ${crawler} requests collected yet. Collection runs with the Site's Cloudflare sync.`].join('\n');
+    const { totals } = data;
+    const statusLine = (statuses) => `2xx ${statuses['2xx']}  304 ${statuses['304']}  3xx ${statuses.other3xx}  404 ${statuses['404']}  410 ${statuses['410']}  4xx ${statuses.other4xx}  429 ${statuses['429']}  5xx ${statuses['5xx']}`;
+    const first = data.days[0]?.day;
+    const last = data.days.at(-1)?.day;
+    return [
+        ...access,
+        `Bot Traffic, ${crawler}${first && last ? `, ${first} to ${last}` : ''}`,
+        fields([
+            ['Collected', `${data.collection.fromDay} to ${data.collection.toDay}`],
+            ['Complete through', data.collection.completeThroughDay ?? ''],
+            ['Requests', totals.requests],
+            ['Statuses', statusLine(totals.statuses)],
+            ['Content', `html ${totals.contents.html}  js ${totals.contents.js}  css ${totals.contents.css}  image ${totals.contents.image}  other ${totals.contents.other}`],
+            ['Wasted share', percent(totals.wastedShare)],
+            ['Cache hit share', percent(totals.cacheHitShare)],
+            ['Origin avg', totals.originAvgMs === null ? '' : `${totals.originAvgMs} ms`],
+        ]),
+        data.days.length === 0 ? 'No collected days in this window.' : 'Days',
+        ...data.days.map(day => `  ${day.day}${day.complete ? '' : ' (partial)'}  ${day.requests} requests  ${statusLine(day.statuses)}`),
+        data.errorPaths.length === 0 ? '' : 'Error paths',
+        ...data.errorPaths.map(path => `  ${path.status}  ${path.requests}  ${path.path}  last ${path.lastDay}`),
+    ].filter(Boolean).join('\n');
+}
 export function renderAnalytics(view, data) {
     const delta = (label, value) => [
         label,
@@ -979,7 +1021,9 @@ export function renderMonitoredPages(data) {
         return 'No monitored Pages. Start one with `nuxtseo page scan <url>`.';
     return [
         `Monitored Pages (${data.pages.length})`,
-        ...data.pages.map(page => `  ${page.enabled ? 'on ' : 'off'}  ${page.path}  last scan ${page.lastScanAt ?? 'never'}`),
+        ...data.pages.map(page => page.pauseReason
+            ? `  paused  ${page.path}  ${page.pauseReason}  last scan ${page.lastScanAt ?? 'never'}`
+            : `  ${page.enabled ? 'on    ' : 'off   '}  ${page.path}  last scan ${page.lastScanAt ?? 'never'}`),
     ].join('\n');
 }
 export function renderScanDetail(data) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "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.5.9",
-    "@nuxtseo/sdk": "^0.5.9",
+    "@nuxtseo/protocol": "^0.5.11",
+    "@nuxtseo/sdk": "^0.5.11",
     "citty": "^0.2.2",
     "pathe": "^2.0.3"
   },

package/skills/nuxtseo-cli/SKILL.md

@@ -51,8 +51,16 @@ Read the matching file before you act on its subject:
    instead.
 
 3. **Token.** Run `nuxtseo whoami --json`. It returns the Team, role, scopes,
-   and token expiry. Exit `3` means no working token. Ask the user to run
-   `nuxtseo login` themselves, because a person must approve it in a browser.
+   and token expiry. Exit `3` means no working token.
+   If authentication is missing, invalid, or expired, run `nuxtseo login --no-browser`.
+   A missing referenced keychain credential can instead exit `7` with `state_error`; use the same login flow.
+   If browser automation is authorized, open the printed URL in the intended signed-in account.
+   Verify the account, Team, machine, and matching pairing code before approving.
+   Select the least access needed. Editor supports Scans and Action claims.
+   Keep the login process running until it saves the credential, then repeat `whoami --json`.
+   Honor browser connection approval. Never copy cookies or bypass sign-in.
+   If browser access or approval is unavailable, ask the user to approve the printed URL.
+   If login reports a transport failure, investigate it before starting another pairing.
    The other route is a token from
    <https://nuxtseo.com/pro/dashboard/settings/api-tokens>, exported as
    `NUXTSEO_TOKEN`. Never put a token in an argument, a file, or a commit.
@@ -246,6 +254,7 @@ you got:
 | `page issues` | `availableKeys` |
 | `search cohorts` | `analysed: false`: no completed crawl, no Google index state, or `reason: "sampled-index-state"` |
 | `vitals summary` | `available: false` |
+| `bot-traffic` | `collection: null`; `access._tag` other than `collecting` |
 | `research keywords`, `research rankings`, `research domain-*`, `page issues`, `search cohorts`, `vitals findings` | `data.message`, and `data.tip` for the repair |
 
 Read `data.message` before the list. For example, `research keywords` refuses
@@ -283,6 +292,9 @@ Do not compare this population with a summary or cohort from another capture.
   is normal.
 - `status` is the verdict, `performance` the lab score, `vitals` what real
   users measured. Never substitute one for another.
+- `bot-traffic --crawler googlebot` or `--crawler bingbot` counts verified search engine requests at the Site's Cloudflare edge. It is
+  not Search Console's Crawl Stats report, so its totals can differ. A high
+  `wastedShare` during a planned URL retirement is expected.
 - `page inspect` reads the Nuxt SEO observation store. `search inspect` reads
   the latest retained Google URL Inspection for the same URL.
   `search inspect <url> --fresh --yes` requests Google URL Inspection through

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

@@ -62,6 +62,7 @@ a research unit.
 | Which route family is Google declining | `search cohorts` |
 | Why is this one URL not indexed | `search inspect <url>` |
 | When did this URL change index state | `search index-history`, with `--url` |
+| Which URLs answer search engines with errors | `bot-traffic` with the Googlebot or Bingbot crawler filter |
 | Which pages earn the clicks | `search analytics pages` |
 | Which terms is the Site visible for | `search analytics keywords` |
 | Which pages are losing clicks | `audit content-decay` |
@@ -108,7 +109,7 @@ lines.
 | --- | --- |
 | `whoami` | Credential, Team, role, granted scopes, token expiry. The cheapest health check. Reads no Site |
 | `feedback submit` | Submit sanitized agent feedback. Requires `--command` (1..200 characters), `--comment` (1..2000), `--agent` (1..100), and `--yes`. Optional `--intent bug\|improvement` (default `bug`) and `--request-id` (1..128). Adds the CLI version. Needs no Site. Returns the feedback ID and status |
-| `login` | Pairs the CLI with a Team through the browser. A person must approve the pairing, so ask the user to run it. `--with-token` reads a token from a hidden prompt or stdin. `--no-browser` skips opening the browser |
+| `login` | Pairs the CLI with a Team through the browser. An authorized agent can run `--no-browser` and approve through the intended signed-in account. Verify the account, Team, machine, and matching code first. If approval is unavailable, ask the user to approve the printed URL. `--with-token` reads a token from a hidden prompt or stdin. `--no-browser` skips opening the browser |
 | `logout` | Discards the stored credential. Returns a `CliLogout` value |
 | `sites list` | Every accessible Site. The source of Site IDs |
 | `sites use <site-id>` | Persists a default Site in local config, for the human, not for you |
@@ -142,6 +143,12 @@ lines.
 `failureKind` says why a Scan failed, for example `timeout`, `rejected`, or `quota`.
 It is null on a Scan that did not fail, and on a Scan that failed before kinds were recorded.
 
+Reuse saved successful Scan details. Read only the details needed for the missing proof.
+For persistent Poor metrics, start with the latest two completed Scans per canonical Page and strategy.
+Read older details only when the comparison needs them. Missing details mean incomplete coverage, never healthy performance.
+If the server reports a retry delay, respect it across the work queue.
+If throttling repeats, stop parallel reads and preserve the failures for a later paced retry.
+
 `comparison` has one of three tags.
 `compared` lists each metric both Scans measured, with `previous`, `current`, `delta`, and `severity`.
 `incompatible` names why the two Scans differ, for example `lighthouse-version`. Do not compare their numbers.
@@ -263,6 +270,7 @@ A missing query row is never evidence of no demand.
 
 | Command | What it returns, and its flags |
 | --- | --- |
+| `bot-traffic` | Bot Traffic counts verified Googlebot or Bingbot requests per UTC day at the Site's Cloudflare zone. `--crawler googlebot\|bingbot` defaults to Googlebot. Statuses split into `2xx`, `304`, `other3xx`, `404`, `410`, `other4xx`, `429`, `5xx`; content into `html`, `js`, `css`, `image`, `other`. `totals.wastedShare` counts every answer except 2xx and 304. `errorPaths` lists the most requested 4xx, 429 and 5xx paths, without 410. `--days 1..90` (default 28), today included. `days` lists only collected days, and a `complete: false` day is partial. `collection: null` means no collection ran yet. Read `access` first: `zone_access_missing` lists the Cloudflare permissions (`Zone: Read`, `Analytics: Read`) and OAuth scopes to grant. `collection_failed` names the reason. Stored days stop at the last collection. A Site without a Cloudflare zone returns `conflict`. These edge counts can differ from Search Console's Crawl Stats report. Source: `packages/protocol/src/v1/analytics.ts`, `packages/cli/src/commands.ts` |
 | `analytics <view>` | Web Analytics from the connected provider. Views: `performance`, `top-pages`, `source-medium`, `key-events`, `countries`, `devices`, `dimension`. `--period` is a free string, for example `28d` (default `28d`); an empty value exits `2`. `--compare previous\|year\|none` (default `previous`), `--dimension` (required for the `dimension` view; one of `date`, `page`, `hostname`, `source`, `medium`, `campaign`, `country`, `region`, `city`, `deviceCategory`, `browser`, `operatingSystem`), `--filters` as a JSON array, `--phase current\|prior\|full` (default `full`), `--no-stable-data` to include unstable recent days, `--no-host-scope` to include every host, `--no-compare-prior` to skip the prior window, `--fresh` to bypass the server cache |
 
 ## Research, backlinks, and mentions
@@ -332,9 +340,9 @@ already answer.
 
 ### Claim response
 
-`actions resolve` saves your Claim. It returns before a requested scan finishes starting.
+`actions resolve` saves your Claim. It returns before verification completes.
 `status: "open"` stays unchanged until the engine verifies the Action.
-Human output shows `Claimed, verifying` and the suggested check-back time.
+Human output shows `Claimed, verifying`.
 Claimed Actions leave `actions list`. Use `actions show <action-id>` to check them.
 
 Both `resolve` and `show` return these additive fields:
@@ -342,8 +350,12 @@ 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.
+| `checkBackAt` | Supported ISO timestamp to check again, or `null` when the schedule is unknown. |
+
+`recheck-queued` requests a fresh check of the cited URLs.
+`scan-queued` means a source refresh is queued or already running.
+`next-assessment` waits for a site check, which can reuse stored results.
+An assessment can already be queued without requesting fresh Crawl collection.
+Unknown check times stay null, including retries and later reads.
+A supported check-back time does not promise completed verification.
 A self-resolved Claim returns `status: "verified"` and `verification: "user-resolved"`.

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

@@ -18,6 +18,22 @@ Protocol failure, still on stdout, with recovery details on stderr:
 
 Read `data`. The CLI does not unwrap, rename, rank, or enrich fields.
 
+## Provisional Site verdicts
+
+If `status` returns degraded data quality, read `dataQuality.reason` with `unavailableProofs`.
+The reason records the unavailable stage. It does not identify the underlying database or network fault.
+
+| Reason | Recorded outcome |
+| --- | --- |
+| `completed-crawl-unavailable` | The loader found no completed Crawl evidence with a completion clock. |
+| `crawl-read-failed` | The collection read failed. |
+| `crawl-snapshot-unavailable` | Generation could not reread Findings for the pinned Crawl. |
+| `crawl-snapshot-read-failed` | The pinned Findings read failed. |
+
+A null reason can mean an older assessment or another missing proof.
+It never clears the missing proof or proves zero blockers.
+A completed Crawl elsewhere does not identify which stage failed for this assessment.
+
 ## A soft failure looks like an empty result
 
 Some commands refuse the argument and still exit `0` with an empty list. The
@@ -138,6 +154,7 @@ command returns; never guess a chain. Verified against the response schemas.
 | `sitemaps submission` | no list; `data.state` | none |
 | `sitemaps inspect` | no list; `data.capture`, `data.state` | none |
 | `search watches` | `data.watched`; each item's `checkpoints` | none |
+| `bot-traffic` | `data.days` and `data.errorPaths` | none |
 | `sitemaps urls` | `data.items` | `data.page.nextCursor`, `data.page.limit` |
 | `audit content-decay` | `data.rows` | `data.page`; `data.total`, `data.truncated` |
 | `audit link-opportunities` | `data.rows` | `data.page`; `data.total` |
@@ -167,7 +184,7 @@ Branch on the exit code, not message text.
 | ---: | --- | --- |
 | `0` | Success, including a closed stdout pipe | Continue |
 | `2` | Invalid input, or mutation without `--yes` | Fix arguments. Do not retry unchanged |
-| `3` | Missing, invalid, or expired authentication | Ask the user for a token |
+| `3` | Missing, invalid, or expired authentication | Run `nuxtseo login --no-browser`. Follow Setup's authorized browser pairing flow, then repeat `whoami --json` |
 | `4` | Forbidden, scope, or entitlement failure | Report the plan or token blocker |
 | `5` | Conflict, stale evidence, or ambiguous Site | Re-read. Pass `--site` if ambiguous |
 | `6` | Rate limit, `quota_exhausted`, provider outage, or timeout | Read retry metadata, then wait |
@@ -182,5 +199,10 @@ may also include the retry delay, the rate policy, the requests remaining, the
 rate limit, the window, the reset delay, and structured details. Keep the
 request ID when reporting a problem.
 
+If its retry wait reaches the request deadline, the CLI preserves the last verified API failure.
+That preserves the server code, request ID, and retry metadata.
+Respect the reported retry delay before starting more calls.
+Network-only timeouts still return `request_timeout`. Explicit cancellation returns exit `130`.
+
 Only exit `6` means the same command may work later. The SDK already retried
 HTTP 429 responses. Mutations are never retried automatically.