@nuxtseo/cli 0.5.3 → 0.5.5

package/README.md

@@ -206,6 +206,9 @@ nuxtseo sitemaps urls
 nuxtseo sitemaps submit <sitemap-url>
 nuxtseo sitemaps delete <sitemap-url>
 nuxtseo research overview
+nuxtseo research competitors list
+nuxtseo research competitors add <domain> --yes
+nuxtseo research competitors remove <competitor-id> --yes
 nuxtseo research domain-traffic <domain>
 nuxtseo research domain-availability <domains>
 nuxtseo research keywords <topic>
@@ -256,7 +259,9 @@ 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. `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.
+`search inspect <url>` reads the latest retained Google URL Inspection for one URL.
+`search inspect <url> --fresh --yes` requests Google URL Inspection through the Site connection and uses inspection quota.
+Fresh inspection reports errors and skipped URLs with a nonzero exit code. If the request needs more time, add `--timeout-ms 60000`.
 `page inspect <url>` reads the Nuxt SEO observation store for the same URL.
 `research keywords`, `research serp`, and `research rankings` can use the Team
 research limit. Keyword responses report cache use in `evidence`. SERP and

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, renderKeywordResearch, renderLinkOpportunities, renderLinkStructure, renderMentions, renderMonitoredPages, renderPageInspection, renderPageIssues, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderReferringDomains, renderResearchOverview, renderScanDetail, renderScans, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSitemapAction, renderSitemaps, renderSitemapUrls, renderSites, renderSiteStatus, renderTimeline, renderUrlInspection, renderUsage, } from './render.js';
+import { renderAccountToken, renderAction, renderActionDismissal, renderActionResolution, renderActions, renderAnalytics, renderAnnotation, renderAnnotationDeleted, renderAnnotations, renderAuditChanges, renderBacklinkAnchors, renderBacklinksHistory, renderBacklinksSummary, renderContentDecay, renderDomainAvailability, renderDomainTraffic, renderDuplicateClusters, renderFieldVitalFindings, renderFieldVitals, renderIndexCohorts, renderIndexingDiagnostics, renderIndexingHistory, renderKeywordResearch, renderLinkOpportunities, renderLinkStructure, renderMentions, renderMonitoredPages, renderPageInspection, renderPageIssues, renderPageScan, renderPerformance, renderRankingsResearch, renderRecoverableBacklinks, renderReferringDomains, renderResearchOverview, renderScanDetail, renderScans, renderSearchAnalytics, renderSearchStatus, renderSerpResearch, renderSitemapAction, renderSitemaps, 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';
@@ -717,13 +717,36 @@ async function searchIndexHistory(runtime, globals, args) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderIndexingHistory(value.data));
 }
-async function searchInspect(runtime, globals, rawUrl) {
+async function searchInspect(runtime, globals, rawUrl, fresh = false) {
     const url = parsePageUrlOrPath(rawUrl);
     if (url._tag === 'Err')
         return url;
+    if (fresh) {
+        const confirmed = await confirmMutation(runtime, globals, `Request a fresh URL Inspection for ${url.value}? This uses inspection quota.`);
+        if (confirmed._tag === 'Err')
+            return confirmed;
+        if (!confirmed.value)
+            return ok(undefined);
+    }
     const resolved = await apiAndSite(runtime, globals);
     if (resolved._tag === 'Err')
         return resolved;
+    if (fresh) {
+        const response = await withSpinner(runtime, 'Requesting URL Inspection', () => resolved.value.api.client.search.refreshUrlInspection({
+            params: { siteId: resolved.value.siteId },
+            body: { url: url.value },
+        }, { signal: runtime.requestSignal }));
+        if (response._tag === 'Err')
+            return fromSdkFailure(response.error);
+        if (response.value.data.errors.length || response.value.data.skipped.length || response.value.data.results.length !== 1) {
+            const incomplete = fail(EXIT_CODE.conflict, 'Fresh URL Inspection did not complete. Read the errors or skipped URLs in the response.');
+            if (globals.json)
+                return { _tag: 'Err', error: { ...incomplete.error, protocolResponse: response.value } };
+            writeOutput(runtime, renderUrlInspectionRefresh(response.value.data));
+            return incomplete;
+        }
+        return present(runtime, globals, response, value => renderUrlInspectionRefresh(value.data));
+    }
     const response = await withSpinner(runtime, 'Loading URL Inspection', () => resolved.value.api.client.search.readUrlInspection({
         params: { siteId: resolved.value.siteId },
         query: { url: url.value },
@@ -739,6 +762,40 @@ async function researchOverview(runtime, globals) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderResearchOverview(value.data));
 }
+async function competitorsList(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading competitors', () => resolved.value.api.client.research.listCompetitors({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => value.data.competitors.map(competitor => `${competitor.id}\t${competitor.domain}`).join('\n') || '0 tracked competitors');
+}
+async function competitorWrite(runtime, globals, action) {
+    const confirmed = await confirmMutation(runtime, globals, action._tag === 'Add'
+        ? `Track ${action.domain}? This uses the research limit.`
+        : `Remove competitor ${action.competitorId}? This cannot be undone.`);
+    if (confirmed._tag === 'Err')
+        return confirmed;
+    if (!confirmed.value) {
+        writeDiagnostic(runtime, 'Mutation cancelled.');
+        return ok(undefined);
+    }
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    if (action._tag === 'Add') {
+        const response = await withSpinner(runtime, 'Adding competitor', () => resolved.value.api.client.research.addCompetitor({
+            params: { siteId: resolved.value.siteId },
+            body: { domain: action.domain },
+        }, { signal: runtime.requestSignal }));
+        return present(runtime, globals, response, value => `${value.data.competitor.id}\t${value.data.competitor.domain}\tAnalysis queued`);
+    }
+    const response = await withSpinner(runtime, 'Removing competitor', () => resolved.value.api.client.research.removeCompetitor({
+        params: { siteId: resolved.value.siteId, competitorId: action.competitorId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => `Removed competitor ${value.data.competitorId}`);
+}
 /**
  * DataForSEO refuses these characters, so the research provider removes them
  * before it counts the words of a seed. Mirrored from
@@ -1810,6 +1867,25 @@ export function createRootCommand(runtime, globals, execution) {
     const research = defineCommand({
         meta: { name: 'research', description: 'Read stored and live search research' },
         subCommands: {
+            'competitors': defineCommand({
+                meta: { name: 'competitors', description: 'Manage tracked competitors for the Site' },
+                subCommands: {
+                    list: defineCommand({
+                        meta: { name: 'list', description: 'List tracked competitor domains and ids' },
+                        run: ({ args }) => capture(execution, () => competitorsList(runtime, globals), args._, 0)(),
+                    }),
+                    add: defineCommand({
+                        meta: { name: 'add', description: 'Track one competitor and queue its analysis' },
+                        args: { domain: positional('domain', 'Public competitor domain') },
+                        run: ({ args }) => capture(execution, () => competitorWrite(runtime, globals, { _tag: 'Add', domain: args.domain }), args._, 1)(),
+                    }),
+                    remove: defineCommand({
+                        meta: { name: 'remove', description: 'Remove one competitor using its listed id' },
+                        args: { competitorId: positional('competitorId', 'Competitor id from research competitors list') },
+                        run: ({ args }) => capture(execution, () => competitorWrite(runtime, globals, { _tag: 'Remove', competitorId: args.competitorId }), args._, 1)(),
+                    }),
+                },
+            }),
             'overview': defineCommand({
                 meta: { name: 'overview', description: 'Read stored Site metrics and competitor research' },
                 run: ({ args }) => capture(execution, () => researchOverview(runtime, globals), args._, 0)(),
@@ -2016,8 +2092,11 @@ export function createRootCommand(runtime, globals, execution) {
             }),
             'inspect': defineCommand({
                 meta: { name: 'inspect', description: 'Read the latest URL Inspection result for one URL' },
-                args: { url: positional('url', 'Page URL or path') },
-                run: ({ args }) => capture(execution, () => searchInspect(runtime, globals, args.url), args._, 1)(),
+                args: {
+                    url: positional('url', 'Page URL or path'),
+                    fresh: { type: 'boolean', description: 'Request Google URL Inspection using inspection quota', default: false },
+                },
+                run: ({ args }) => capture(execution, () => searchInspect(runtime, globals, args.url, args.fresh), args._, 1)(),
             }),
         },
     });

package/dist/pull.js

@@ -319,22 +319,25 @@ export async function runPull(runtime, globals, args, resolve, catalogue = PULL_
         });
         const outcome = pullLine(candidate.name, result);
         writeProtocolResponse(runtime, outcome.line);
-        if (!explainedAnalyticsConnection
-            && candidate.name.startsWith('analytics ')
+        const analyticsUnconnected = candidate.name.startsWith('analytics ')
             && result._tag === 'Err'
             && result.error._tag === 'ApiFailure'
             && result.error.code === 'conflict'
-            && result.error.details?.action === 'connect_web_analytics') {
+            && result.error.details?.action === 'connect_web_analytics';
+        if (!explainedAnalyticsConnection && analyticsUnconnected) {
             explainedAnalyticsConnection = true;
             writeDiagnostic(runtime, 'Web Analytics is not connected. Connect a property to read these views. For a full SEO pull, use --exclude analytics.');
         }
-        exitCodes.push(outcome.exitCode);
+        // Default pulls include optional integrations. An explicit include asks
+        // for those reads, so their missing connection still fails that request.
+        const optionalUnavailable = analyticsUnconnected && !args.include;
+        exitCodes.push(optionalUnavailable ? EXIT_CODE.success : outcome.exitCode);
         completed++;
         // An expired or rejected credential fails every later read the same way.
         // Stopping there saves the requests and keeps the reason on one line.
         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'}`);
