@nuxtseo/cli 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
-# NuxtSEO CLI
+# `nuxtseo` CLI
 
-Use NuxtSEO public Site operations from a terminal, script, or coding agent.
+Use Nuxt SEO public Site operations from a terminal, script, or coding agent.
 The CLI sends feature requests through `@nuxtseo/sdk`. It does not call MCP or
 private routes. Live research uses declared public API operations.
 
@@ -81,7 +81,7 @@ When keychain support is unavailable, it warns on stderr and uses
 scope before the request that needs it.
 
 `nuxtseo logout` removes the local credential. Revoke the token from the
-NuxtSEO dashboard when it must stop working everywhere. An environment token
+Nuxt SEO dashboard when it must stop working everywhere. An environment token
 always wins and is unchanged by login or logout.
 
 API host resolution order is:
@@ -216,9 +216,6 @@ nuxtseo audit link-opportunities
 nuxtseo audit link-structure
 nuxtseo audit content-decay
 nuxtseo audit duplicates
-nuxtseo content briefs list
-nuxtseo content briefs show <brief-id>
-nuxtseo content briefs create <keyword>
 nuxtseo timeline list
 nuxtseo skill install
 ```
@@ -256,7 +253,7 @@ reads retained rows and spends nothing.
 `search indexing summary` reads retained URL Inspection coverage.
 `search index-history` dates an indexing change against known releases.
 `search inspect <url>` reads Google's own verdict for one URL.
-`page inspect <url>` reads the NuxtSEO observation store for the same URL.
+`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
 ranking responses report `cached: true`. A cached response spends nothing.
@@ -279,7 +276,6 @@ The CLI fetches one page per invocation by default. It never merges responses.
 | `search analytics` | `--limit 1..100`, `--page >=1` | `--limit 25 --page 1` | row views only |
 | `search indexing` | `--limit 1..500`, `--offset >=0` | `--limit 50 --offset 0` | `urls` view only |
 | `sitemaps urls` | `--cursor`, `--limit 1..1000` | `--limit 500` | yes |
-| `content briefs list` | `--limit 1..100`, `--offset >=0` | `--limit 25 --offset 0` | yes |
 | `timeline list` | `--kind`, `--feature`, `--severity`, `--since`, `--cursor`, `--limit 1..100` | `--limit 25` | no |
 
 Keep the server order for actions. For another page, pass the next offset or

package/dist/cli.js

