@nuxtseo/cli 0.1.0 → 0.1.2

package/dist/render.js

@@ -34,6 +34,13 @@ export function renderUsage(response) {
         });
     return [`Plan: ${response.data.plan}`, ...meters].join('\n');
 }
+function evidenceAgeLine(freshness) {
+    if (freshness.verdict === 'aged')
+        return `  evidence observed ${freshness.ageHours}h ago (${freshness.confidence})`;
+    if (freshness.verdict === 'unknown')
+        return '  evidence age unknown';
+    return '';
+}
 export function renderActions(data) {
     if (data.actions.length === 0)
         return 'No next actions.';
@@ -42,7 +49,8 @@ export function renderActions(data) {
         ...data.actions.map(action => [
             `${action.id}  ${action.diagnosis}`,
             `  ${action.status}, effort ${action.effort}, ${action.affectedPages ?? 'unknown'} affected pages`,
-        ].join('\n')),
+            evidenceAgeLine(action.evidence.freshness),
+        ].filter(Boolean).join('\n')),
         data.page.hasMore ? `More actions available after offset ${data.page.offset + data.page.limit}.` : '',
     ].filter(Boolean).join('\n');
 }
@@ -76,9 +84,12 @@ export function renderPageInspection(data) {
             ['SEO', data.performance.lighthouse.seo],
         ])
         : 'No Lighthouse scan.';
