@nuxtseo/cli 0.5.7 → 0.5.9

package/dist/cli.js

@@ -376,7 +376,7 @@ async function interactiveBare(runtime, globals) {
         message: 'Account and setup',
         options: [
             { value: 'site', label: 'Switch Site', hint: config.value.siteId ?? 'none selected' },
-            { value: 'usage', label: 'Account usage' },
+            { value: 'usage', label: 'Team usage' },
             { value: 'whoami', label: 'Credential and scopes' },
             { value: 'config', label: 'Configuration' },
             { value: 'logout', label: 'Log out' },

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, renderUrlInspectionRefresh, 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, 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';
@@ -1010,6 +1010,54 @@ async function sitemapsList(runtime, globals) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderSitemaps(value.data));
 }
+async function sitemapsSubmission(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Sitemap submission', () => resolved.value.api.client.sitemaps.readSubmission({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderSitemapSubmission(value.data));
+}
+async function searchWatches(runtime, globals) {
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Loading Watched URLs', () => resolved.value.api.client.search.listWatches({
+        params: { siteId: resolved.value.siteId },
+    }, { signal: runtime.requestSignal }));
+    return present(runtime, globals, response, value => renderIndexingWatches(value.data));
+}
+async function sitemapsInspect(runtime, globals, rawUrl, engine) {
+    const url = parseAbsolutePageUrl(rawUrl);
+    if (url._tag === 'Err')
+        return url;
+    const resolved = await apiAndSite(runtime, globals);
+    if (resolved._tag === 'Err')
+        return resolved;
+    const response = await withSpinner(runtime, 'Reading Sitemap evidence', () => resolved.value.api.client.sitemaps.inspect({
+        params: { siteId: resolved.value.siteId },
+        query: { url: url.value, searchEngine: engine },
+    }, { signal: runtime.requestSignal }));
+    if (response._tag === 'Err')
+        return fromSdkFailure(response.error);
+    if (response.value.data.state._tag === 'unavailable') {
+        const { reason } = response.value.data.state;
+        const exitCode = reason === 'throttled' || reason === 'provider-unavailable'
+            ? EXIT_CODE.retryable
+            : reason === 'grant-missing' || reason === 'reauthorization-required'
+                ? EXIT_CODE.authentication
+                : reason === 'permission-lost' || reason === 'not-enabled'
+                    ? EXIT_CODE.authorization
+                    : EXIT_CODE.conflict;
+        const incomplete = fail(exitCode, `Sitemap evidence is unavailable: ${reason}.`);
+        if (globals.json)
+            return { _tag: 'Err', error: { ...incomplete.error, protocolResponse: response.value } };
+        writeOutput(runtime, renderSitemapEvidence(response.value.data));
+        return incomplete;
+    }
+    return present(runtime, globals, response, value => renderSitemapEvidence(value.data));
+}
 async function sitemapsUrls(runtime, globals, args) {
     const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 1000, defaultValue: 500 });
     if (limit._tag === 'Err')