+        writeDiagnostic(runtime, `[${completed}/${operations.length}] ${candidate.name} ${optionalUnavailable ? 'unavailable' : 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.

package/dist/render.d.ts

@@ -4,7 +4,7 @@ import type { ActionDismiss, ActionList, ActionResolve, ActionShow } from '@nuxt
 import type { AnalyticsQueryData, AnalyticsView } 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, SearchAnalyticsData, SearchStatusData, UrlInspectionData } from '@nuxtseo/protocol/v1/gsc';
+import type { IndexCohorts, IndexingDiagnosticsData, IndexingHistoryData, SearchAnalyticsData, SearchStatusData, UrlInspectionData, UrlInspectionRefreshData } 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';
 import type { DomainAvailability, DomainTraffic, KeywordResearchData, RankingsResearchData, SerpResearchData, StoredResearchOverview } from '@nuxtseo/protocol/v1/research';
@@ -21,6 +21,7 @@ export declare function renderPerformance(data: SitePerformanceOverview): string
 export declare function renderSearchStatus(data: SearchStatusData): string;
 export declare function renderSearchAnalytics(data: SearchAnalyticsData): string;
 export declare function renderIndexingHistory(data: IndexingHistoryData): string;
+export declare function renderUrlInspectionRefresh(data: UrlInspectionRefreshData): string;
 export declare function renderUrlInspection(data: UrlInspectionData): string;
 export declare function renderAuditChanges(data: AuditChanges): string;
 export declare function renderLinkStructure(data: AuditLinkStructure): string;

package/dist/render.js

@@ -232,6 +232,25 @@ export function renderIndexingHistory(data) {
         }),
     ].join('\n');
 }
+export function renderUrlInspectionRefresh(data) {
+    return [
+        `URL Inspection request completed at ${data.checkedAt}.`,
+        ...data.results.map(result => fields([
+            ['URL', result.url],
+            ['Verdict', result.verdict],
+            ['Coverage', result.coverageState],
+            ['Indexing', result.indexingState],
+            ['robots.txt', result.robotsTxtState],
+            ['Page fetch', result.pageFetchState],
+            ['User canonical', result.userCanonical],
+            ['Google canonical', result.googleCanonical],
+            ['Last crawl', result.lastCrawlTime],
+        ])),
+        ...data.errors.map(result => `Inspection failed for ${result.url}: ${result.error}`),
+        ...data.skipped.map(result => `Inspection skipped for ${result.url}: ${result.reason}`),
+        `Inspection quota remaining: ${data.rateLimit.remaining} of ${data.rateLimit.limit}.`,
+    ].join('\n');
+}
 export function renderUrlInspection(data) {
     if (data._tag === 'no-inspection-data')
         return `No retained URL Inspection for ${data.requestedUrl}.`;
@@ -465,9 +484,19 @@ export function renderResearchOverview(data) {
     return [subject, `Competitors: ${data.summary.competitorCount}`, competitors].join('\n');
 }
 export function renderKeywordResearch(data) {
+    const measured = data.topicMetrics.filter(row => row._tag === 'measured').length;
+    const topics = data.topicMetrics.length
+        ? [
+            `Requested topics (${measured}/${data.topicMetrics.length} measured)`,
+            ...data.topicMetrics.map(row => row._tag === 'measured'
+                ? `${row.metrics.volume ?? 'unknown'} volume  ${row.metrics.difficulty ?? 'unknown'} difficulty  ${row.metrics.intent ?? 'unknown intent'}\n  ${row.topic}`
+                : `No data returned\n  ${row.topic}`),
+        ]
+        : [];
     if (data.keywords.length === 0)
-        return data.message ?? `No keyword ideas found for ${data.topic}.`;
+        return [...topics, data.message ?? `No keyword ideas found for ${data.topic}.`, ...(data.tip ? [`Tip: ${data.tip}`] : [])].join('\n');
     return [
+        ...topics,
         `Keyword ideas for ${data.topic} (${data.keywords.length} of ${data.totalFound})${data.evidence._tag === 'cache' ? '  cached' : ''}`,
         ...data.keywords.map(row => `${row.volume ?? 'unknown'} volume  ${row.difficulty ?? 'unknown'} difficulty  ${row.intent ?? 'unknown intent'}\n  ${row.keyword}`),
         ...(data.tip ? [`Tip: ${data.tip}`] : []),
@@ -604,7 +633,7 @@ export function renderFieldVitals(data) {
             ['As of', summary.asOf],
             ...['lcp', 'inp', 'cls'].map(metric => [
                 metric.toUpperCase(),
-                `${vitalValue(metric, summary[metric].p75)}  ${summary[metric].status ?? 'unrated'}  delta ${summary[metric].deltaOverPeriod ?? 'none'}`,
+                `${vitalValue(metric, summary[metric].p75)}  ${summary[metric].status ?? 'unrated'}  delta ${summary[metric].deltaOverPeriod ?? 'none'}  As of ${summary[metric].asOf ?? 'unknown'}`,
             ]),
         ]),
     ].join('\n');
@@ -896,7 +925,7 @@ export function renderScanDetail(data) {
     if (data.observedTrace?._tag === 'available') {
         const trace = data.observedTrace;
         blocks.push([
-            `Observed trace LCP  ${trace.observedLcpMs}ms  throttling ${trace.throttlingMethod}`,
+            `Observed trace LCP  ${trace.observedLcpMs}ms  throttling ${trace.throttlingMethod ?? 'not reported'}`,
             ...trace.phases.map(phase => `  ${phase.id}  ${phase.durationMs}ms`),
             'Trace phases describe observed LCP. Reported LCP can be simulated.',
         ].join('\n'));

package/package.json

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

package/skills/nuxtseo-cli/SKILL.md

@@ -64,6 +64,7 @@ Read the matching file before you act on its subject:
    | `page scan` | `page:write` |
    | `actions resolve`, `actions dismiss` | `actions:write` |
    | `annotations` writes | `timeline:write` |
+   | `research competitors add`, `research competitors remove` | `research:write` |
    | `sitemaps submit`, `sitemaps delete` | `sites:write` |
 
    If a write scope is missing, do the reads, then hand the user the exact
@@ -277,7 +278,10 @@ Do not compare this population with a summary or cohort from another capture.
 - `status` is the verdict, `performance` the lab score, `vitals` what real
   users measured. Never substitute one for another.
 - `page inspect` reads the Nuxt SEO observation store. `search inspect` reads
-  Google's index verdict for the same URL.
+  the latest retained Google URL Inspection for the same URL.
+  `search inspect <url> --fresh --yes` requests Google URL Inspection through
+  the Site connection and uses inspection quota. Errors or skipped URLs mean
+  the fresh inspection did not complete. Never present them as fresh verdicts.
 - `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.

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

@@ -141,6 +141,7 @@ lines.
 `scans show` can include `observedTrace` from the retained Lighthouse projection.
 If its tag is `available`, its phases describe `observedLcpMs` from the browser trace.
 `throttlingMethod` names how Lighthouse computed the reported metrics.
+If it is `null`, the provider omitted the method. Do not infer a method from the timings.
 With `simulate`, reported `lcp` is modeled. Observed trace phases do not partition that modeled value.
 With `devtools` or `provided`, Lighthouse uses observed metrics.
 Neither value is real-user field data.
@@ -194,7 +195,7 @@ The monitored Page then follows its own recurring schedule.
 | `search analytics <view>` | Search Console rows, trend, detail, or analysis. Views: `pages`, `keywords`, `countries`, `devices`, `timeseries`, `page-detail`, `keyword-detail`, `analysis`. `--period 7d\|28d\|3m\|6m\|12m` (default `28d`). No other period value is accepted; `90d` exits `2`, and `3m` is the three-month window. `--limit 1..100` (default 25), `--page` (default 1), `--search`, `--sort clicks\|impressions\|ctr\|position` (default `clicks`), `--sort-dir asc\|desc` (default `desc`), `--filter top-level\|new\|lost\|improving\|declining`, `--min-clicks`, `--max-clicks`, `--min-impressions`, `--max-impressions`, `--min-position 1..100`, `--max-position 1..100`, `--max-ctr 0..1`. The `page-detail` view needs `--page-url`, `keyword-detail` needs `--keyword`, and `analysis` needs `--preset`. The brand presets also need `--brand-terms` |
 | `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 inspect <url>` | Latest retained Google URL Inspection for one URL. Takes an absolute URL or a site-relative path. `--fresh --yes` requests Google URL Inspection through the Site connection and uses inspection quota. Errors or skipped URLs produce a nonzero exit code |
 | `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` |
@@ -251,12 +252,16 @@ A missing query row is never evidence of no demand.
 ## Research, backlinks, and mentions
 
 Every command here can start live research, except `research overview`,
+`research competitors list`, `research competitors remove`,
 `backlinks recoverable` and `mentions list`, which read retained rows. Read the
 research boundary in SKILL.md first.
 
 | Command | What it returns, and its flags |
 | --- | --- |
 | `research overview` | Stored Site and competitor research: metrics, history, gaps, quick wins. Takes no flags. Returns `data.competitors` and `data.summary` |
+| `research competitors list` | Tracked competitor domains and ids for this Site. Suggested competitors stay excluded. Reads start no provider work. |
+| `research competitors add <domain>` | Mutation, requires `research:write` and `--yes`. Accepts a public domain or URL. Queues analysis within existing Site and Team limits. Returns `data.competitor.id` and `data.status: queued`. |
+| `research competitors remove <competitor-id>` | Mutation, requires `research:write` and `--yes`. Use an id from the list. Removes that Site's competitor without provider work. |
 | `research keywords <topic>` | Live keyword ideas, with volume, difficulty, intent, and cost data. The seed must be 1 to 3 words. The server refuses a longer seed. The refusal arrives as exit `0` with an empty `data.keywords`, so read `data.message` first. Comma-separate several short seeds instead. Special characters are stripped before the lookup. If a seed is under 2 characters after stripping, the server refuses it the same way. The server applies default filters and echoes them in `data.filters`: `--min-volume` (default 10), `--max-volume` (default 10000), `--min-difficulty 0..100` (default 0), `--max-difficulty 0..100` (default 60). So a default run hides keywords over difficulty 60 or under 10 searches. Also `--limit 1..100` (default 20), `--intent`, `--location-code` (default 2840), `--no-related` to drop related keywords, and `--verbose` for full evidence. If `--max-volume` is under `--min-volume`, the run exits `2`. The same holds for `--max-difficulty` under `--min-difficulty` |
 | `research serp <keyword>` | A live SERP snapshot: results, features, fetch time. `--depth 1..20` (default 10) sets how many organic results return. `--location-code` (default 2840). The keyword must be 2 to 200 characters. `data.cached` reports cache use |
 | `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 |
@@ -269,6 +274,13 @@ research boundary in SKILL.md first.
 | `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 |
 
+Keyword research returns `data.topicMetrics` for every accepted comma-separated topic.
+Read it separately from filtered `data.keywords`, which contains keyword ideas.
+A `measured` row preserves exact metrics, including zero volume and values outside idea filters.
+A `no-data` row means the provider returned no exact metrics. It does not mean zero volume.
+If any topic becomes shorter than two characters after sanitization, the server refuses the whole request.
+Cached reads preserve all topic metrics without another provider call.
+
 ## Crawl audit
 
 | Command | What it returns, and its flags |

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

@@ -63,5 +63,6 @@ Keep these reads separate:
 | 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 |
+| What did Google say at the last inspection? | `search inspect <url>` | The retained verdict and inspection date |
+| What does Google say about one URL now? | `search inspect <url>` | Add `--fresh --yes`. Report fresh results, quota, and explicit errors or skipped URLs |
 | Which URLs did the Site submit? | `sitemaps list`, then `sitemaps urls` | Sitemap totals and membership |