+    const empty = data.observations.coverage === 'issues-open'
+        ? ''
+        : ` (${data.observations.coverage})`;
     return [
         data.page.url,
-        `Observations: ${data.observations.total}`,
+        `Observations: ${data.observations.total}${empty}`,
         ...observations,
         lighthouse,
         `Tracked keywords: ${data.search.keywords.length}`,
@@ -107,16 +118,130 @@ export function renderPerformance(data) {
     ]);
 }
 export function renderSearchStatus(data) {
+    if (data._tag === 'Connected')
+        return fields([['Site', data.site], ['Search Console', 'connected']]);
+    if (data._tag === 'ActionRequired') {
+        const next = data.reason === 'credential_inactive'
+            ? 'Reconnect Search Console in Site settings.'
+            : 'Connect Search Console in Site settings.';
+        return `${fields([['Site', data.site], ['Search Console', 'action required']])}\n${next}`;
+    }
+    return `${fields([['Site', data.site], ['Search Console', 'disconnected']])}\nConnect Search Console in Site settings.`;
+}
+export function renderSearchAnalytics(data) {
+    if (data.type === 'pages') {
+        if (data.rows.length === 0)
+            return 'No Search Console Page rows match these filters.';
+        return [
+            `Search Console Pages (${data.rows.length} of ${data.total})`,
+            ...data.rows.map(row => `${row.clicks} clicks  ${row.impressions} impressions  position ${row.pos.toFixed(1)}\n  ${row.url}`),
+        ].join('\n');
+    }
+    if (data.type === 'keywords') {
+        if (data.rows.length === 0)
+            return 'No Search Console query rows match these filters.';
+        return [
+            `Search Console queries (${data.rows.length} of ${data.total})`,
+            ...data.rows.map(row => `${row.clicks} clicks  ${row.impressions} impressions  position ${row.pos.toFixed(1)}\n  ${row.keyword}`),
+        ].join('\n');
+    }
+    return fields([
+        ['View', data.type],
+        ['Period', data.period],
+        ['Rows', 'rows' in data ? data.rows.length : data.type === 'timeseries' ? data.daily.length : 0],
+    ]);
+}
+export function renderResearchOverview(data) {
+    const subject = data.subject
+        ? fields([
+            ['Domain', data.subject.domain],
+            ['Organic traffic', data.subject.metrics.organicTraffic],
+            ['Keywords', data.subject.metrics.totalKeywords],
+            ['Traffic value', data.subject.metrics.trafficValue],
+        ])
+        : 'No stored Site research.';
+    const competitors = data.competitors.length === 0
+        ? 'No stored competitors.'
+        : data.competitors.map(row => `${row.domain}  ${row.metrics.organicTraffic ?? 'unknown'} traffic  ${row.quickWins.length} quick wins`).join('\n');
+    return [subject, `Competitors: ${data.summary.competitorCount}`, competitors].join('\n');
+}
+export function renderKeywordResearch(data) {
+    if (data.keywords.length === 0)
+        return data.message ?? `No keyword ideas found for ${data.topic}.`;
+    return [
+        `Keyword ideas for ${data.topic} (${data.keywords.length} of ${data.totalFound})${data.evidence._tag === 'cache' ? '  cached' : ''}`,
+        ...data.keywords.map(row => `${row.volume ?? 'unknown'} volume  ${row.difficulty ?? 'unknown'} difficulty  ${row.intent ?? 'unknown intent'}\n  ${row.keyword}`),
+        ...(data.tip ? [`Tip: ${data.tip}`] : []),
+    ].join('\n');
+}
+export function renderSerpResearch(data) {
+    if (data.results.length === 0)
+        return `No organic SERP results found for ${data.keyword}.`;
+    return [
+        `SERP for ${data.keyword}  ${data.fetchedAt}${data.cached ? '  cached' : ''}`,
+        data.serpFeatures.length ? `Features: ${data.serpFeatures.join(', ')}` : 'Features: none',
+        ...data.results.map(row => `${row.position}. ${row.title}\n  ${row.domain}\n  ${row.url}`),
+    ].join('\n');
+}
+export function renderRankingsResearch(data) {
+    if (data.keywords.length === 0)
+        return data.message ?? `No rankings found for ${data.domain}.`;
+    return [
+        `${data.domain} rankings (${data.keywords.length} of ${data.totalFound})${data.cached ? '  cached' : ''}`,
+        ...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([
-        ['Site', data.site],
-        ['Connected', data.connected],
-        ['Sync status', data.syncStatus],
-        ['Progress', `${data.progress.percent}%`],
-        ['Last sync', data.lastSyncAt],
-        ['Data available', data.hasData],
-        ['Coverage', `${data.daysSynced}/${data.daysAvailable} days`],
+        ['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.';
+    if (data.rows.length === 0)
+        return 'No decaying Pages found.';
+    return [
+        `Content decay (${data.rows.length} of ${data.total})  ${data.clicksLost} clicks lost`,
+        ...data.rows.map(row => `${row.clicksDelta} clicks  ${row.clicksChangePct.toFixed(1)}%\n  ${row.url}`),
+    ].join('\n');
+}
+export function renderDuplicateClusters(data) {
+    if (data.clusters.length === 0)
+        return 'No duplicate clusters found.';
+    return [
+        `Duplicate clusters (${data.clusters.length} of ${data.total})  ${data.pagesAffected} Pages`,
+        ...data.clusters.map(cluster => `${cluster.size} Pages  ${cluster.pathPattern}\n  Keep: ${cluster.keepPath ?? 'not selected'}`),
+    ].join('\n');
+}
+export function renderLinkOpportunities(data) {
+    if (!data.connected)
+        return 'Connect Search Console to find link opportunities.';
+    if (data.textUnavailable)
+        return 'Page text is unavailable. Run a Site scan first.';
+    if (data.rows.length === 0)
+        return 'No link opportunities found.';
+    return [
+        `Link opportunities (${data.rows.length} of ${data.total})`,
+        ...data.rows.map(row => `${row.phrase}\n  From: ${row.sourceUrl}\n  To: ${row.targetUrl}`),
+    ].join('\n');
+}
 export function renderRecoverableBacklinks(data) {
     if (data.items.length === 0)
         return 'No recoverable Backlinks. Every stored inbound link resolves.';

package/dist/runtime.d.ts

@@ -10,6 +10,7 @@ export interface CliRuntime {
     interactive: boolean;
     signal: AbortSignal;
     requestSignal: AbortSignal;
+    requestTimeoutMs?: number;
     readStdin: () => Promise<string>;
 }
 export declare function writeOutput(runtime: CliRuntime, text: string): void;

package/dist/state/paths.d.ts

@@ -1,10 +1,12 @@
 export declare const STATE_DIRECTORY_NAME = ".nuxtseo";
 export declare const AUTH_FILENAME = "auth.json";
 export declare const CONFIG_FILENAME = "config.json";
+export declare const UPDATE_CHECK_FILENAME = "update-check.json";
 export interface StatePaths {
     directory: string;
     authFile: string;
     configFile: string;
+    updateCheckFile: string;
 }
 export declare function createStatePaths(homeDirectory: string): StatePaths;
 export declare function defaultStatePaths(): StatePaths;

package/dist/state/paths.js

@@ -3,12 +3,14 @@ import { join } from 'pathe';
 export const STATE_DIRECTORY_NAME = '.nuxtseo';
 export const AUTH_FILENAME = 'auth.json';
 export const CONFIG_FILENAME = 'config.json';
+export const UPDATE_CHECK_FILENAME = 'update-check.json';
 export function createStatePaths(homeDirectory) {
     const directory = join(homeDirectory, STATE_DIRECTORY_NAME);
     return {
         directory,
         authFile: join(directory, AUTH_FILENAME),
         configFile: join(directory, CONFIG_FILENAME),
+        updateCheckFile: join(directory, UPDATE_CHECK_FILENAME),
     };
 }
 export function defaultStatePaths() {

package/dist/update-check.d.ts

@@ -0,0 +1,25 @@
+import type { StatePaths } from './state/index.js';
+/** How long a registry answer stays authoritative, matching npm's update cache. */
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+export interface UpdateNotice {
+    current: string;
+    latest: string;
+}
+export interface UpdateCheckCache {
+    lastCheckedAt: string;
+    latest: string | null;
+}
+export type RegistryLatestFetch = (url: string, signal: AbortSignal) => Promise<string | null>;
+export interface UpdateCheckOptions {
+    paths: StatePaths;
+    env?: Readonly<Record<string, string | undefined>>;
+    fetch?: RegistryLatestFetch;
+    now?: () => Date;
+}
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+export declare function updateNoticeFor(latest: string | null, current: string): UpdateNotice | null;
+export declare function updateCheckDue(cache: UpdateCheckCache | null, now: Date): boolean;
+export declare function parseUpdateCheckCache(content: string): UpdateCheckCache | null;
+export declare function fetchRegistryLatest(url: string, signal: AbortSignal): Promise<string | null>;
+export declare function checkForUpdate(options: UpdateCheckOptions): Promise<UpdateNotice | null>;
+export declare function updateNoticeLine(notice: UpdateNotice): string;

package/dist/update-check.js

@@ -0,0 +1,107 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { VERSION } from './version.js';
+/** How long a registry answer stays authoritative, matching npm's update cache. */
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/@nuxtseo/cli/latest';
+const FETCH_TIMEOUT_MS = 2_000;
+function updateCheckDisabled(env) {
+    return env?.NUXTSEO_NO_UPDATE_CHECK === '1' || env?.NUXTSEO_NO_UPDATE_CHECK === 'true';
+}
+export function isNewerVersion(candidate, current) {
+    const core = (value) => {
+        const parts = value.trim().replace(/^v/, '').split('-')[0].split('.');
+        if (parts.length < 3)
+            return null;
+        const numbers = parts.slice(0, 3).map(part => Number.parseInt(part, 10));
+        return numbers.some(part => Number.isNaN(part)) ? null : numbers;
+    };
+    const candidateCore = core(candidate);
+    const currentCore = core(current);
+    if (!candidateCore || !currentCore)
+        return false;
+    for (let index = 0; index < 3; index++) {
+        if (candidateCore[index] !== currentCore[index])
+            return candidateCore[index] > currentCore[index];
+    }
+    // Same core: a prerelease candidate is not an update over the stable current.
+    return false;
+}
+export function updateNoticeFor(latest, current) {
+    return latest !== null && isNewerVersion(latest, current) ? { current, latest } : null;
+}
+export function updateCheckDue(cache, now) {
+    if (!cache)
+        return true;
+    const checkedAt = Date.parse(cache.lastCheckedAt);
+    return Number.isNaN(checkedAt) || now.getTime() - checkedAt >= UPDATE_CHECK_INTERVAL_MS;
+}
+export function parseUpdateCheckCache(content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        // A corrupt cache file is disposable state, not an error: refetch instead.
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const record = value;
+    if (typeof record.lastCheckedAt !== 'string')
+        return null;
+    if (record.latest !== null && typeof record.latest !== 'string')
+        return null;
+    return { lastCheckedAt: record.lastCheckedAt, latest: record.latest };
+}
+async function readUpdateCheckCache(paths) {
+    const content = await readFile(paths.updateCheckFile, 'utf8').catch(() => {
+        // A missing or unreadable cache file is the common first-run case.
+        return null;
+    });
+    return typeof content === 'string' ? parseUpdateCheckCache(content) : null;
+}
+async function writeUpdateCheckCache(paths, cache) {
+    // Persisting the cache is best effort. A failed write only costs one extra
+    // registry fetch on the next run, so the failure is ignorable by design.
+    await mkdir(paths.directory, { recursive: true, mode: 0o700 }).catch(() => {
+        // See the comment above: the cache is disposable state.
+        return undefined;
+    });
+    await writeFile(paths.updateCheckFile, `${JSON.stringify(cache, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    }).catch(() => {
+        // See the comment above: the cache is disposable state.
+        return undefined;
+    });
+}
+export async function fetchRegistryLatest(url, signal) {
+    const response = await fetch(url, { signal, headers: { accept: 'application/json' } });
+    if (!response.ok)
+        return null;
+    const body = await response.json();
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const version = body.version;
+    return typeof version === 'string' && version ? version : null;
+}
+export async function checkForUpdate(options) {
+    if (updateCheckDisabled(options.env))
+        return null;
+    const now = options.now?.() ?? new Date();
+    const cache = await readUpdateCheckCache(options.paths);
+    if (!updateCheckDue(cache, now))
+        return updateNoticeFor(cache.latest, VERSION);
+    const fetchLatest = options.fetch ?? fetchRegistryLatest;
+    const latest = await fetchLatest(REGISTRY_LATEST_URL, AbortSignal.timeout(FETCH_TIMEOUT_MS)).catch(() => {
+        // Registry reachability is best effort. The run continues without a hint.
+        return null;
+    });
+    if (latest !== null)
+        await writeUpdateCheckCache(options.paths, { lastCheckedAt: now.toISOString(), latest });
+    // A stale cached answer still beats no answer while the registry is unreachable.
+    return updateNoticeFor(latest ?? cache?.latest ?? null, VERSION);
+}
+export function updateNoticeLine(notice) {
+    return `${notice.latest} available, current ${notice.current}. Update with: pnpm add -g @nuxtseo/cli`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Command line interface for the NuxtSEO public API.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com/pro",
@@ -30,13 +30,11 @@
   "engines": {
     "node": ">=22"
   },
-  "peerDependencies": {
-    "@nuxtseo/sdk": "^0.1.0"
-  },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "citty": "^0.2.2",
-    "pathe": "^2.0.3"
+    "pathe": "^2.0.3",
+    "@nuxtseo/sdk": "^0.1.2"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "^1.3.0"
@@ -44,10 +42,9 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@types/node": "^26.2.0",
-    "publint": "^0.3.23",
+    "publint": "^0.3.24",
     "typescript": "npm:typescript-native-bridge@6.0.3-bridge.10.tsgo.7.0.2",
-    "@nuxtseo/protocol": "0.1.0",
-    "@nuxtseo/sdk": "0.1.0"
+    "@nuxtseo/protocol": "0.1.2"
   },
   "publishConfig": {
     "access": "public"

package/skills/nuxtseo-cli/SKILL.md

@@ -1,35 +1,31 @@
 ---
 name: nuxtseo-cli
-description: Drive the `nuxtseo` CLI (@nuxtseo/cli) to read and act on the NuxtSEO Pro data a Site already stores - next actions, page observations, Lighthouse and Core Web Vitals, Search Console sync state, and account usage. Use this whenever the user mentions NuxtSEO, `nuxtseo`, "what should I fix on my site", next actions, page scans, or asks you to check or resolve stored SEO issues, even when they do not name the CLI. Also use it before writing any script or CI step that shells out to `nuxtseo`. The CLI does NOT do research work; keyword ideas, SERP analysis, Search Console query and page data, rank tracking, competitors, and content briefs live in the `nuxt-seo-pro` MCP server instead, and this skill says which tool to reach for.
+description: Drive the `nuxtseo` CLI for Site triage, Search Console rows, keyword and competitor research, SERP analysis, rankings, link opportunities, Content Briefs, content decay, duplicate clusters, scans, and issue resolution. Use whenever the user mentions NuxtSEO, the `nuxtseo` command, Site SEO work, or NuxtSEO automation.
 ---
 
 # NuxtSEO CLI
 
 `nuxtseo` reads a Site through the NuxtSEO public API. Every command goes
-through `@nuxtseo/sdk`. The CLI never calls MCP, private routes, or providers,
-so it has no hidden fallback: what it prints is what the API returned.
+through `@nuxtseo/sdk`. The CLI never calls MCP or private routes. Live
+research reaches providers 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 repo you are working in.
 
-## What this CLI does not cover
+## Data boundaries
 
-The CLI reads what the product already stored for a Site. It runs no research.
+Most commands read stored Site evidence. Three commands can start live research:
 
-| The user wants | Reach for |
-| --- | --- |
-| Keyword ideas, volume, difficulty, SERP analysis | MCP `keyword_research`, `domain_info` |
-| Search Console queries, pages, striking distance | MCP `gsc_query` |
-| Rank history for tracked keywords | MCP `rank_tracker` |
-| Competitors, mentions, backlinks, link opportunities | MCP `competitors`, `mentions`, `backlinks`, `link_opportunities` |
-| Content briefs, content decay, duplicate clusters | MCP `content_briefs`, `content_decay`, `duplicate_clusters` |
+- `research keywords`
+- `research serp`
+- `research rankings`
 
-Those tools come from the `nuxt-seo-pro` MCP server, which the user connects
-separately. If the MCP server is not connected and the job is research shaped,
-say so and stop. Do not approximate research output from CLI data.
+These commands use the Team research allowance when the server misses its
+cache. Keyword JSON reports cache use in `evidence`. SERP and ranking JSON
+report `cached`.
 
-`nuxtseo search status` reports only whether Search Console is connected and how
-far the sync got. It returns no query rows.
+`search status` reads stored connection state. It never waits for Google.
+`search analytics` reads Search Console rows through the public API.
 
 ## Get the binary
 
@@ -109,13 +105,26 @@ handling failures, read [CLI protocol](references/protocol.md).
 | `sites list` | Every accessible Site | Source of Site IDs |
 | `sites use <site-id>` | – | Persists a default Site for the human, not for you |
 | `usage` | Plan and meters | `--group integrations\|compute\|capacity` |
-| `actions list` | Server ranked next actions | `--limit 1..25` (default 10), `--offset` |
-| `actions show <action-id>` | One action plus evidence | `--limit 1..100` (default 50), `--group-id`, `--cursor` |
-| `actions resolve <action-id>` | – | Mutation. Claims the action and starts server verification |
-| `page inspect <url>` | Stored observations, Lighthouse, keywords | `--limit 1..200`, `--offset`, `--include-resolved` |
+| `actions list` | Server-ranked issues and opportunities | `--limit 1..25` (default 10), `--offset`. JSON 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 evidence | `--limit 1..100` (default 50), `--group-id`, `--cursor` |
+| `actions resolve <action-id>` | – | Mutation. Claims the issue or opportunity and starts server verification |
+| `backlinks recoverable` | Stored recoverable backlinks | `--limit 1..200`, `--offset` |
+| `mentions list` | Stored mentions | `--limit 1..200` |
+| `page inspect <url>` | Stored observations, Lighthouse, keywords | `--limit 1..200`, `--offset`, `--include-resolved`. JSON carries `observations.coverage`: `never-scanned` means no source recorded this Page, `scanned-clear` means recorded and all clear |
 | `page scan <url>` | – | Mutation. Starts mobile and desktop scans |
 | `performance` | Site performance overview | Medians for perf, a11y, SEO, LCP, TBT, CLS |
-| `search status` | Search Console connection and sync progress | Check this before trusting search data |
+| `search status` | Stored Search Console connection | Provider free |
+| `search analytics <pages\|keywords>` | Search Console Page or query rows | `--period`, `--limit`, `--page`, `--search` |
+| `research overview` | Stored Site and competitor research | Metrics, history, gaps, and quick wins |
+| `research keywords <topic>` | Live keyword ideas | Volume, difficulty, intent, and cost data |
+| `research serp <keyword>` | Live SERP snapshot | Results, features, and fetch time |
+| `research rankings <domain>` | Live domain rankings | Current keywords and domain metrics |
+| `audit link-opportunities` | Stored internal link opportunities | Includes crawl coverage |
+| `audit content-decay` | Stored decaying Pages | Includes Search Console loss evidence |
+| `audit duplicates` | Stored duplicate clusters | Includes members and keep candidate |
+| `content briefs list` | Content Brief summaries | `--status`, `--limit`, `--offset` |
+| `content briefs show <brief-id>` | One Content Brief | Includes its grounded payload |
+| `content briefs create <keyword>` | – | Mutation. `--target-page` is optional |
 | `config` | Local config path, API host, selected Site | Local only |
 
 `page inspect` and `page scan` take an absolute URL, for example
@@ -132,7 +141,10 @@ flag, and prefer the table above for anything it already answers.
 This is the sequence that turns CLI output into a code change:
 
 1. `nuxtseo actions list --site <id> --json` gives ranked work with an ID, a
-   diagnosis, an effort, and an affected page count.
+   diagnosis, an effort, and an affected page count. Check
+   `evidence.freshness` per row: `verdict: "aged"` with a large `ageHours`
+   means the evidence is old. Live-check a cheap sample before fixing, because
+   the site may have moved on since the observation.
 2. `nuxtseo actions show <action-id> --site <id> --json` gives the evidence:
    which pages, which finding type, and when it was observed.
 3. Fix the cause in the repository. The evidence names URLs; map them back to
@@ -152,11 +164,9 @@ command exits `5` with `stale_evidence`; re-run step 2 and decide again.
 - Ask before you mutate. `actions resolve` and `page scan` consume quota and
   change server state. `--yes` is consent you are borrowing from the user, so
   get it first unless the user already asked for that exact action.
-- Do not loop over pages or URLs unattended. Each call is a real API request
-  against a metered plan. Check `nuxtseo usage --json` if you plan a batch.
-- Report failures as they are. The CLI has no cache and no fallback path, so a
-  failure means the data is genuinely unavailable, not that another route may
-  work.
-- Do not treat an empty result as a clean bill of health. `search status` may
-  report an unfinished sync, and a Page with no stored observations may simply
-  never have been crawled.
+- Do not loop over Pages, keywords, or domains unattended. Check `usage` first.
+- Live research can consume allowance. A cached result does not consume a unit.
+- Report failures as they are. The CLI has no MCP or private-route fallback.
+- Do not treat an empty result as clean. `page inspect` JSON says which empty
+  it is through `observations.coverage`; other commands may still have
+  incomplete evidence.

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

@@ -32,6 +32,22 @@ Local outcomes have no server body. They carry `schemaVersion: 1` and one tag:
 
 Discriminate on `_tag`. Protocol envelopes never carry one.
 
+A `CliError` for exit `2` or exit `7` also carries `cliVersion`, and
+`latestKnownVersion` when the CLI knows the registry holds a newer version.
+Those two exits are where a stale binary looks like broken docs or a broken
+server; check the versions before debugging anything else.
+
+## Update hints
+
+Every run checks the npm registry for a newer CLI, cached for 24 hours. When a
+newer version is known, one line goes to stderr, for example:
+
+```
+0.2.0 available, current 0.1.1. Update with: pnpm add -g @nuxtseo/cli
+```
+
+Set `NUXTSEO_NO_UPDATE_CHECK=1` to disable the check, for example in CI.
+
 ## Paging
 
 One invocation makes one request. The CLI never auto-pages or merges responses.
@@ -51,7 +67,7 @@ Branch on the exit code, not message text.
 | `4` | Forbidden, scope, or entitlement failure | Report the plan or token blocker |
 | `5` | Conflict, stale evidence, or ambiguous Site | Re-read. Pass `--site` if ambiguous |
 | `6` | Rate limit, quota, provider outage, or timeout | Read retry metadata, then wait |
-| `7` | Local state, network, contract, or infrastructure failure | Report it with the request ID |
+| `7` | Local state, network, contract, or infrastructure failure | Report it with the request ID. If the message names `contract_violation`, update the CLI first |
 | `8` | Resource or Site not found | Run `sites list` for a valid Site ID |
 | `127` | Shell cannot find `nuxtseo` | Install the CLI |
 | `130` | Interrupted or cancelled | Check whether a mutation ran before retrying |