@@ -1326,11 +1374,10 @@ async function actionDismiss(runtime, globals, args) {
         return fail(EXIT_CODE.invalidInput, 'Pass the action id to dismiss.', undefined, 'invalid_cli_input');
     if (!args.artifactVersion)
         return fail(EXIT_CODE.invalidInput, 'Pass --artifact-version, the artifactVersion returned with this action.', undefined, 'invalid_cli_input');
-    if (args.note !== undefined && (!args.note.trim() || args.note.trim().length > 2000))
-        return fail(EXIT_CODE.invalidInput, 'Pass --note with 1 to 2000 characters.', undefined, 'invalid_cli_input');
-    const confirmed = await confirmMutation(runtime, globals, args.note
-        ? `Dismiss action ${args.actionId}? Your note records this decision. No fix is verified.`
-        : `Dismiss action ${args.actionId}? The page stays removed.`);
+    const note = args.note?.trim();
+    if (!note || note.length > 2000)
+        return fail(EXIT_CODE.invalidInput, 'Pass --note with 1 to 2000 characters that say why this action is intentional or incorrect.', undefined, 'invalid_cli_input');
+    const confirmed = await confirmMutation(runtime, globals, `Dismiss action ${args.actionId}? Your note records this decision. No fix is verified.`);
     if (confirmed._tag === 'Err')
         return confirmed;
     if (!confirmed.value) {
@@ -1342,7 +1389,7 @@ async function actionDismiss(runtime, globals, args) {
         return resolved;
     const response = await withSpinner(runtime, 'Dismissing action', () => resolved.value.api.client.actions.dismiss({
         params: { siteId: resolved.value.siteId, actionId: args.actionId },
-        body: { artifactVersion: args.artifactVersion, ...(args.note !== undefined ? { note: args.note.trim() } : {}) },
+        body: { artifactVersion: args.artifactVersion, note },
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderActionDismissal(value.data));
 }
@@ -1666,11 +1713,11 @@ export function createRootCommand(runtime, globals, execution) {
                 run: ({ args }) => capture(execution, () => actionsResolve(runtime, globals, args.actionId), args._, 1)(),
             }),
             dismiss: defineCommand({
-                meta: { name: 'dismiss', description: 'Dismiss reviewed work with a note, or confirm an unlinked page removal' },
+                meta: { name: 'dismiss', description: 'Dismiss reviewed work with a note that says why' },
                 args: {
                     'actionId': positional('action-id', 'Action ID'),
                     'artifact-version': { type: 'string', description: 'The artifactVersion returned with this action' },
-                    'note': { type: 'string', description: 'Why this action is intentional or incorrect, 1 to 2000 characters' },
+                    'note': { type: 'string', description: 'Required. Why this action is intentional or incorrect, 1 to 2000 characters' },
                 },
                 run: ({ args }) => capture(execution, () => actionDismiss(runtime, globals, {
                     actionId: args.actionId,
@@ -2042,6 +2089,10 @@ export function createRootCommand(runtime, globals, execution) {
     const search = defineCommand({
         meta: { name: 'search', description: 'Read Search Console state' },
         subCommands: {
+            'watches': defineCommand({
+                meta: { name: 'watches', description: 'Read Watched URLs and retained Checkpoints' },
+                run: ({ args }) => capture(execution, () => searchWatches(runtime, globals), args._, 0)(),
+            }),
             'status': defineCommand({
                 meta: { name: 'status', description: 'Read the stored Search Console connection' },
                 run: ({ args }) => capture(execution, () => searchStatus(runtime, globals), args._, 0)(),
@@ -2149,6 +2200,18 @@ export function createRootCommand(runtime, globals, execution) {
     const sitemaps = defineCommand({
         meta: { name: 'sitemaps', description: 'Read and manage Search Console sitemaps' },
         subCommands: {
+            submission: defineCommand({
+                meta: { name: 'submission', description: 'Read site-level Google Sitemap submission readiness' },
+                run: ({ args }) => capture(execution, () => sitemapsSubmission(runtime, globals), args._, 0)(),
+            }),
+            inspect: defineCommand({
+                meta: { name: 'inspect', description: 'Read exact Sitemap listing evidence' },
+                args: {
+                    url: positional('sitemap-url', 'Absolute Sitemap URL'),
+                    engine: { type: 'enum', options: ['google', 'bing'], default: 'google', description: 'Google live or Bing stored evidence' },
+                },
+                run: ({ args }) => capture(execution, () => sitemapsInspect(runtime, globals, args.url, args.engine), args._, 1)(),
+            }),
             list: defineCommand({
                 meta: { name: 'list', description: 'List the sitemaps Search Console knows' },
                 run: ({ args }) => capture(execution, () => sitemapsList(runtime, globals), args._, 0)(),
@@ -2305,7 +2368,7 @@ export function createRootCommand(runtime, globals, execution) {
                 },
             }),
             usage: defineCommand({
-                meta: { name: 'usage', description: 'Read account usage' },
+                meta: { name: 'usage', description: 'Read Team usage' },
                 args: {
                     group: {
                         type: 'enum',

package/dist/render.d.ts

@@ -4,11 +4,11 @@ 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, UrlInspectionRefreshData } from '@nuxtseo/protocol/v1/gsc';
+import type { IndexCohorts, IndexingDiagnosticsData, IndexingHistoryData, IndexingWatchesData, 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';
-import type { SiteSitemapActionResponse, SiteSitemapsResponse, SiteSitemapUrlsResponse } from '@nuxtseo/protocol/v1/sitemaps';
+import type { SiteSitemapActionResponse, SiteSitemapEvidenceData, SiteSitemapsResponse, SiteSitemapSubmissionData, SiteSitemapUrlsResponse } from '@nuxtseo/protocol/v1/sitemaps';
 import type { Annotation, AnnotationDeleted, Annotations, TimelineEntries } from '@nuxtseo/protocol/v1/timeline';
 export declare function renderSites(response: SitesListResponse, selectedSiteId?: string): string;
 export declare function renderUsage(response: AccountUsageResponse): string;
@@ -25,6 +25,9 @@ export declare function renderUrlInspectionRefresh(data: UrlInspectionRefreshDat
 export declare function renderUrlInspection(data: UrlInspectionData): string;
 export declare function renderAuditChanges(data: AuditChanges): string;
 export declare function renderLinkStructure(data: AuditLinkStructure): string;
+export declare function renderSitemapSubmission(data: SiteSitemapSubmissionData): string;
+export declare function renderSitemapEvidence(data: SiteSitemapEvidenceData): string;
+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;

package/dist/render.js

@@ -106,20 +106,56 @@ export function renderPageScan(data) {
         ...data.scans.map(scan => `${scan.strategy}: ${scan.scanId}`),
     ].join('\n');
 }
+/** A lab duration in milliseconds. Null is unmeasured, never zero. */
+function labMs(value) {
+    return value === null ? 'not measured' : `${value}ms`;
+}
+function labScanLine(label, scan) {
+    if (!scan?.completedAt)
+        return `${label}  no complete Scan`;
+    return `${label}  perf ${scan.perf ?? 'none'}  LCP ${labMs(scan.lcp)}  TBT ${labMs(scan.tbt)}  CLS ${scan.cls ?? 'not measured'}  scanned ${scan.completedAt}`;
+}
 export function renderPerformance(data) {
-    if (!data.health)
+    const blocks = [];
+    if (data.health) {
+        blocks.push([
+            'Mobile medians across monitored Pages',
+            fields([
+                ['Scanned pages', data.health.scannedPageCount],
+                ['Last scan', data.health.lastScanAt],
+                ['Performance median', data.health.perf.median],
+                ['Performance worst', data.health.perf.worst],
+                ['Accessibility median', data.health.a11y.median],
+                ['SEO median', data.health.seo.median],
+                ['LCP median', data.health.lcp.median],
+                ['TBT median', data.health.tbt.median],
+                ['CLS median', data.health.cls.median],
+            ]),
+        ].join('\n'));
+    }
+    if (data.homepage || data.homepageDesktop) {
+        blocks.push([
+            'Homepage',
+            labScanLine('  mobile ', data.homepage),
+            labScanLine('  desktop', data.homepageDesktop),
+        ].join('\n'));
+    }
+    if (data.routes.length || data.routesDesktop.length) {
+        const desktopByPage = new Map(data.routesDesktop.map(route => [route.pageId, route]));
+        const mobileByPage = new Map(data.routes.map(route => [route.pageId, route]));
+        const pages = [...data.routes, ...data.routesDesktop.filter(route => !mobileByPage.has(route.pageId))];
+        blocks.push([
+            `Monitored Pages (${pages.length})`,
+            ...pages.flatMap(page => [
+                `  ${page.path}`,
+                labScanLine('    mobile ', mobileByPage.get(page.pageId)),
+                labScanLine('    desktop', desktopByPage.get(page.pageId)),
+            ]),
+        ].join('\n'));
+    }
+    if (!blocks.length)
         return `No stored performance overview. Monitored routes: ${data.routes.length}.`;
-    return fields([
-        ['Scanned pages', data.health.scannedPageCount],
-        ['Last scan', data.health.lastScanAt],
-        ['Performance median', data.health.perf.median],
-        ['Performance worst', data.health.perf.worst],
-        ['Accessibility median', data.health.a11y.median],
-        ['SEO median', data.health.seo.median],
-        ['LCP median', data.health.lcp.median],
-        ['TBT median', data.health.tbt.median],
-        ['CLS median', data.health.cls.median],
-    ]);
+    return blocks.join('\n\n');
 }
 export function renderSearchStatus(data) {
     if (data._tag === 'Connected')
@@ -348,6 +384,23 @@ export function renderLinkStructure(data) {
         ];
     return [header, ...slots, ...deadEnds, ...anchors].join('\n');
 }
+export function renderSitemapSubmission(data) {
+    return `Google Sitemap submission: ${data.state._tag}\n${JSON.stringify(data.state, null, 2)}\nCan act: ${data.callerCanAct}`;
+}
+export function renderSitemapEvidence(data) {
+    return [
+        `${data.searchEngine} Sitemap: ${data.sitemapUrl}`,
+        `State: ${data.state._tag}`,
+        data.capture._tag === 'captured' ? `Capture: ${data.capture.source} at ${data.capture.capturedAt}` : 'Capture: unavailable',
+        JSON.stringify(data.state, null, 2),
+    ].join('\n');
+}
+export function renderIndexingWatches(data) {
+    return [
+        `Watched URLs: ${data.watched.length}/${data.limit}. Cadence: ${data.cadenceDays} days.`,
+        ...data.watched.map(watch => `${watch.url}\n  Due: ${watch.dueAt}\n  Checkpoints: ${JSON.stringify(watch.checkpoints)}`),
+    ].join('\n');
+}
 export function renderSitemaps(data) {
     if (data.sitemaps.length === 0)
         return `No sitemaps are known for ${data.meta.siteUrl}.`;
@@ -652,8 +705,9 @@ export function renderFieldVitalFindings(data) {
     if (data.findings.length === 0)
         return data.message ?? 'No failing field vitals attributed to an element.';
     const shown = `${data.offset + 1}-${data.offset + data.findings.length} of ${data.total}`;
+    const window = data.window ? `, ${data.window.from} to ${data.window.to}` : '';
     return [
-        `Field vital findings (${shown}, source ${data.source ?? 'unknown'})`,
+        `Field vital findings (${shown}, source ${data.source ?? 'unknown'}${window})`,
         ...data.findings.map(finding => [
             `${finding.metric.toUpperCase()}  ${finding.severity}  ${vitalValue(finding.metric, finding.p75)}  ${finding.route}`,
             `  selector ${finding.selector}`,
@@ -881,6 +935,12 @@ export function renderPageIssues(data) {
         ].filter(Boolean).join('\n')),
     ].join('\n') + truncated;
 }
+/** A failed Scan names its kind and message. Other states carry no failure row. */
+function scanFailureRows(scan) {
+    if (scan.status !== 'failed')
+        return [];
+    return [['failure', `${scan.failureKind ?? 'unknown kind'}: ${scan.error ?? 'no message recorded'}`]];
+}
 export function renderScans(data) {
     if (data.scans.length === 0)
         return 'No Lighthouse Scans retained for this Site.';
@@ -890,6 +950,9 @@ export function renderScans(data) {
             `${scan.completedAt ?? 'pending'}  ${scan.strategy}  ${scan.status}  ${scan.url}`,
             `  ${fields([
                 ['id', scan.id],
+                ['trigger', scan.trigger],
+                ['lighthouse', scan.lighthouseVersion],
+                ...scanFailureRows(scan),
                 ['performance', scan.scores.perf],
                 ['accessibility', scan.scores.a11y],
                 ['best practices', scan.scores.bestPractices],
@@ -897,11 +960,20 @@ export function renderScans(data) {
                 ['lcp', scan.lcp],
                 ['tbt', scan.tbt],
                 ['cls', scan.cls],
-                ['error', scan.error],
             ]).split('\n').join('\n  ')}`,
         ].join('\n')),
     ].join('\n');
 }
+function renderScanComparison(comparison) {
+    if (!comparison || comparison._tag === 'none')
+        return 'Previous Scan  none compared';
+    if (comparison._tag === 'incompatible')
+        return `Previous Scan  ${comparison.previousScanId ?? 'unknown'} not comparable: ${comparison.reasons.join(', ')}`;
+    return [
+        `Since previous Scan ${comparison.previousScanId ?? 'unknown'}  ${comparison.severity}`,
+        ...comparison.changes.map(change => `  ${change.metric}  ${change.previous} to ${change.current}  ${change.delta > 0 ? '+' : ''}${change.delta}  ${change.severity}`),
+    ].join('\n');
+}
 export function renderMonitoredPages(data) {
     if (data.pages.length === 0)
         return 'No monitored Pages. Start one with `nuxtseo page scan <url>`.';
@@ -917,6 +989,9 @@ export function renderScanDetail(data) {
             ['URL', data.url],
             ['Strategy', data.strategy],
             ['Status', data.status],
+            ...scanFailureRows(data).map(([, failure]) => ['Failure', failure]),
+            ['Trigger', data.trigger],
+            ['Lighthouse', data.lighthouseVersion],
             ['Completed', data.completedAt],
             ['Performance', data.scores.perf],
             ['Accessibility', data.scores.a11y],
@@ -930,6 +1005,8 @@ export function renderScanDetail(data) {
             ['TTFB', data.ttfb],
         ]),
     ];
+    if (data.status === 'complete')
+        blocks.push(renderScanComparison(data.comparison));
     if (data.lcpElement)
         blocks.push(`LCP element  ${data.lcpElement.selector ?? data.lcpElement.nodeLabel ?? 'unknown'}`);
     if (data.observedTrace?._tag === 'available') {
@@ -951,13 +1028,15 @@ export function renderScanDetail(data) {
     if (waste.length) {
         blocks.push([
             `Wasteful assets (${waste.length})`,
-            ...waste.map(issue => `  ${issue.wastedMs ?? 0}ms  ${issue.wastedBytes ?? 0}b  ${issue.subtype ?? issue.type}  ${issue.url ?? ''}`.trimEnd()),
+            ...waste.map(issue => `  ${issue.wastedMs === null ? 'time not measured' : `${issue.wastedMs}ms`}  ${issue.wastedBytes === null ? 'bytes not measured' : `${issue.wastedBytes}b`}  ${issue.subtype ?? issue.type}  ${issue.url ?? ''}`.trimEnd()),
         ].join('\n'));
     }
     if (data.thirdParties.length) {
+        // A null blocking time is unmeasured. Printing it as 0ms read as "this
+        // script never blocks".
         blocks.push([
             `Third parties (${data.thirdParties.length})`,
-            ...data.thirdParties.map(script => `  ${script.blockingTime ?? 0}ms blocking  ${script.entity ?? 'unknown'}`),
+            ...data.thirdParties.map(script => `  ${script.blockingTime === null ? 'blocking not measured' : `${script.blockingTime}ms blocking`}  ${script.entity ?? 'unknown'}`),
         ].join('\n'));
     }
     for (const [label, checks] of [['Accessibility failures', data.accessibility], ['Best-practices failures', data.bestPractices]]) {

package/package.json

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

package/skills/nuxtseo-cli/SKILL.md

@@ -17,7 +17,7 @@ Read the matching file before you act on its subject:
 | --- | --- |
 | [references/commands.md](references/commands.md) | use a flag, range, or default. Never guess a flag |
 | [references/protocol.md](references/protocol.md) | parse output, page through a list, or handle an exit code |
-| [references/indexing.md](references/indexing.md) | report an indexed count or name indexed URLs |
+| [references/indexing.md](references/indexing.md) | interpret indexing, Sitemap evidence, or Watched URLs |
 
 ## Setup
 
@@ -211,21 +211,21 @@ The server verifies the claim; the CLI never marks anything fixed. Resolve
 sends the current `artifactVersion` for you. If the evidence moved, it exits
 `5` with `stale_evidence`: re-run step 3 and decide again.
 
-If the fix is a deliberate removal, dismiss instead. Read `artifactVersion`
-from `actions show`, then:
+If the owner confirms an action is intentional or incorrect, dismiss it. Read
+`artifactVersion` from `actions show`, then record the reason:
 
 ```sh
-nuxtseo actions dismiss <action-id> --site <site-id> --artifact-version <v> --yes --json
+nuxtseo actions dismiss <action-id> --site <site-id> --artifact-version <v> --note "<reason>" --yes --json
 ```
 
-Without a note, the server admits a dismiss only for a broken-page action with
-complete 404 or 410 evidence and no internal referrers.
+The note is required. Review the exact scope first. A note dismisses the whole
+action, so never use it to hide a mix of intentional and broken URLs. Dismissal
+keeps the observations and does not verify a fix. The dashboard can restore the
+action later.
 
-If the owner confirms an action is intentional or incorrect, record that
-decision with `--note "<reason>"`. Review the exact scope first. A note dismisses
-the whole action, so never use it to hide a mix of intentional and broken URLs.
-Dismissal keeps the observations and does not verify a fix. The dashboard can
-restore the action later.
+A 404 or 410 is a gone URL. An action names one only when a link, a sitemap
+entry, or search demand still points at it, or when the crawl cannot confirm
+the removal.
 
 **7. Mark the day.**
 
@@ -264,6 +264,10 @@ and do not route around it with `pull` or another read.
 `coverage.bestPracticesChecksTotal` from `scans show`. `possiblyTruncated:
 true` marks the list as a floor.
 
+**A failed Scan has no scores.** `status: failed` with `failureKind` says why.
+Its null scores and vitals are not zeros. A null `blockingTime` or `wastedMs`
+is unmeasured, never zero.
+
 For `search indexing urls`, read `totalSemantics` before quoting `total`.
 `lower-bound` means the provider used lookahead instead of counting every URL.
 The total can rise between pages without a filter change. Follow `hasMore` or

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

@@ -124,7 +124,7 @@ lines.
 | `actions list` | Server-ranked issues and opportunities. `--limit 1..25` (default 10), `--offset`. Each row carries `evidence.freshness`; `verdict: "aged"` means the observation is over a day old, so live-check before fixing |
 | `actions show <action-id>` | One issue or opportunity, plus its evidence. `--limit 1..100` (default 50), `--group-id`, `--cursor` |
 | `actions resolve <action-id>` | Mutation. Claims the issue or opportunity and starts server verification. Reads the action first and sends `artifactVersion` for you |
-| `actions dismiss <action-id>` | Mutation. Needs `--artifact-version`, read from `actions show`. `--note` records why the owner considers the action intentional or incorrect. Without a note, complete unlinked 404 or 410 evidence is required. Dismissal preserves observations and never verifies a fix |
+| `actions dismiss <action-id>` | Mutation. Needs `--artifact-version`, read from `actions show`, and `--note`, which records why the owner considers the action intentional or incorrect. Dismissal preserves observations and never verifies a fix |
 
 ## Pages, Scans, and lab performance
 
@@ -133,11 +133,24 @@ lines.
 | `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. Paused Sites exit `4` or `5`. Removed Sites return `not_found` with exit `8` |
 | `page scan <url>` | Mutation. Adds or re-enables the URL as a monitored Page, then starts mobile and desktop Scans |
-| `performance` | Stored Lighthouse lab overview for the Site: medians for perf, a11y, SEO, LCP, TBT, CLS. Lab Scans, never real-user field data |
-| `scans list` | Retained Lighthouse Scans, newest first, with scores, lab vitals, and the error on a failed Scan. `--limit 1..100` (default 25) |
-| `scans show <scan-id>` | One Scan, and the evidence behind its scores: wasteful assets, repeat-visit cache policy, third-party scripts, the LCP element, and every failing accessibility and best-practices check with its CSS selectors and DOM snippets. Read `coverage` before quoting a total |
+| `performance` | Stored Lighthouse lab overview for the Site: mobile medians for perf, a11y, SEO, LCP, TBT, CLS, then the homepage and each monitored Page on mobile and desktop. Lab Scans, never real-user field data |
+| `scans list` | Retained Lighthouse Scans, newest first, with scores, lab vitals, `trigger`, and `lighthouseVersion`. A failed Scan carries `failureKind` and `error`, and its scores are null. `--limit 1..100` (default 25) |
+| `scans show <scan-id>` | One Scan, and the evidence behind its scores: wasteful assets, repeat-visit cache policy, third-party scripts, the LCP element, and every failing accessibility and best-practices check with its CSS selectors and DOM snippets. Also `trigger`, `lighthouseVersion`, and `comparison` with the previous Scan of the same Page. Read `coverage` before quoting a total |
 | `scans pages` | The Pages this Site scans on a schedule. Add one with `page scan <url>` |
 
+`scans list` and `scans show` return the same Scan shape as the `lighthouse_audits` MCP tool.
+`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.
+
+`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.
+`none` means no previous Scan was compared. The homepage slot always reads `none`.
+A lab `regression` compares one Lighthouse result per Scan. Lab scores vary by a few points between Scans.
+
+A null `blockingTime` or `wastedMs` is unmeasured. It is never zero.
+If a Scan could not measure blocking time for a third party, text output prints "blocking not measured".
+
 `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.
@@ -185,7 +198,7 @@ The monitored Page then follows its own recurring schedule.
 | --- | --- |
 | `vitals summary` | Field Core Web Vitals from CrUX: the latest p75, plus its change over the window. `--url` for one Page, `--form-factor phone\|desktop\|all`. `available: false` means the target is under the CrUX traffic floor |
 | `vitals trend` | A 25-week field p75 series. Same inputs as `vitals summary` |
-| `vitals findings` | Failing field vitals attributed to a DOM element. `--metric lcp\|inp\|cls`, `--limit 1..50` (default 20), `--offset`, `--no-only-failing`. Each finding carries the CSS selector and a ready-to-apply `fixPrompt`. Needs a connected Web Analytics provider |
+| `vitals findings` | Failing field vitals attributed to a DOM element. `--metric lcp\|inp\|cls`, `--limit 1..50` (default 20), `--offset`, `--no-only-failing`. Each finding carries the CSS selector, `poorFraction`, `labHint`, and a ready-to-apply `fixPrompt`. An LCP finding adds `resource`, `fetchPriority`, `initiatorType`, and `phases`. An INP finding adds `interaction`. `window` gives the dates the provider aggregated. Needs a connected Web Analytics provider |
 
 ## Search Console and sitemaps
 
@@ -198,6 +211,9 @@ The monitored Page then follows its own recurring schedule.
 | `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 submission` | Site-level Google Sitemap submission state. Redacts account identity. Does not prove listing for an arbitrary Sitemap URL |
+| `sitemaps inspect <sitemap-url>` | Exact Sitemap listing evidence. `--engine google\|bing` defaults to `google`. Google reads live. Bing reads dated stored data. Missing exits `0`; unavailable exits `3`, `4`, `5`, or `6` |
+| `search watches` | Retained Watched URLs, `dueAt`, and Checkpoints. An empty Checkpoint list means no retained Checkpoint for that watch |
 | `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. Success means Search Console accepted it, not that Google downloaded it. Read `lastDownloaded` and `isPending` in `sitemaps list` |
 | `sitemaps delete <sitemap-url>` | Mutation. Removes one sitemap through the Site's stored Search Console credential |

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

@@ -65,4 +65,19 @@ Keep these reads separate:
 | Which URLs appeared in the current period? | `search analytics pages` | Rows with `impressions > 0`, then each `url` |
 | 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 |
+| Which URLs belong to the Sitemap generation? | `sitemaps list`, then `sitemaps urls` | Sitemap totals and retained membership |
+| Does a provider list this exact Sitemap URL? | `sitemaps inspect <sitemap-url>` | `state`, `capture.source`, and `capture.capturedAt` |
+| Can the Site submit its selected Google Sitemap? | `sitemaps submission` | Site-level `state` and `callerCanAct` |
+| What checks exist for Watched URLs? | `search watches` | Each URL's `dueAt` and retained Checkpoints |
+
+`sitemaps inspect` uses `--engine google` by default. Use `--engine bing` for Bing's stored evidence.
+Google reads live. Bing reports its stored capture time; it does not make a live provider request.
+`state._tag: missing` proves absence only within that successful dated read.
+`state._tag: unavailable` provides no listing conclusion and produces a nonzero exit.
+Grant or reauthorization failures exit `3`. Permission loss or disabled access exits `4`.
+Unverified or unchecked evidence exits `5`. Throttling or provider failure exits `6`.
+The JSON response preserves the evidence with these failures.
+
+Watched URL due times describe scheduling. They do not prove that checks can run.
+An empty Checkpoint list means no retained Checkpoint for that watch.
+Neither Sitemap listing nor Watched URL enrollment proves that Google indexed a Page.

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

@@ -135,6 +135,9 @@ command returns; never guess a chain. Verified against the response schemas.
 | `search index-history` | `data.changes` | none |
 | `search cohorts` | `data.established` and `data.ranked` | `data.rankedTotal` |
 | `sitemaps list` | `data.sitemaps` | none |
+| `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 |
 | `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` |