@@ -202,7 +202,7 @@ async function interactiveBare(runtime, globals) {
         return fromStateError(apiUrl.error);
     if (config._tag === 'Err')
         return fromStateError(config.error);
-    prompts.intro(`NuxtSEO ${VERSION}`, { input: runtime.input, output: runtime.error });
+    prompts.intro(`nuxtseo ${VERSION}`, { input: runtime.input, output: runtime.error });
     prompts.note([
         `Authentication: ${auth.value.authenticated ? auth.value.source : 'not configured'}`,
         `API: ${apiUrl.value.apiUrl}`,
@@ -215,7 +215,7 @@ async function interactiveBare(runtime, globals) {
             { value: 'fix', label: 'Fix my Site', hint: 'Issues, Pages, and Scans' },
             { value: 'performance', label: 'Understand performance', hint: 'Performance and Search Console' },
             { value: 'research', label: 'Research growth', hint: 'Keywords, SERPs, and competitors' },
-            { value: 'content', label: 'Plan content', hint: 'Briefs, decay, and duplicates' },
+            { value: 'content', label: 'Plan content', hint: 'Decay, duplicates, and annotations' },
             { value: 'account', label: 'Account and setup', hint: config.value.siteId ?? 'no Site selected' },
             { value: 'exit', label: 'Exit' },
         ],
@@ -356,8 +356,6 @@ async function interactiveBare(runtime, globals) {
         const task = await prompts.select({
             message: 'Plan content',
             options: [
-                { value: 'briefs', label: 'Content Briefs' },
-                { value: 'create', label: 'Create a Content Brief' },
                 { value: 'decay', label: 'Content decay' },
                 { value: 'duplicates', label: 'Duplicate clusters' },
                 { value: 'annotations', label: 'Chart annotations', hint: 'mark what you shipped' },
@@ -368,22 +366,11 @@ async function interactiveBare(runtime, globals) {
         });
         if (typeof task === 'symbol')
             return ok(undefined);
-        if (task === 'briefs')
-            return runInteractiveCommand(['content', 'briefs', 'list'], runtime, globals);
         if (task === 'decay')
             return runInteractiveCommand(['audit', 'content-decay'], runtime, globals);
         if (task === 'duplicates')
             return runInteractiveCommand(['audit', 'duplicates'], runtime, globals);
-        if (task === 'annotations')
-            return runInteractiveCommand(['annotations', 'list'], runtime, globals);
-        const keyword = await promptTextValue(runtime, {
-            message: 'Which target keyword?',
-            placeholder: 'nuxt seo',
-            label: 'Keyword',
-        });
-        return keyword._tag === 'Err'
-            ? keyword
-            : runInteractiveCommand(['content', 'briefs', 'create', keyword.value], runtime, globals);
+        return runInteractiveCommand(['annotations', 'list'], runtime, globals);
     }
     const task = await prompts.select({
         message: 'Account and setup',

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, renderContentBrief, renderContentBriefCreated, renderContentBriefs, 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, renderUsage, } from './render.js';
 import { writeCliResponse, writeDiagnostic, writeOutput, writeProtocolResponse } from './runtime.js';
 import { resolveSite } from './site.js';
 import { installSkill, SKILL_AGENTS } from './skill.js';
@@ -231,7 +231,7 @@ async function logout(runtime, globals) {
     else {
         writeOutput(runtime, cleared.value.removed ? 'Local credential removed.' : 'No stored credential.');
     }
-    writeDiagnostic(runtime, 'Token revocation remains in the NuxtSEO dashboard. NUXTSEO_TOKEN, when set, is unchanged.');
+    writeDiagnostic(runtime, 'Token revocation remains in the Nuxt SEO dashboard. NUXTSEO_TOKEN, when set, is unchanged.');
     return ok(undefined);
 }
 async function whoami(runtime, globals) {
@@ -370,7 +370,7 @@ async function feedbackSubmit(runtime, globals, args) {
     const body = accountFeedbackBodySchema.safeParse({ ...args, cliVersion: VERSION });
     if (!body.success)
         return fail(EXIT_CODE.invalidInput, 'Pass valid --command, --comment, and --agent values. Read feedback submit --help for limits.', undefined, 'invalid_cli_input');
-    const confirmed = await confirmMutation(runtime, globals, 'Submit this agent report to NuxtSEO feedback?');
+    const confirmed = await confirmMutation(runtime, globals, 'Submit this agent report to Nuxt SEO feedback?');
     if (confirmed._tag === 'Err')
         return confirmed;
     if (!confirmed.value) {
@@ -1088,65 +1088,6 @@ async function timelineEntries(runtime, globals, args) {
     }, { signal: runtime.requestSignal }));
     return present(runtime, globals, response, value => renderTimeline(value.data));
 }
-async function contentBriefList(runtime, globals, args) {
-    const status = args.status === undefined
-        ? ok(undefined)
-        : parseChoice(args.status, {
-            name: '--status',
-            choices: ['queued', 'researching', 'ready', 'written', 'published', 'stale', 'failed', 'archived'],
-        });
-    if (status._tag === 'Err')
-        return status;
-    const limit = parseInteger(args.limit, { name: '--limit', minimum: 1, maximum: 100, defaultValue: 25 });
-    if (limit._tag === 'Err')
-        return limit;
-    const offset = parseInteger(args.offset, { name: '--offset', minimum: 0, defaultValue: 0 });
-    if (offset._tag === 'Err')
-        return offset;
-    const resolved = await apiAndSite(runtime, globals);
-    if (resolved._tag === 'Err')
-        return resolved;
-    return collect(runtime, globals, {
-        all: args.all === true,
-        message: 'Loading Content Briefs',
-        start: { offset: offset.value },
-        fetch: position => resolved.value.api.client.content.listBriefs({
-            params: { siteId: resolved.value.siteId },
-            query: { status: status.value, limit: limit.value, offset: position.offset ?? 0 },
-        }, { signal: runtime.requestSignal }),
-        render: value => renderContentBriefs(value.data),
-        next: value => offsetPage(value.data.page),
-    });
-}
-async function contentBriefShow(runtime, globals, briefId) {
-    const resolved = await apiAndSite(runtime, globals);
-    if (resolved._tag === 'Err')
-        return resolved;
-    const response = await withSpinner(runtime, 'Loading Content Brief', () => resolved.value.api.client.content.showBrief({
-        params: { siteId: resolved.value.siteId, briefId },
-    }, { signal: runtime.requestSignal }));
-    return present(runtime, globals, response, value => renderContentBrief(value.data));
-}
-async function contentBriefCreate(runtime, globals, args) {
-    const targetPage = args.targetPage === undefined ? ok(undefined) : parseAbsolutePageUrl(args.targetPage);
-    if (targetPage._tag === 'Err')
-        return targetPage;
-    const resolved = await apiAndSite(runtime, globals);
-    if (resolved._tag === 'Err')
-        return resolved;
-    const confirmed = await confirmMutation(runtime, globals, `Create a Content Brief for ${args.keyword}?`);
-    if (confirmed._tag === 'Err')
-        return confirmed;
-    if (!confirmed.value) {
-        writeDiagnostic(runtime, 'Mutation cancelled.');
-        return ok(undefined);
-    }
-    const response = await withSpinner(runtime, 'Creating Content Brief', () => resolved.value.api.client.content.createBrief({
-        params: { siteId: resolved.value.siteId },
-        body: { keyword: args.keyword, targetPage: targetPage.value },
-    }, { signal: runtime.requestSignal }));
-    return present(runtime, globals, response, value => renderContentBriefCreated(value.data));
-}
 const VITALS_FORM_FACTORS = ['phone', 'desktop', 'all'];
 const VITALS_METRICS = ['lcp', 'inp', 'cls'];
 const VITALS_FORM_FACTOR_WIRE = {
@@ -1969,51 +1910,6 @@ export function createRootCommand(runtime, globals, execution) {
             }),
         },
     });
-    const content = defineCommand({
-        meta: { name: 'content', description: 'Read and create Content Briefs' },
-        subCommands: {
-            briefs: defineCommand({
-                meta: { name: 'briefs', description: 'Manage Content Briefs' },
-                subCommands: {
-                    list: defineCommand({
-                        meta: { name: 'list', description: 'List Content Briefs' },
-                        args: {
-                            status: {
-                                type: 'enum',
-                                options: ['queued', 'researching', 'ready', 'written', 'published', 'stale', 'failed', 'archived'],
-                                description: 'Filter by status',
-                            },
-                            limit: { type: 'string', description: 'Maximum Content Briefs, 1 to 100' },
-                            offset: { type: 'string', description: 'Pagination offset' },
-                            all: { type: 'boolean', description: 'Repeat until every page is written; one envelope per page' },
-                        },
-                        run: ({ args }) => capture(execution, () => contentBriefList(runtime, globals, {
-                            status: args.status,
-                            limit: args.limit,
-                            offset: args.offset,
-                            all: args.all,
-                        }), args._, 0)(),
-                    }),
-                    show: defineCommand({
-                        meta: { name: 'show', description: 'Show one Content Brief' },
-                        args: { briefId: positional('brief-id', 'Content Brief ID') },
-                        run: ({ args }) => capture(execution, () => contentBriefShow(runtime, globals, args.briefId), args._, 1)(),
-                    }),
-                    create: defineCommand({
-                        meta: { name: 'create', description: 'Create a Content Brief' },
-                        args: {
-                            'keyword': positional('keyword', 'Target keyword'),
-                            'target-page': { type: 'string', description: 'Absolute target Page URL' },
-                        },
-                        run: ({ args }) => capture(execution, () => contentBriefCreate(runtime, globals, {
-                            keyword: args.keyword,
-                            targetPage: args['target-page'],
-                        }), args._, 1)(),
-                    }),
-                },
-            }),
-        },
-    });
     const search = defineCommand({
         meta: { name: 'search', description: 'Read Search Console state' },
         subCommands: {
@@ -2217,10 +2113,10 @@ export function createRootCommand(runtime, globals, execution) {
         meta: {
             name: 'nuxtseo',
             version: VERSION,
-            description: 'Use NuxtSEO from a terminal or automation',
+            description: 'Use Nuxt SEO from a terminal or automation',
         },
         args: {
-            'api-url': { type: 'string', description: 'Override the NuxtSEO API host' },
+            'api-url': { type: 'string', description: 'Override the Nuxt SEO API host' },
             'site': { type: 'string', description: 'Override the selected Site' },
             'json': { type: 'boolean', description: 'Write machine JSON; protocol envelopes remain unchanged' },
             'no-input': { type: 'boolean', description: 'Disable every interactive prompt' },
@@ -2255,7 +2151,7 @@ export function createRootCommand(runtime, globals, execution) {
             }),
             sites,
             feedback: defineCommand({
-                meta: { name: 'feedback', description: 'Report CLI problems to NuxtSEO' },
+                meta: { name: 'feedback', description: 'Report CLI problems to Nuxt SEO' },
                 subCommands: {
                     submit: defineCommand({
                         meta: { name: 'submit', description: 'Submit sanitized agent feedback without selecting a Site' },
@@ -2290,7 +2186,6 @@ export function createRootCommand(runtime, globals, execution) {
             actions,
             audit,
             backlinks,
-            content,
             mentions,
             page,
             performance: defineCommand({

package/dist/pull.js

@@ -129,10 +129,6 @@ export const PULL_OPERATIONS = [
         params: { siteId: context.siteId },
         query: { limit: 100, includeFiltered: publicV1BooleanFlagValue(false) },
     }, { signal: context.signal })),
-    operation('content briefs list', context => context.client.content.listBriefs({
-        params: { siteId: context.siteId },
-        query: { limit: 25, offset: 0 },
-    }, { signal: context.signal })),
     operation('timeline list', context => context.client.timeline.entries({
         params: { siteId: context.siteId },
         query: { limit: 25 },

package/dist/render.d.ts

@@ -4,7 +4,6 @@ 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 { BacklinkAnchors, BacklinksHistory, BacklinksSummary, MentionsData, RecoverableBacklinksData, ReferringDomains } from '@nuxtseo/protocol/v1/backlinks';
-import type { ContentBrief, ContentBriefCreateData, ContentBriefListData } from '@nuxtseo/protocol/v1/content';
 import type { IndexCohorts, IndexingDiagnosticsData, IndexingHistoryData, SearchAnalyticsData, SearchStatusData, UrlInspectionData } from '@nuxtseo/protocol/v1/gsc';
 import type { PageInspectData, PageIssues, PageScan } from '@nuxtseo/protocol/v1/pages';
 import type { FieldVitalFindings, FieldVitals, MonitoredPages, PerformanceScanDetail, PerformanceScans, SitePerformanceOverview } from '@nuxtseo/protocol/v1/performance';
@@ -39,9 +38,6 @@ export declare function renderResearchOverview(data: StoredResearchOverview): st
 export declare function renderKeywordResearch(data: KeywordResearchData): string;
 export declare function renderSerpResearch(data: SerpResearchData): string;
 export declare function renderRankingsResearch(data: RankingsResearchData): string;
-export declare function renderContentBriefs(data: ContentBriefListData): string;
-export declare function renderContentBrief(data: ContentBrief): string;
-export declare function renderContentBriefCreated(data: ContentBriefCreateData): string;
 export declare function renderContentDecay(data: AuditContentDecay): string;
 export declare function renderDuplicateClusters(data: AuditDuplicateClusters): string;
 export declare function renderLinkOpportunities(data: AuditLinkOpportunities): string;

package/dist/render.js

@@ -482,27 +482,6 @@ export function renderRankingsResearch(data) {
         ...data.keywords.map(row => `${row.position}. ${row.keyword}  ${row.volume} volume  ${row.traffic} traffic\n  ${row.url}`),
     ].join('\n');
 }
-export function renderContentBriefs(data) {
-    if (data.briefs.length === 0)
-        return 'No Content Briefs match these filters.';
-    return [
-        `Content Briefs (${data.briefs.length} of ${data.page.total})`,
-        ...data.briefs.map(brief => `${brief.id}  ${brief.status}\n  ${brief.keyword}`),
-    ].join('\n');
-}
-export function renderContentBrief(data) {
-    return fields([
-        ['Content Brief', data.id],
-        ['Keyword', data.keyword],
-        ['Status', data.status],
-        ['Generated', data.generatedAt],
-        ['Updated', data.updatedAt],
-        ['Error', data.error],
-    ]);
-}
-export function renderContentBriefCreated(data) {
-    return `${data.created ? 'Created' : 'Found existing'} Content Brief.\n${renderContentBrief(data.brief)}`;
-}
 export function renderContentDecay(data) {
     if (!data.connected)
         return 'Connect Search Console to find content decay.';

package/dist/state/auth.js

@@ -65,7 +65,7 @@ function keyringFailure(operation, paths, cause) {
         _tag: 'KeychainFailure',
         operation,
         path: paths.authFile,
-        message: `Could not ${operation} the NuxtSEO credential in the OS keychain. Local auth state is recorded at ${paths.authFile}.`,
+        message: `Could not ${operation} the Nuxt SEO credential in the OS keychain. Local auth state is recorded at ${paths.authFile}.`,
         cause,
     });
 }
@@ -148,7 +148,7 @@ export async function saveCredential(value, options = {}) {
         return err({
             _tag: 'InvalidCredential',
             source: 'input',
-            message: 'The NuxtSEO API token cannot be empty.',
+            message: 'The Nuxt SEO API token cannot be empty.',
         });
     }
     const paths = options.paths ?? defaultStatePaths();

package/dist/state/files.js

@@ -19,7 +19,7 @@ function statePath(paths, kind) {
 function corruptState(kind, path, detail, cause) {
     const common = {
         path,
-        message: `Could not parse NuxtSEO ${kind} state at ${path}: ${detail}`,
+        message: `Could not parse Nuxt SEO ${kind} state at ${path}: ${detail}`,
         ...(cause === undefined ? {} : { cause }),
     };
     return kind === 'auth'
@@ -37,7 +37,7 @@ export async function readStateJson(paths, kind) {
             kind,
             operation: 'read',
             path,
-            message: `Could not read NuxtSEO ${kind} state at ${path}.`,
+            message: `Could not read Nuxt SEO ${kind} state at ${path}.`,
             cause: content,
         });
     }
@@ -76,7 +76,7 @@ export async function writeStateJson(paths, kind, value) {
             kind,
             operation: 'write',
             path,
-            message: `Could not write NuxtSEO ${kind} state at ${path}: the filesystem is read-only or permission was denied.`,
+            message: `Could not write Nuxt SEO ${kind} state at ${path}: the filesystem is read-only or permission was denied.`,
             cause,
         }
         : {
@@ -84,7 +84,7 @@ export async function writeStateJson(paths, kind, value) {
             kind,
             operation: 'write',
             path,
-            message: `Could not write NuxtSEO ${kind} state at ${path}.`,
+            message: `Could not write Nuxt SEO ${kind} state at ${path}.`,
             cause,
         }));
     if (written._tag === 'Err' && temporaryCreated) {
@@ -110,7 +110,7 @@ export async function removeStateFile(paths, kind) {
                 kind,
                 operation: 'delete',
                 path,
-                message: `Could not remove NuxtSEO ${kind} state at ${path}: the filesystem is read-only or permission was denied.`,
+                message: `Could not remove Nuxt SEO ${kind} state at ${path}: the filesystem is read-only or permission was denied.`,
                 cause,
             }
             : {
@@ -118,7 +118,7 @@ export async function removeStateFile(paths, kind) {
                 kind,
                 operation: 'delete',
                 path,
-                message: `Could not remove NuxtSEO ${kind} state at ${path}.`,
+                message: `Could not remove Nuxt SEO ${kind} state at ${path}.`,
                 cause,
             });
     });

package/package.json

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

package/skills/nuxtseo-cli/SKILL.md

@@ -1,149 +1,85 @@
 ---
 name: nuxtseo-cli
-description: Drives the `nuxtseo` CLI to triage a Site through the NuxtSEO public API: Site status and ranked issues, Search Console rows, route-family indexing, field and lab Core Web Vitals, Lighthouse Scans, Page Issues, keyword competitor and domain research, backlinks, SERP analysis, rankings, link opportunities, Content Briefs, content decay, duplicate clusters, chart annotations, and issue resolution. Use whenever the user mentions NuxtSEO, the `nuxtseo` command, Site SEO work, or NuxtSEO automation.
+description: Drives the `nuxtseo` CLI to triage a Site through the Nuxt SEO public API: Site status and ranked issues, Search Console rows, route-family indexing, field and lab Core Web Vitals, Lighthouse Scans, Page Issues, keyword competitor and domain research, backlinks, SERP analysis, rankings, link opportunities, content decay, duplicate clusters, chart annotations, and issue resolution. Use whenever the user mentions NuxtSEO, the `nuxtseo` command, Site SEO work, or Nuxt SEO automation.
 ---
 
-# NuxtSEO CLI
+# `nuxtseo` CLI
 
-`nuxtseo` reads a Site through the NuxtSEO public API. Every command goes
-through `@nuxtseo/sdk`. The CLI never calls MCP or private routes. Live
-research reaches a provider only through a declared public API operation.
-
-Use it to answer "what is wrong with this site, and what did I break". Then fix
-the code in the repository you are working in.
+`nuxtseo` reads a Site through the Nuxt SEO public API. Use it to answer "what
+is wrong with this site, and what did I break", then fix the cause in the
+repository you are working in. There is no MCP or private-route fallback.
 
 ## Reference files
 
-Read each one before you act on its subject:
-
-- [references/commands.md](references/commands.md): every command, with its
-  flags, ranges, and defaults. Read it instead of guessing a flag.
-- [references/protocol.md](references/protocol.md): response envelopes, paging,
-  and exit codes. Read it before you parse output or handle a failure.
-- [references/indexing.md](references/indexing.md): how to answer "is this
-  indexed". Read it before you report an indexed count, or name the URLs
-  Google indexed.
-
-## Get the binary
-
-```sh
-pnpm dlx @nuxtseo/cli@latest --version  # no install
-pnpm add -g @nuxtseo/cli                # or npm install --global
-```
-
-Node 22 or newer is required.
-
-Inside the NuxtSEO monorepo the package is not published. Run the built entry
-directly:
-
-```sh
-node packages/cli/dist/cli-entry.js --version
-```
-
-Exit `127` or `command not found` means the CLI is absent. That is not exit
-`3`; no token has been checked yet. Install it, then continue.
-
-## Before the first command
-
-```sh
-nuxtseo whoami --json          # validates the token and reports its scopes
-```
-
-`whoami` returns the Team, the role, the granted scopes, and the token expiry.
-Read `data.scopes` before a write command. A missing scope is exit `4`, and the
-scope list tells you that before you spend the request.
-
-Exit `3` means there is no working token. Ask the user to run `nuxtseo login`
-themselves. It opens a browser, they approve the pairing, and the CLI stores
-the token. Do not run `login` for them. It needs a person at the browser, and
-in a non-interactive shell it falls back to reading a token from stdin.
-
-The alternative is a token created at
-<https://nuxtseo.com/pro/dashboard/settings/api-tokens> and exported as
-`NUXTSEO_TOKEN`. Either way the token is bound to a Team role, and that role
-gates what it can do.
-
-Never put a token in a command argument, a file you write, or a commit.
-`login` reads a token from a hidden prompt or stdin only.
-
-Resolve the Site once and reuse it. `nuxtseo sites list --json` prints every
-accessible Site with its ID.
-
-## How to call it as an agent
+Read the matching file before you act on its subject:
 
-Always pass `--json`. Pass `--site <site-id>` for Site commands.
-`feedback submit` needs no Site.
-
-```sh
-nuxtseo actions list --site site_123 --json
-```
-
-`--json` writes the complete protocol envelope to stdout and one newline. It
-also disables prompts. Diagnostics, warnings, spinners, and failure messages go
-to stderr, so stdout stays parseable.
-
-Read `data.scopes` from `whoami` before you plan a loop, not when a step fails.
-A Team token carries only the scopes its role allows. A `viewer` token carries
-every `*:read` scope plus `feedback:write`, and nothing else. That token reads
-the whole Site and cannot write, so steps 5, 6, and 7 of the triage loop below
-all exit `4`: `page scan` needs `page:write`, `actions resolve` and `actions
-dismiss` need `actions:write`, and the `annotations` writes need
-`timeline:write`. `content briefs create` needs `content:write`, and the
-`sitemaps` writes need `sites:write`. Live research reads need only
-`research:read`, so a `viewer` token can still run them.
-
-If a write scope is missing, do steps 1 to 4, then hand the user the exact
-commands for the rest. Do not spend calls discovering the block one step at a
-time.
-
-`--site` matters for a second reason. An explicit Site ID goes straight to the
-operation and skips the Sites read. A token whose role cannot list Sites still
-works. If more than one Site is accessible and `--site` is absent, the CLI
-exits `5` rather than guessing.
-
-Other flags worth knowing:
-
-| Flag | Use it when |
+| File | Read it before you |
 | --- | --- |
-| `--yes`, `-y` | The command mutates. Without it, a non-interactive run exits `2` |
-| `--timeout-ms <ms>` | The default 30000 ms deadline is too short. Maximum is 300000 |
-| `--api-url <url>` | Testing against a non-production host |
-| `--no-input` | Running in a TTY but no prompt is wanted. `--json` already implies this |
-
-Unknown options exit `2` before any network work, so a typo costs nothing.
-
-Parse JSON. Never scrape human output.
-
-Every `--json` run prints one envelope. For example, `status` returns this,
-abridged:
-
-```sh
-nuxtseo status --site site_01JXYZ --json
-```
-
-```json
-{
-  "data": {
-    "available": true,
-    "dataQuality": { "status": "complete", "reason": null },
-    "nextAction": { "kind": "action", "actionId": "act_01JXYZ" }
-  },
-  "meta": { "requestId": "req_01JXYZ", "version": "1.0" }
-}
-```
-
-Read `data.available` first; `false` means the first assessment has not run.
-Read `data.dataQuality.status` before you quote the verdict. Pass
-`data.nextAction.actionId` into `actions show`.
+| [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 |
+
+## Setup
+
+1. **Binary.** Exit `127` means the CLI is absent. Install it, then continue:
+
+   ```sh
+   pnpm dlx @nuxtseo/cli@latest --version   # no install
+   pnpm add -g @nuxtseo/cli                 # global install, Node 22+
+   ```
+
+   Inside the Nuxt SEO monorepo, run `node packages/cli/dist/cli-entry.js`
+   instead.
+
+2. **Skill version.** Run `nuxtseo --version --json`. If stderr carries a line
+   like `skill 0.3.0 installed, CLI 0.4.0. Refresh with: nuxtseo skill install
+   --agent claude`, run that command and re-read this file. A stale skill hides
+   commands, so a missing command reads as a missing feature. If
+   `NUXTSEO_NO_UPDATE_CHECK` is set, the line never appears; compare this
+   file's frontmatter `version` with the binary 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.
+   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.
+
+4. **Scopes.** Read `data.scopes` now, not when a step fails. A `viewer` token
+   carries every `*:read` scope plus `feedback:write`. It can run every read,
+   including live research, and no write:
+
+   | Write | Scope |
+   | --- | --- |
+   | `page scan` | `page:write` |
+   | `actions resolve`, `actions dismiss` | `actions:write` |
+   | `annotations` writes | `timeline:write` |
+   | `sitemaps submit`, `sitemaps delete` | `sites:write` |
+
+   If a write scope is missing, do the reads, then hand the user the exact
+   write commands. Do not discover the block one exit `4` at a time.
+
+5. **Site.** Run `nuxtseo sites list --json` once and reuse the ID. If more
+   than one Site is accessible and `--site` is absent, the CLI exits `5`
+   rather than guess.
+
+## Calling convention
+
+- Always pass `--json` and `--site <site-id>`. `feedback submit` needs no Site.
+- `--json` writes one envelope to stdout. Diagnostics go to stderr. Parse the
+  JSON; never scrape human output.
+- A mutation needs `--yes`. Without it, a non-interactive run exits `2`.
+- `--timeout-ms` raises the 30000 ms deadline, up to 300000.
+- An unknown option exits `2` before any network work.
+- Branch on the exit code, never on message text. The table is in
+  [references/protocol.md](references/protocol.md).
 
 ## The triage loop
 
-This sequence turns CLI output into a code change. Copy the checklist and track
-your progress:
+Copy this checklist and track your progress:
 
 ```
 Triage progress:
-- [ ] 0. version check: this skill matches the binary
 - [ ] 1. status: read the verdict and the Next Action
 - [ ] 2. actions list: pick a ranked action, check its freshness
 - [ ] 3. actions show: read the evidence behind it
@@ -153,116 +89,90 @@ Triage progress:
 - [ ] 7. annotations create: mark the day the fix shipped
 ```
 
-**Step 0. Check this skill matches the binary.**
+**1. Read the verdict.**
 
 ```sh
-nuxtseo --version --json
+nuxtseo status --site <site-id> --json
 ```
 
-This writes a `CliVersion` value, so read `version` at the top level. There is
-no `data` wrapper. This skill records CLI 0.2.1: the `skill install` command
-copies this file out of that package release, so a matching binary means a
-matching skill. Compare the binary version with 0.2.1. If the binary differs,
-it may hold commands this skill never names. Refresh the skill first:
-
-```sh
-nuxtseo skill install --agent claude
+```json
+{
+  "data": {
+    "available": true,
+    "dataQuality": { "status": "complete", "reason": null },
+    "nextAction": { "kind": "action", "actionId": "act_01JXYZ" }
+  },
+  "meta": { "requestId": "req_01JXYZ", "version": "1.0" }
+}
 ```
 
-Then re-read this file. The refreshed copy records its own CLI version, so the
-check passes on the re-read. A stale skill fails silently: it lists fewer
-commands, so a missing command reads as a missing feature.
-
-**Step 1. Read the Site verdict.**
-
-```sh
-nuxtseo status --site <site-id> --json
-```
+- `available: false` means the first assessment has not run.
+- Read `dataQuality.status` before you quote the verdict. `degraded` means
+  proofs were missing, so the verdict is Provisional. `unavailable` means it
+  has not run.
+- If `nextAction.kind` is `action`, pass its `actionId` to step 3.
 
-If you need the whole Site rather than the next action, start with `pull`
-instead:
+For the whole Site instead of the next action, run one `pull`. It performs
+every spend-free Site read and writes one envelope per line:
 
 ```sh
 nuxtseo pull --site <site-id> --json > site.ndjson
 ```
 
-One invocation performs every stored-evidence read and writes one envelope per
-line. It spends nothing, and it never mutates. Read
-[references/commands.md](references/commands.md) for its filters and its
-failure behaviour. Then return to step 2 with the rows it gave you.
-
-This is the cheapest orientation: the verdict, the single ranked Next Action,
-and what changed recently. Read `dataQuality.status` before quoting it.
-`degraded` means the assessment ran with proofs missing, so the verdict is real
-but Provisional. `unavailable` means it has not run. If `nextAction.kind` is
-`action`, its `actionId` goes straight into step 3.
-
-**Step 2. Pick a ranked action.**
+**2. Pick a ranked action.**
 
 ```sh
 nuxtseo actions list --site <site-id> --json
 ```
 
-Each row carries an ID, a diagnosis, an effort, and an affected page count.
-Check `evidence.freshness` per row. If `verdict` is `aged` with a large
-`ageHours`, live-check a cheap sample before fixing. The site may have moved on
-since the observation.
+Keep server order. Check `evidence.freshness` on each row. If `verdict` is
+`aged` with a large `ageHours`, live-check a cheap sample before you fix. The
+Site may have changed since the observation.
 
-**Step 3. Read the evidence.**
+**3. Read the evidence.**
 
 ```sh
 nuxtseo actions show <action-id> --site <site-id> --json
 ```
 
-This returns which pages, which finding type, and when it was observed.
-
-Two reads deepen this step when the action's own evidence is not enough:
+It names the pages, the finding type, and when it was observed. Two reads go
+deeper:
 
-- `nuxtseo page issues --action-id <action-id> --site <site-id> --json` returns
-  the raw observations behind that action: the exact URLs, status codes,
-  redirect targets, and for a Lighthouse row the failing selectors and DOM
-  snippets. These are the mutable observation store, never canonical action
-  membership.
-- `nuxtseo scans show <scan-id> --site <site-id> --json` returns the failing
-  checks behind a Lighthouse score, so you can locate the cause without
-  re-scanning.
+- `page issues --action-id <action-id>`: the raw observations, with URLs,
+  status codes, redirect targets, and Lighthouse selectors. This is the
+  mutable observation store, never canonical action membership.
+- `scans show <scan-id>`: the failing checks behind a Lighthouse score.
 
-**Step 4. Fix the cause in the repository.**
+**4. Fix the cause.** Map the URLs in the evidence to routes, components, or
+config.
 
-The evidence names URLs. Map them back to routes, components, or config.
-
-**Step 5. Re-scan a page you changed.**
-
-Deploy or preview the fix first. Then ask for fresh Scans:
+**5. Re-scan.** Deploy or preview the fix first:
 
 ```sh
 nuxtseo page scan <url> --site <site-id> --yes --json
 ```
 
-**Step 6. Claim the action.**
+**6. Claim the action.**
 
 ```sh
 nuxtseo actions resolve <action-id> --site <site-id> --yes --json
 ```
 
-The server verifies it. The CLI never marks anything fixed by itself. Resolve
-reads the action first and sends the current `artifactVersion` for you. Do not
-construct that field by hand. If the evidence moved under you, the command
-exits `5` with `stale_evidence`. Re-run step 3 and decide again.
+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.
 
-When the fix is a deliberate removal rather than a repair, dismiss instead of
-resolving:
+If the fix is a deliberate removal, dismiss instead. Read `artifactVersion`
+from `actions show`, then:
 
 ```sh
-nuxtseo actions show <action-id> --site <site-id> --json    # read artifactVersion
 nuxtseo actions dismiss <action-id> --site <site-id> --artifact-version <v> --yes --json
 ```
 
-Dismiss is admitted only for a broken-page action with complete 404 or 410
-evidence and no internal referrers. Anything else is rejected, so it cannot be
-used to hide work.
+The server admits a dismiss only for a broken-page action with complete 404 or
+410 evidence and no internal referrers.
 
-**Step 7. Mark the day the fix shipped.**
+**7. Mark the day.**
 
 ```sh
 nuxtseo annotations create --site <site-id> --date "$(date -u +%F)" --title "Fixed canonicals on /docs" --yes --json
@@ -270,127 +180,93 @@ nuxtseo annotations create --site <site-id> --date "$(date -u +%F)" --title "Fix
 
 The next traffic move then has a cause beside it.
 
-## Datasets that must not be conflated
-
-Two datasets share the word "vitals":
-
-- `performance` and `scans *` read Lighthouse **lab** Scans.
-- `vitals summary`, `vitals trend`, and `vitals findings` read **field**
-  (real-user) data. `vitals` reads CrUX. `vitals findings` reads the Site's own
-  Web Analytics provider.
-
-A lab score and a field p75 disagreeing is normal, not a fault.
-
-Two commands inspect the same URL and answer different questions. `page inspect`
-reads the NuxtSEO observation store. `search inspect` reads Google's index
-verdict.
-
-`status`, `performance`, and `vitals` answer different questions. `status` is
-the verdict. `performance` is the lab score. `vitals` is what real users
-measured. Never substitute one for another.
-
-The Search Console reads also split:
+## Reading results correctly
 
-- `search status` reads stored connection state. It never waits for Google.
-- `search analytics`, `search indexing`, `search index-history`, and
-  `search inspect` read retained Search Console evidence through the public API.
-- `sitemaps submit` and `sitemaps delete` reach Google through the Site's
-  stored Search Console credential. Both are mutations.
+**Empty is not clean.** Each read names its own kind of empty. Say which one
+you got:
 
-## Route-family indexing: two lists, one claim
-
-`search cohorts` answers "which template is Google declining" in one read,
-instead of N page-level findings. Read it before you list individual
-not-indexed URLs. Its output holds two lists that mean different things. Never
-merge them.
+| Command | Empty signal |
+| --- | --- |
+| `page inspect` | `observations.coverage` |
+| `page issues` | `availableKeys` |
+| `search cohorts` | `analysed: false`: no completed crawl, or no Google index state |
+| `vitals summary` | `available: false` |
+| `research keywords`, `research rankings`, `research domain-*`, `page issues`, `search cohorts`, `vitals findings` | `data.message`, and `data.tip` for the repair |
+
+Read `data.message` before the list. For example, `research keywords` refuses
+a seed over three words, still exits `0`, and returns `keywords: []` with
+`evidence._tag: "no-provider"`. That is a refused argument, not zero demand.
+
+**A refusal is not an empty Site.** Exit `4` is a plan, scope, or entitlement
+blocker, for example `entitlement_required`. Exit `5` on `status`, `page
+issues`, or `search cohorts` can mean an archived or paused Site. Report the
+blocker and stop. Do not read it as "no data" or "nothing wrong", and do not
+retry unchanged.
+
+**Quote the count the result ships.** Never quote the length of a list. Use
+`data.total` from `page issues`, and `coverage.accessibilityChecksTotal` and
+`coverage.bestPracticesChecksTotal` from `scans show`. `possiblyTruncated:
+true` marks the list as a floor.
+
+**Keep these datasets apart:**
+
+- `performance` and `scans *` read Lighthouse **lab** Scans. `vitals summary`
+  and `vitals trend` read CrUX **field** data. `vitals findings` reads the
+  Site's own Web Analytics provider. A lab score and a field p75 that disagree
+  is normal.
+- `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.
+- `search status` reads the stored connection and never waits for Google.
+  `search analytics`, `search indexing`, `search index-history`, and
+  `search inspect` read retained Search Console evidence.
+- An indexed count comes from `search indexing`, never from analytics rows.
+  See [references/indexing.md](references/indexing.md).
+
+**Route families: `established` versus `ranked`.** Read `search cohorts`
+before you list single not-indexed URLs. Never merge its two lists:
+
+- `established` holds only families whose not-indexed rate is significant
+  against the rest of the Site, after a Bonferroni correction. Only these rows
+  are a finding or a cause.
+- `ranked` orders every family by raw rate, with no significance test. A row
+  with `statisticallyEstablished: false` is a lead to verify, for example by
+  inspecting its URLs. Presenting it as a cause is a hard failure.
 
-- `established` holds only families whose Wilson score interval clears the
-  not-indexed rate of their **own complement** after a Bonferroni correction.
-  These are the only rows you may report as a finding or a cause.
-- `ranked` orders every family by raw rate, with **no significance test**. It
-  always answers "where is indexing worst", even when nothing is provable. A
-  row with `statisticallyEstablished: false` is a lead to verify, never a
-  conclusion. Presenting one as established is a hard failure.
+## Guardrails
 
-`analysed: false` means there is no completed crawl, or no Google index state
-to join against. That is a coverage gap, not healthy indexing. Say which.
+- **Get consent before a mutation.** `page scan`, `actions resolve`, `actions
+  dismiss`, `sitemaps submit`, `sitemaps delete`, and the `annotations` writes
+  change server state. `sitemaps` writes also reach Google. `--yes` is consent
+  you borrow from the user, so ask first unless they asked for that exact
+  action.
+- **Spend limits.** `page scan` spends Lighthouse limit. `research *` and the
+  `backlinks` reads spend the Team research limit, except `backlinks
+  recoverable` and `mentions list`, which read retained rows. A `cache` or
+  `no-provider` evidence tag, or `cached: true`, means nothing was spent.
+  Check `usage` before any run over many Pages, keywords, or domains.
+- **No shell loops.** Use `pull` for Site reads and `--all` for paging. `--all`
+  stops at 50 requests with exit `9`; treat that as a stop and resume with the
+  argument stderr names.
 
 ## Report CLI feedback
 
-If CLI behavior blocks or slows your work, submit feedback once per distinct problem during the task.
-Report confusing output, missing context, incorrect help, unexpected failures, and useful workarounds.
-Continue the user's task after reporting.
+If the CLI blocks or slows your work, report it once per distinct problem, then
+continue the task. This skill authorizes that; no confirmation is needed unless
+the user forbids reporting.
 
 ```sh
-nuxtseo feedback submit --command "search cohorts" --agent "Codex" \
-  --comment "Agent report by Codex. Expected a reason for missing data. Received an empty list. Used search status instead." \
+nuxtseo feedback submit --command "search cohorts" --agent "<your agent name>" \
+  --comment "Agent report by <your agent name>. Expected a reason for missing data. Received an empty list. Used search status instead." \
   --yes --json
 ```
 
-Use your actual agent name. Start the comment with an agent disclosure.
-Include reproduction steps, expected behavior, actual behavior, and any workaround.
-Use `--intent improvement` for suggestions. The default is `bug`.
-If the affected response has a request ID, pass it with `--request-id`.
-The CLI adds its version automatically.
-
-Send sanitized details only. Remove tokens, cookies, personal data, private URLs, and customer content.
-Use command names and placeholder arguments. Never paste raw logs or full response bodies.
-
-Self-reporting sanitized CLI feedback is authorized by this skill. No separate confirmation is needed.
-This permission covers feedback only. Respect any user instruction that forbids reporting.
-The endpoint requires a working credential with `feedback:write`, available to every Team role.
-It uses no paid limit and allows ten reports per credential each hour.
-
-Success returns `data.id` and `data.status: "new"`. Keep the ID with your task notes.
-If reporting fails, mention the failure and continue. Never retry uncertain submissions or report failures recursively.
-If authentication is broken, describe the feedback to the user. Do not invent another endpoint.
-
-Reports use the existing feedback queue through `POST /api/v1/account/feedback`.
-Health checks show unresolved reports across all dates.
-Operators use **Pro feedback** in admin to record a fix reference and set `fixed` after verification.
-Fixed, replied, closed, and ignored reports leave the health check list. Reopening restores them.
-
-## Guardrails
-
-- **Get consent before a mutation.** `actions resolve`, `actions dismiss`,
-  `page scan`, `sitemaps submit`, `sitemaps delete`, `content briefs create`,
-  and the `annotations` writes all change server state. `page scan` also spends
-  against the Lighthouse limit. `--yes` is consent you borrow from the user, so
-  ask first, unless the user already asked for that exact action. `actions
-  dismiss` says the page stays removed, so use it only when that is the
-  decision.
-- **Live research spends against the Team research limit.** `research
-  keywords`, `research serp`, `research rankings`, `research domain-traffic`,
-  `research domain-availability`, and the `backlinks` reads other than
-  `backlinks recoverable` can all start it. Each one reports what it did.
-  Keyword, domain, and backlink JSON report cache use in `evidence`; a `cache`
-  or `no-provider` tag means nothing was spent. SERP and ranking JSON report
-  `cached`. `backlinks recoverable` and `mentions list` read retained rows and
-  spend nothing.
-- **Prefer one `pull` over a shell loop.** `pull` performs every spend-free
-  Site read in one invocation. Never write a shell loop over `nuxtseo` calls.
-- **Never loop unattended.** Check `usage` before any run over Pages, keywords,
-  or domains. Use `--all` rather than your own offset loop. It writes one
-  envelope per line and stops at 50 requests with exit `9`. Treat exit `9` as a
-  stop, then resume with the argument stderr names.
-- **Read `data.message` before you read a list.** `research keywords` refuses a
-  seed over three words and still exits `0`, with `keywords: []` and
-  `evidence._tag: "no-provider"`. The reason sits in `data.message`, and the
-  repair sits in `data.tip`. A `no-provider` tag can mean a refused argument.
-  Never read it as proof that the topic has no demand. `research rankings`,
-  `research domain-traffic`, `research domain-availability`, `page issues`,
-  `search cohorts`, and `vitals findings` carry the same `data.message`. The
-  full list is in references/protocol.md.
-- **Report the result as the CLI gave it.** Report failures as they are; there
-  is no MCP or private-route fallback. Never treat an empty result as clean:
-  `page inspect` names the kind of empty through `observations.coverage`,
-  `page issues` through `availableKeys`, `search cohorts` through
-  `analysed: false`, and `vitals summary` through `available: false`. A refusal
-  reads differently again: `status`, `page issues` and `search cohorts` exit
-  `4` or `5` on an archived or paused Site, which is never an empty Site. Other
-  commands may still return Provisional evidence. Quote the counts a result
-  ships with, never the length of its list: `data.total` from `page issues`,
-  then `coverage.accessibilityChecksTotal` and
-  `coverage.bestPracticesChecksTotal` from `scans show`. Neither command
-  reports the dropped row count, so `possiblyTruncated: true` marks the list as
-  a floor.
+- Start the comment with an agent disclosure. Give reproduction steps, the
+  expected and actual behaviour, and any workaround.
+- Pass `--request-id` when the response had one. Use `--intent improvement`
+  for a suggestion; the default is `bug`.
+- Send sanitized details only: no tokens, cookies, personal data, private URLs,
+  customer content, raw logs, or full response bodies.
+- The limit is ten reports per credential per hour. If a report fails, say so
+  and continue. Never retry it or report the failure.

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

@@ -10,6 +10,11 @@ Pass `--json` and `--site <site-id>` on every command below, except `whoami`,
 `Mutation` marks a command that changes server state. A mutation needs `--yes`
 in a non-interactive shell.
 
+Global options work on every command: `--site`, `--json`, `--yes` (`-y`),
+`--timeout-ms` (1 to 300000, default 30000), `--api-url` for a non-production
+host, and `--no-input` to disable prompts in a TTY. `--json` already implies
+`--no-input`.
+
 `Needs a Site URL` marks a command that reads the Site's own domain. If the Site
 has no URL, the command exits `2`. Set the Site URL first; retrying will not
 help.
@@ -17,7 +22,7 @@ help.
 `--all` repeats a paged read until every page is written, one envelope per line.
 It is available on `actions list`, `page inspect`, `page issues`, `vitals
 findings`, `backlinks recoverable`, `search analytics` row views, `search
-indexing urls`, `sitemaps urls` and `content briefs list`.
+indexing urls` and `sitemaps urls`.
 
 The `search analytics` row views are `pages`, `keywords`, `countries`,
 `devices`, and `analysis`. `--all` on any other view exits `2`.
@@ -34,7 +39,7 @@ The `search analytics` row views are `pages`, `keywords`, `countries`,
 - Web Analytics
 - Research, backlinks, and mentions
 - Crawl audit
-- Content Briefs, Timeline, and annotations
+- Timeline and annotations
 - Ask the CLI for its own help
 
 ## Which command answers which question
@@ -51,7 +56,7 @@ a research unit.
 | What should I fix first | `actions list` |
 | Why does this action exist | `actions show <action-id>` |
 | Which exact URLs does it affect | `page issues`, with `--action-id` |
-| What does NuxtSEO know about one URL | `page inspect <url>` |
+| What does Nuxt SEO know about one URL | `page inspect <url>` |
 | Did my last deploy break anything | `audit changes` |
 | How much of the Site is indexed | `search indexing summary` |
 | Which route family is Google declining | `search cohorts` |
@@ -80,7 +85,7 @@ reads with one invocation.
 
 `pull` excludes every mutation, and every read that needs an argument it cannot
 invent, such as `page inspect`, `page issues`, `search inspect`, `actions show`,
-`scans show` and `content briefs show`. Run those yourself with the IDs `pull`
+and `scans show`. Run those yourself with the IDs `pull`
 returned.
 
 `pull` makes one request per read. It never follows pages, so a run costs
@@ -227,13 +232,10 @@ research boundary in SKILL.md first.
 | `audit content-decay` | Stored decaying Pages, with Search Console loss evidence. Takes no flags. If `connected` is `false`, the Site has no Search Console data. Never report that as clean. `truncated: true` marks the list as a floor |
 | `audit duplicates` | Stored duplicate clusters, with members and keep candidate. Takes no flags. `crawlSettingsId: null` means the Site never completed a crawl. Then `total: 0` proves nobody looked. Never report it as a clean Site |
 
-## Content Briefs, Timeline, and annotations
+## Timeline and annotations
 
 | Command | What it returns, and its flags |
 | --- | --- |
-| `content briefs list` | Content Brief summaries. `--status`, `--limit`, `--offset` |
-| `content briefs show <brief-id>` | One Content Brief, including its grounded payload |
-| `content briefs create <keyword>` | Mutation. Creates one Content Brief. `--target-page` is optional |
 | `timeline list` | Stored Timeline Entries. `--kind`, `--feature`, `--severity`, `--since`, `--limit`, `--cursor`, `--include-closed` |
 | `annotations list` | This Site's own chart annotations: date-anchored markers on traffic and ranking charts |
 | `annotations create` | Mutation, so it needs `--yes`. Marks the day you shipped a fix. `--date YYYY-MM-DD` and `--title` are required. `--note` and `--url` are optional |

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

@@ -45,8 +45,9 @@ Page row:
 nuxtseo search analytics pages --site <site-id> --period 7d --all --json
 ```
 
-Keep rows where `row.impressions > 0`. Count those rows, and report `row.url`
-when the user asks which URLs appeared. Do not use `data.total` for this count.
+Keep rows where `row.impressions > 0`. Count distinct `row.gscPage` values,
+not rows. `row.url` is canonicalised, so one URL can span several rows. Report
+distinct `row.url` values when the user asks which URLs appeared. Do not use `data.total` for this count.
 It also includes comparison-period rows with zero current impressions.
 
 Keep these reads separate:

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

@@ -94,31 +94,44 @@ infer a cursor. Keep server order for actions. Never re-rank merged results.
 
 ## List key and paging shape per command
 
-There is no single list key. Read the key this command returns; never guess a
-chain. Verified against the response schemas.
+Lists are converging on one envelope: `data.rows` plus `data.page`, where
+`data.page` holds `total`, `limit`, `offset`, and `hasMore`. `page.total` counts
+the whole result set, not this page. Prefer that envelope when the command has
+it. If `data.rows` is absent, the server is older than the CLI; read the domain
+key in the table instead.
+
+The domain keys `data.sites`, `data.actions`, `data.clusters`, `data.items` on
+`backlinks recoverable` and `mentions list`, and `data.observations.pagination`
+are deprecated aliases. They are removed in a later minor version. Do not build
+on them.
+
+Commands without the envelope have no single list key. Read the key this
+command returns; never guess a chain. Verified against the response schemas.
 
 | Command | List key | Paging fields |
 | --- | --- | --- |
-| `sites list` | `data.sites` | none; `meta.total` |
+| `sites list` | `data.rows` (alias `data.sites`) | `data.page`; `meta.total` |
 | `usage` | `data.meters` | none |
-| `actions list` | `data.actions` | `data.page.total`, `.limit`, `.offset`, `.hasMore` |
+| `actions list` | `data.rows` (alias `data.actions`) | `data.page.total`, `.limit`, `.offset`, `.hasMore` |
 | `actions show` | `data.evidenceGroups[].items` | `data.evidenceGroups[].nextCursor` |
-| `page inspect` | `data.observations.rows` | `data.observations.total` and `data.observations.pagination.limit`, `.offset`, `.hasMore` |
+| `page inspect` | `data.observations.rows` | `data.observations.page` (alias `data.observations.pagination`); `data.observations.total` |
 | `page issues` | `data.issues` | `data.total`, `data.limit`, `data.offset` |
 | `scans list` | `data.scans` | `data.total`, `data.limit` |
 | `scans pages` | `data.pages` | `data.total` |
 | `vitals findings` | `data.findings` | `data.total`, `data.limit`, `data.offset` |
-| `search analytics` row views | `data.rows` | `data.total`; page with `--page` |
+| `search analytics` `pages`, `keywords`, `countries`, `devices` | `data.rows` | `data.page`; `data.total`; page with `--page` |
+| `search analytics` `analysis` | `data.rows` | `data.total`; page with `--page` |
+| `search analytics` `page-detail`, `keyword-detail` | `data.rows` | none |
 | `search analytics timeseries` | `data.daily` | none |
 | `search indexing urls` | `data.urls` | `data.total`, `data.limit`, `data.offset`, `data.hasMore` |
 | `search index-history` | `data.changes` | none |
 | `search cohorts` | `data.established` and `data.ranked` | `data.rankedTotal` |
 | `sitemaps list` | `data.sitemaps` | none |
 | `sitemaps urls` | `data.items` | `data.page.nextCursor`, `data.page.limit` |
-| `audit content-decay` | `data.rows` | `data.total`, `data.truncated` |
-| `audit link-opportunities` | `data.rows` | `data.total` |
-| `audit duplicates` | `data.clusters` | `data.total` |
-| `audit link-structure` | `data.templateSlots`, `data.deadEnds`, `data.genericAnchors` | one total per list |
+| `audit content-decay` | `data.rows` | `data.page`; `data.total`, `data.truncated` |
+| `audit link-opportunities` | `data.rows` | `data.page`; `data.total` |
+| `audit duplicates` | `data.rows` (alias `data.clusters`) | `data.page`; `data.total` |
+| `audit link-structure` | `data.templateSlots`, `data.deadEnds`, `data.genericAnchors` | `data.templateSlotTotal`; `data.deadEndGroupTotal` and `data.deadEndPageTotal`; `data.genericAnchorTotal` |
 | `research keywords` | `data.keywords` | `data.totalFound` |
 | `research serp` | `data.results` | none; `data.depth` |
 | `research rankings` | `data.keywords` | `data.totalFound` |
@@ -126,9 +139,8 @@ chain. Verified against the response schemas.
 | `backlinks referring-domains` | `data.items` | `data.total`, `data.limit` |
 | `backlinks anchors` | `data.items` | `data.total`, `data.limit` |
 | `backlinks history` | `data.items` | `data.total` |
-| `backlinks recoverable` | `data.items` | `data.total`, `data.limit`, `data.offset` |
-| `mentions list` | `data.items` | `data.limit` |
-| `content briefs list` | `data.briefs` | `data.page.total`, `.limit`, `.offset`, `.hasMore` |
+| `backlinks recoverable` | `data.rows` (alias `data.items`) | `data.page`; `data.total`, `data.limit`, `data.offset` |
+| `mentions list` | `data.rows` (alias `data.items`) | `data.page`; `data.total`, `data.limit` |
 | `timeline list` | `data.entries` | `data.nextCursor` |
 | `annotations list` | `data.annotations` | `data.total`, `data.limit` |