@nuxtseo/cli 0.2.0 → 0.3.0

package/dist/skill.js

@@ -1,8 +1,25 @@
-import { cp, mkdir, stat } from 'node:fs/promises';
+import { copyFile, mkdir, readdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, relative } from 'pathe';
 import { EXIT_CODE, fail, ok } from './failures.js';
+import { VERSION } from './version.js';
 export const SKILL_NAME = 'nuxtseo-cli';
+/** The stamp an install leaves beside the skill so a later run can read its version. */
+export const SKILL_VERSION_FILENAME = '.skill-version.json';
+/** The skill entry file, which also carries the version in its frontmatter. */
+export const SKILL_MARKDOWN_FILENAME = 'SKILL.md';
+const SKILL_CHECK_FILENAME = 'skill-check.json';
+/**
+ * How long one answer stays authoritative, matching the npm update check.
+ *
+ * Declared here rather than imported so `update-check.ts` can depend on this
+ * module and the two never form an import cycle.
+ */
+export const SKILL_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** The same escape hatch the npm update check honours. */
+function checksDisabled(env) {
+    return env?.NUXTSEO_NO_UPDATE_CHECK === '1' || env?.NUXTSEO_NO_UPDATE_CHECK === 'true';
+}
 /**
  * Directories inside the packaged skill that exist for this repository and not
  * for the person installing it. `npm` keeps them out of the tarball through the
@@ -26,6 +43,314 @@ export function skillSourceDirectory(moduleUrl = import.meta.url) {
 export function skillDestination(homeDirectory, agent) {
     return join(homeDirectory, AGENT_DIRECTORIES[agent], 'skills', SKILL_NAME);
 }
+/**
+ * The install target, followed through a symlink.
+ *
+ * People keep their skills in one directory and link each agent's skill folder
+ * at it. `fs.cp` lstats the target, sees a link rather than a directory, and
+ * refuses with `ERR_FS_CP_DIR_TO_NON_DIR` before it copies anything. That
+ * reported as a permission problem on a directory the user owned and could
+ * write. Follow the link first so the copy writes where the person pointed it.
+ */
+export async function resolveSkillTarget(destination) {
+    return await realpath(destination).catch(() => {
+        // Nothing installed yet, so there is no link to follow. Create the literal path.
+        return destination;
+    });
+}
+/** An errno or Node error as a person can act on it: code, call, and path. */
+export function describeIoCause(cause) {
+    if (!cause || typeof cause !== 'object')
+        return String(cause);
+    const error = cause;
+    const parts = [
+        typeof error.code === 'string' ? error.code : undefined,
+        typeof error.syscall === 'string' ? `during ${error.syscall}` : undefined,
+        typeof error.path === 'string' ? `on ${error.path}` : undefined,
+        typeof error.dest === 'string' ? `to ${error.dest}` : undefined,
+    ].filter((part) => part !== undefined);
+    if (parts.length > 0)
+        return parts.join(' ');
+    return typeof error.message === 'string' ? error.message : String(cause);
+}
+async function collectSkillFiles(root, directory = root) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const collected = [];
+    for (const entry of entries) {
+        const source = join(directory, entry.name);
+        const path = relative(root, source);
+        const [segment] = path.split('/');
+        if (segment && SKILL_LOCAL_ONLY.has(segment))
+            continue;
+        if (entry.isDirectory())
+            collected.push(...await collectSkillFiles(root, source));
+        else if (entry.isFile())
+            collected.push({ path, source });
+    }
+    return collected;
+}
+/**
+ * Write the running version into the skill frontmatter.
+ *
+ * An agent reads `SKILL.md` and nothing else, so the file has to say which
+ * release it came from. Without it a skill from an older CLI hides every
+ * command added since, and the agent cannot tell.
+ */
+export function stampSkillVersion(markdown, version) {
+    const stamp = `version: ${version}`;
+    const lines = markdown.split('\n');
+    if (lines[0]?.trim() !== '---')
+        return `---\n${stamp}\n---\n\n${markdown}`;
+    const closing = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    if (closing === -1)
+        return `---\n${stamp}\n---\n\n${markdown}`;
+    const block = lines.slice(1, closing).filter(line => !/^version\s*:/.test(line));
+    return [lines[0], ...block, stamp, ...lines.slice(closing)].join('\n');
+}
+/** The version recorded in a `SKILL.md` frontmatter, when it carries one. */
+export function frontmatterVersion(markdown) {
+    const lines = markdown.split('\n');
+    if (lines[0]?.trim() !== '---')
+        return null;
+    const closing = lines.findIndex((line, index) => index > 0 && line.trim() === '---');
+    if (closing === -1)
+        return null;
+    for (const line of lines.slice(1, closing)) {
+        const match = /^version\s*:\s*(\S+)\s*$/.exec(line);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+function parseVersionStamp(content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        // A corrupt stamp is disposable state; the frontmatter answers instead.
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const version = value.version;
+    return typeof version === 'string' && version ? version : null;
+}
+/**
+ * The file manifest a previous install recorded in its stamp.
+ *
+ * Pruning may only ever touch paths this tool wrote itself. A stamp without a
+ * readable manifest (a hand copy, an older release, a mangled file) therefore
+ * parses as `null`, and `pruneRemoved` deletes nothing rather than guessing.
+ */
+function parseInstallManifest(content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        // Same deal as a corrupt version stamp: never prune on a guess.
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const files = value.files;
+    if (!Array.isArray(files))
+        return null;
+    const manifest = new Set();
+    for (const file of files) {
+        if (typeof file !== 'string' || !file)
+            return null;
+        manifest.add(file);
+    }
+    return manifest;
+}
+async function readInstallManifest(destination) {
+    const content = await readFile(join(destination, SKILL_VERSION_FILENAME), 'utf8').catch(() => {
+        // No stamp: nothing was ever recorded, so nothing may be pruned.
+        return null;
+    });
+    return content === null ? null : parseInstallManifest(content);
+}
+/**
+ * Which version of the skill sits in a destination directory.
+ *
+ * Reads the stamp first, then the frontmatter, so a skill installed by hand or
+ * by an older release still reports something the caller can compare.
+ */
+export async function readInstalledSkill(destination) {
+    const stamp = await readFile(join(destination, SKILL_VERSION_FILENAME), 'utf8').catch(() => {
+        // No stamp means an older install or a hand copy. Fall through to the frontmatter.
+        return null;
+    });
+    const stamped = stamp === null ? null : parseVersionStamp(stamp);
+    if (stamped !== null)
+        return { _tag: 'SkillVersion', version: stamped };
+    const markdown = await readFile(join(destination, SKILL_MARKDOWN_FILENAME), 'utf8').catch(() => {
+        // No entry file means no skill is installed for this agent.
+        return null;
+    });
+    if (markdown === null)
+        return { _tag: 'SkillMissing' };
+    const declared = frontmatterVersion(markdown);
+    return declared === null ? { _tag: 'SkillUnversioned' } : { _tag: 'SkillVersion', version: declared };
+}
+/**
+ * A stale installed skill, or `null` when nothing needs saying.
+ *
+ * An absent skill is not stale: the person may not use one. Any other
+ * difference from the running binary is, in both directions, because the two
+ * describe different command sets.
+ */
+export function skillNoticeFor(installed, current, agent) {
+    if (installed._tag === 'SkillMissing')
+        return null;
+    if (installed._tag === 'SkillUnversioned')
+        return { agent, installed: null, current };
+    return installed.version === current ? null : { agent, installed: installed.version, current };
+}
+export function skillNoticeLine(notice) {
+    const installed = notice.installed === null ? 'skill version unknown' : `skill ${notice.installed} installed`;
+    return `${installed}, CLI ${notice.current}. Refresh with: nuxtseo skill install --agent ${notice.agent}`;
+}
+export function parseSkillCheckCache(content) {
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch {
+        // A corrupt cache file is disposable state, not an error: recheck instead.
+        return null;
+    }
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const record = value;
+    if (typeof record.lastCheckedAt !== 'string' || typeof record.cliVersion !== 'string')
+        return null;
+    if (typeof record.installed !== 'object' || record.installed === null)
+        return null;
+    const installed = {};
+    for (const agent of SKILL_AGENTS) {
+        const entry = record.installed[agent];
+        if (typeof entry === 'string' || entry === null)
+            installed[agent] = entry;
+    }
+    return { lastCheckedAt: record.lastCheckedAt, cliVersion: record.cliVersion, installed };
+}
+/**
+ * Whether the filesystem has to be read again.
+ *
+ * A cache from a different binary is never reusable: the binary version is half
+ * of the comparison, so an upgrade must warn on the very next run.
+ */
+export function skillCheckDue(cache, now, current) {
+    if (!cache || cache.cliVersion !== current)
+        return true;
+    const checkedAt = Date.parse(cache.lastCheckedAt);
+    return Number.isNaN(checkedAt) || now.getTime() - checkedAt >= SKILL_CHECK_INTERVAL_MS;
+}
+function skillCheckFile(paths) {
+    return join(paths.directory, SKILL_CHECK_FILENAME);
+}
+async function readSkillCheckCache(paths) {
+    const content = await readFile(skillCheckFile(paths), 'utf8').catch(() => {
+        // A missing cache file is the common first-run case.
+        return null;
+    });
+    return typeof content === 'string' ? parseSkillCheckCache(content) : null;
+}
+async function writeSkillCheckCache(paths, cache) {
+    // Persisting the cache is best effort. A failed write only costs one extra
+    // directory read 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(skillCheckFile(paths), `${JSON.stringify(cache, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    }).catch(() => {
+        // See the comment above: the cache is disposable state.
+        return undefined;
+    });
+}
+function noticeFromCache(cache, current) {
+    for (const agent of SKILL_AGENTS) {
+        const version = cache.installed[agent];
+        if (version === undefined)
+            continue;
+        const installed = version === null
+            ? { _tag: 'SkillUnversioned' }
+            : { _tag: 'SkillVersion', version };
+        const notice = skillNoticeFor(installed, current, agent);
+        if (notice)
+            return notice;
+    }
+    return null;
+}
+/**
+ * One line's worth of "your installed skill is not this binary".
+ *
+ * Costs one cached read per day, and nothing at all when the caller disabled
+ * update checks.
+ */
+export async function checkSkillVersion(options) {
+    if (checksDisabled(options.env))
+        return null;
+    const now = options.now?.() ?? new Date();
+    const cache = await readSkillCheckCache(options.paths);
+    if (cache && !skillCheckDue(cache, now, VERSION))
+        return noticeFromCache(cache, VERSION);
+    const homeDirectory = options.homeDirectory ?? dirname(options.paths.directory);
+    const installed = {};
+    let notice = null;
+    for (const agent of SKILL_AGENTS) {
+        const destination = await resolveSkillTarget(skillDestination(homeDirectory, agent));
+        const state = await readInstalledSkill(destination);
+        if (state._tag === 'SkillMissing')
+            continue;
+        installed[agent] = state._tag === 'SkillVersion' ? state.version : null;
+        notice ??= skillNoticeFor(state, VERSION, agent);
+    }
+    await writeSkillCheckCache(options.paths, {
+        lastCheckedAt: now.toISOString(),
+        cliVersion: VERSION,
+        installed,
+    });
+    return notice;
+}
+function sourceFailure(source, cause) {
+    return fail(EXIT_CODE.infrastructure, `skill_source_unreadable: Could not read the packaged skill at ${source}.\nCause: ${describeIoCause(cause)}.\nReinstall @nuxtseo/cli, then run the command again.`, cause);
+}
+function destinationFailure(destination, cause) {
+    return fail(EXIT_CODE.infrastructure, `skill_install_failed: Could not write the skill to ${destination}.\nCause: ${describeIoCause(cause)}.\nRead the cause above, repair that path, then run the command again.`, cause);
+}
+/**
+ * Remove installed files the previous install recorded and this release no
+ * longer ships.
+ *
+ * A plain recursive copy only adds. A reference file dropped from the package
+ * stays in the install forever and keeps answering an agent that asks for it.
+ * The prune set is the previous stamp's manifest, nothing more: a file the
+ * install never wrote (or cannot prove it wrote) belongs to the person, and
+ * deleting it would destroy data this package never shipped.
+ */
+async function pruneRemoved(destination, keep, recorded) {
+    if (!recorded)
+        return 0;
+    const existing = await collectSkillFiles(destination).catch(() => {
+        // A fresh install has nothing to prune.
+        return [];
+    });
+    let pruned = 0;
+    for (const entry of existing) {
+        if (keep.has(entry.path) || !recorded.has(entry.path))
+            continue;
+        await rm(entry.source, { force: true });
+        pruned += 1;
+    }
+    return pruned;
+}
 export async function installSkill(options) {
     const source = options.sourceDirectory ?? skillSourceDirectory();
     const readable = await stat(source).catch(() => {
@@ -36,21 +361,53 @@ export async function installSkill(options) {
     if (!readable?.isDirectory()) {
         return fail(EXIT_CODE.infrastructure, `skill_source_missing: The packaged skill is missing at ${source}.\nReinstall @nuxtseo/cli, then run the command again.`);
     }
+    const files = await collectSkillFiles(source).catch((cause) => cause);
+    if (!Array.isArray(files))
+        return sourceFailure(source, files);
     const destination = options.target
         ? join(options.target, SKILL_NAME)
         : skillDestination(options.homeDirectory, options.agent);
-    const written = await mkdir(dirname(destination), { recursive: true })
-        .then(() => cp(source, destination, {
-        recursive: true,
-        force: true,
-        filter: (entry) => {
-            const [segment] = relative(source, entry).split('/');
-            return !segment || !SKILL_LOCAL_ONLY.has(segment);
-        },
-    }))
-        .then(() => ok(undefined))
-        .catch(cause => fail(EXIT_CODE.infrastructure, `skill_install_failed: Could not write the skill to ${destination}.\nCheck the directory permissions, then run the command again.`, cause));
-    if (written._tag === 'Err')
-        return written;
-    return ok({ agent: options.agent, source, destination });
+    const resolvedDestination = await resolveSkillTarget(destination);
+    // Read before the stamp is overwritten: the previous install's manifest is
+    // the only proof of what a prune may touch.
+    const previous = await readInstallManifest(resolvedDestination);
+    const keep = new Set([SKILL_VERSION_FILENAME]);
+    const write = async () => {
+        await mkdir(resolvedDestination, { recursive: true });
+        for (const file of files) {
+            const target = join(resolvedDestination, file.path);
+            await mkdir(dirname(target), { recursive: true });
+            if (file.path === SKILL_MARKDOWN_FILENAME)
+                await writeFile(target, stampSkillVersion(await readFile(file.source, 'utf8'), VERSION), 'utf8');
+            else
+                await copyFile(file.source, target);
+            keep.add(file.path);
+        }
+        await writeFile(join(resolvedDestination, SKILL_VERSION_FILENAME), `${JSON.stringify({ version: VERSION, skill: SKILL_NAME, installedAt: new Date().toISOString(), files: [...keep].sort() }, null, 2)}\n`, 'utf8');
+        return await pruneRemoved(resolvedDestination, keep, previous);
+    };
+    const result = await write().then(pruned => ok(pruned)).catch(cause => destinationFailure(resolvedDestination, cause));
+    if (result._tag === 'Err')
+        return result;
+    if (options.paths) {
+        // The freshly installed version is now the answer, so clear the stale
+        // notice the same run rather than a day later. Merge into the recorded
+        // map: another agent's entry still has to answer for its own skill, and
+        // replacing the map would hide its stale warning until the cache expires.
+        const cached = await readSkillCheckCache(options.paths);
+        await writeSkillCheckCache(options.paths, {
+            lastCheckedAt: new Date().toISOString(),
+            cliVersion: VERSION,
+            installed: { ...cached?.installed, [options.agent]: VERSION },
+        });
+    }
+    return ok({
+        agent: options.agent,
+        source,
+        destination,
+        resolvedDestination,
+        version: VERSION,
+        written: files.length,
+        pruned: result.value,
+    });
 }

package/dist/update-check.d.ts

@@ -15,6 +15,11 @@ export interface UpdateCheckOptions {
     env?: Readonly<Record<string, string | undefined>>;
     fetch?: RegistryLatestFetch;
     now?: () => Date;
+    /**
+     * Receives one diagnostic line per stale local artefact, before this check
+     * resolves. The caller owns the stream, so this module never writes to one.
+     */
+    onDiagnostic?: (line: string) => void;
 }
 export declare function isNewerVersion(candidate: string, current: string): boolean;
 export declare function updateNoticeFor(latest: string | null, current: string): UpdateNotice | null;

package/dist/update-check.js

@@ -1,4 +1,5 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { checkSkillVersion, skillNoticeLine } from './skill.js';
 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;
@@ -85,13 +86,28 @@ export async function fetchRegistryLatest(url, signal) {
     const version = body.version;
     return typeof version === 'string' && version ? version : null;
 }
+async function emitSkillNotice(check, onDiagnostic) {
+    const notice = await check.catch(() => {
+        // A local read failure must never break a command. The run continues silently.
+        return null;
+    });
+    if (notice && onDiagnostic)
+        onDiagnostic(skillNoticeLine(notice));
+}
 export async function checkForUpdate(options) {
     if (updateCheckDisabled(options.env))
         return null;
+    // The installed agent skill is the other half of "is this install current".
+    // It runs beside the registry fetch so neither waits for the other.
+    const skillCheck = options.onDiagnostic
+        ? checkSkillVersion({ paths: options.paths, env: options.env, now: options.now })
+        : Promise.resolve(null);
     const now = options.now?.() ?? new Date();
     const cache = await readUpdateCheckCache(options.paths);
-    if (!updateCheckDue(cache, now))
+    if (!updateCheckDue(cache, now)) {
+        await emitSkillNotice(skillCheck, options.onDiagnostic);
         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.
@@ -99,6 +115,7 @@ export async function checkForUpdate(options) {
     });
     if (latest !== null)
         await writeUpdateCheckCache(options.paths, { lastCheckedAt: now.toISOString(), latest });
+    await emitSkillNotice(skillCheck, options.onDiagnostic);
     // A stale cached answer still beats no answer while the registry is unreachable.
     return updateNoticeFor(latest ?? cache?.latest ?? null, VERSION);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtseo/cli",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Command line interface for the NuxtSEO public API.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com/pro",
@@ -32,8 +32,9 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@clack/prompts": "^1.7.0",
-    "@nuxtseo/sdk": "^0.2.0",
+    "@clack/prompts": "^1.8.0",
+    "@nuxtseo/protocol": "^0.3.0",
+    "@nuxtseo/sdk": "^0.3.0",
     "citty": "^0.2.2",
     "pathe": "^2.0.3"
   },
@@ -42,10 +43,9 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@nuxtseo/protocol": "0.2.0",
-    "@types/node": "^26.4.0",
+    "@types/node": "^26.5.1",
     "publint": "^0.3.24",
-    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.15.tsgo.7.0.2"
+    "typescript": "npm:typescript-native-bridge@6.0.3-bridge.16.tsgo.7.0.2"
   },
   "publishConfig": {
     "access": "public"

package/skills/nuxtseo-cli/SKILL.md

@@ -71,7 +71,8 @@ accessible Site with its ID.
 
 ## How to call it as an agent
 
-Always pass `--json` and `--site <site-id>`.
+Always pass `--json`. Pass `--site <site-id>` for Site commands.
+`feedback submit` needs no Site.
 
 ```sh
 nuxtseo actions list --site site_123 --json
@@ -81,6 +82,20 @@ nuxtseo actions list --site site_123 --json
 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
@@ -128,6 +143,7 @@ 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
@@ -137,12 +153,44 @@ Triage progress:
 - [ ] 7. annotations create: mark the day the fix shipped
 ```
 
+**Step 0. Check this skill matches the binary.**
+
+```sh
+nuxtseo --version --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
+```
+
+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
 ```
 
+If you need the whole Site rather than the next action, start with `pull`
+instead:
+
+```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
@@ -267,6 +315,41 @@ merge them.
 `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.
 
+## 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.
+
+```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." \
+  --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`,
@@ -284,10 +367,20 @@ to join against. That is a coverage gap, not healthy indexing. Say which.
   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`,