@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/clients/cli/commands/theme-add.doc.mjs

@@ -41,7 +41,7 @@ export const doc = {
   examples: [
     {label: 'Scaffold a theme', cli: 'astryx theme add matcha'},
     {
-      label: 'Select an integration theme',
+      label: 'Pick the owner when two packages ship the same slug',
       cli: 'astryx theme add ocean --package @acme/themes',
     },
   ],

package/clients/cli/commands/theme-palette-generate.doc.mjs

@@ -35,12 +35,13 @@ export const doc = {
     {
       flag: '--preview <path>',
       param: 'options.preview',
-      description: 'Write a standardized self-contained HTML preview',
+      description: 'Write a self-contained HTML preview page; the path must end in .html',
     },
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
-      description: 'Replace existing candidate and receipt files',
+      description:
+        'Replace existing candidate, receipt, and preview files. Without it, if any of them exists, nothing is written',
     },
   ],
   examples: [

package/clients/cli/commands/theme-palette.doc.mjs

@@ -8,8 +8,7 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Create and work with theme-owned color palettes',
   description:
-    'Palette authoring tools. The initial generate command creates reviewable candidates. ' +
-    'Palette inspection and diagnostic commands are intentionally deferred to follow-up work.',
+    'Palette authoring tools. generate writes a palette candidate for you to review before a theme uses it.',
   subcommands: ['generate'],
   examples: [
     {

package/clients/cli/commands/theme-targets.doc.mjs

@@ -20,8 +20,8 @@ export const doc = {
     'the component that declares it, and the props and states that are legal override keys ' +
     'under it. This is the whole themeable surface in one command: what auditing a theme, or ' +
     'answering "which key paints this pixel?", used to need one `astryx component <Name>` per ' +
-    'component to assemble. Pass a component name to scope it; pass any substring to search ' +
-    'keys. `--json` for a list a repo can lint its own theme against.',
+    'component to assemble. Pass a component name to scope it; pass any other text to search ' +
+    'target keys, classes, and components. `--json` for a list a repo can lint its own theme against.',
   fn: 'themeTargets',
   args: [{name: 'filter', param: 'filter', required: false}],
   examples: [

package/clients/cli/commands/theme.doc.mjs

@@ -13,7 +13,8 @@ export const doc = {
   name: 'theme',
   displayName: 'astryx theme',
   namespace: 'cli/commands',
-  summary: 'Theme tools: build, export, and manage themes',
+  summary:
+    'Create and build themes: add a shipped one, compile to CSS, or list what a theme can override',
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +
     'subcommand list; the work happens in the subcommands: compile a theme (build), ' +

package/clients/cli/commands/upgrade.ascii-output.test.mjs

@@ -84,4 +84,18 @@ describe('upgrade human output is ASCII', () => {
       'minSize: 200',
     );
   });
+
+  // Every fixture above has a real src/, so the completion line for a project
+  // whose source is somewhere else was never reached — this suite was green on
+  // that path by luck, not by coverage.
+  it('reports a source directory that does not exist', async () => {
+    fs.rmSync(path.join(tmpDir, 'src'), {recursive: true, force: true});
+    fs.mkdirSync(path.join(tmpDir, 'app'), {recursive: true});
+    write('app/panel.tsx', 'export const x = 1;\n');
+
+    expect(await nonAsciiLines(['upgrade', '--from', '0.5.0'])).toEqual([]);
+    expect(
+      await nonAsciiLines(['upgrade', '--from', '0.5.0', '--apply']),
+    ).toEqual([]);
+  });
 });

package/clients/cli/commands/upgrade.doc.mjs

@@ -13,7 +13,8 @@ export const doc = {
   name: 'upgrade',
   displayName: 'astryx upgrade',
   namespace: 'cli/commands',
-  summary: 'Migrate versions and update ShadCN-copied compositions',
+  summary:
+    'Update your code after upgrading Astryx, and refresh ShadCN-copied components',
   description:
     'Migrates project source from a previous Astryx version to the installed one by ' +
     'running the registered codemods, and refreshes the fully rendered managed ' +
@@ -33,7 +34,7 @@ export const doc = {
     {
       flag: '--apply',
       param: 'options.apply',
-      description: 'Write changes to disk (default: dry-run)',
+      description: 'Write changes to disk; without it, the run is a dry run',
       default: false,
     },
     {
@@ -80,7 +81,8 @@ export const doc = {
       flag: '--registry',
       param: 'options.registry',
       description:
-        'Only reconcile ShadCN-copied compositions; --from is not required. ' +
+        'Only update ShadCN-copied compositions from their install receipts: unchanged files are updated, ' +
+        'edits that do not overlap are merged, and conflicts are left untouched; --from is not required. ' +
         'Combining it with --list, --from, --force, --codemod, --skip-codemod, --integration or --install-deps exits 1 with ERR_INVALID_ARGUMENT',
       default: false,
     },
@@ -113,4 +115,61 @@ export const doc = {
     },
   ],
   related: ['init', 'doctor'],
+  notes: [
+    {type: 'heading', level: 3, text: 'Protected files'},
+    {
+      type: 'prose',
+      text:
+        'Codemods never write to a file your project marks as generated, vendored, or ignored. ' +
+        'upgrade reads these marks from the files on disk, so the answer is the same with any version control, or none. ' +
+        'A file is protected when:',
+    },
+    {
+      type: 'list',
+      style: 'unordered',
+      items: [
+        'a `.gitattributes` file marks it `linguist-generated` or `linguist-vendored`',
+        'its leading comment says `@generated`, `@partially-generated`, or `Code generated ... DO NOT EDIT.`',
+        'a `.gitignore`, or the `.hgignore` at the project root, excludes it',
+        'it is an installed dependency (such as anything in `node_modules`), is inside `.git`, `.hg`, or `.sl`, is a symbolic link, or is outside the project',
+      ],
+    },
+    {
+      type: 'prose',
+      text:
+        'Rules work as they do in Git: a later rule wins, so `linguist-generated=false` or a `!` line in an ignore file ' +
+        'returns a file to normal handling. A folder name such as `dist` or `generated` protects nothing by itself. ' +
+        'If a protection file cannot be read or parsed, upgrade stops with ERR_CODEMOD_PROTECTION_SOURCE before it writes anything.',
+    },
+    {
+      type: 'code',
+      lang: 'text',
+      code:
+        '# .gitattributes\n' +
+        'generated/** linguist-generated=true\n' +
+        'vendor/** linguist-vendored=true\n' +
+        '\n' +
+        '# A later rule returns one authored file to normal handling\n' +
+        'generated/hand-authored.ts linguist-generated=false',
+    },
+    {
+      type: 'prose',
+      text:
+        'When a codemod would change a protected file, upgrade makes the change only in memory and leaves the file as it is. ' +
+        'The rest of the upgrade goes ahead. With --apply, your other files are written, then upgrade runs the ' +
+        '`hooks.postCodemod` commands from astryx.config (see `astryx docs authoring config`) and checks the protected ' +
+        'files again. If one still needs the change, the run is incomplete: it exits 1, prints ' +
+        'ERR_CODEMOD_PROTECTED with each file and the rule that protects it, and does not refresh the agent docs. ' +
+        'Regenerate or edit those files, then run the same upgrade again. A dry run reports the same files and writes nothing.',
+    },
+    {
+      type: 'prose',
+      text:
+        'With --json, the receipt says `complete: false` and `errorCode: "ERR_CODEMOD_PROTECTED"`. `modifiedFiles` lists the files ' +
+        'upgrade changed (or would change), and `protectedFiles` lists each blocked file with its `reasons`, `declarations` ' +
+        '(the rules that protect it), `codemods`, and `commands`. A generated file can name the command that rebuilds it on a ' +
+        '`Command:` line in its header, such as `// Command: pnpm run gen:panel`; upgrade prints it as ' +
+        '`Regenerate with: <command>` and lists it in `commands`.',
+    },
+  ],
 };

package/clients/cli/commands/write-failure.test.mjs

@@ -0,0 +1,175 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A write that fails on the filesystem reports ERR_WRITE_FAILED.
+ *
+ * An unwritable target produced `{"error": "EACCES: permission denied, open
+ * '/abs/host/path/readonly/x.tsx'", "code": "ERR_UNKNOWN"}` — the raw Node
+ * errno error, with the wrong code and an absolute host path in the message.
+ * ERR_WRITE_FAILED is in the frozen registry for exactly this case, and every
+ * other Astryx message names its target relative to the project.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');
+
+// chmod means nothing to root, so the unwritable directory would be writable
+// and the command would succeed. Skip rather than assert something false.
+const asRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+
+let dir;
+let readonlyDir;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-write-fail-'));
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({
+      name: 'scratch',
+      version: '1.0.0',
+      dependencies: {'@astryxdesign/core': '0.6.3'},
+    }),
+  );
+  fs.mkdirSync(path.join(dir, 'node_modules', '@astryxdesign'), {recursive: true});
+  fs.symlinkSync(
+    path.join(REPO, 'packages', 'core'),
+    path.join(dir, 'node_modules', '@astryxdesign', 'core'),
+    'dir',
+  );
+  readonlyDir = path.join(dir, 'readonly');
+  fs.mkdirSync(readonlyDir);
+  fs.chmodSync(readonlyDir, 0o500);
+});
+
+afterEach(() => {
+  try {
+    fs.chmodSync(readonlyDir, 0o700);
+  } catch {
+    // already gone
+  }
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+/** @param {string[]} args */
+const json = async args => {
+  const {status, stdout} = await runCli(['--json', ...args], {cwd: dir});
+  return {status, body: JSON.parse(stdout)};
+};
+
+describe.skipIf(asRoot)('a failed write reports ERR_WRITE_FAILED', () => {
+  it('template into an unwritable directory', async () => {
+    const {status, body} = await json(['template', 'ai-chat', 'readonly/x.tsx']);
+
+    expect(status).toBe(1);
+    expect(body.code).toBe('ERR_WRITE_FAILED');
+    expect(body.error).toContain('readonly/x.tsx');
+    expect(body.error).toContain('EACCES');
+    // The whole point of the relative form: no absolute host path escapes.
+    expect(body.error).not.toContain(dir);
+    expect(fs.existsSync(path.join(readonlyDir, 'x.tsx'))).toBe(false);
+  });
+
+  it('swizzle into an unwritable directory', async () => {
+    const {status, body} = await json([
+      'swizzle',
+      'Button',
+      '--output',
+      'readonly/sub',
+    ]);
+
+    expect(status).toBe(1);
+    expect(body.code).toBe('ERR_WRITE_FAILED');
+    expect(body.error).toContain('readonly/sub');
+    expect(body.error).not.toContain(dir);
+    expect(fs.existsSync(path.join(readonlyDir, 'sub'))).toBe(false);
+  });
+
+  it('still writes normally into a writable directory', async () => {
+    const {status, body} = await json(['template', 'ai-chat', 'src/page.tsx']);
+
+    expect(status, JSON.stringify(body).slice(0, 200)).toBe(0);
+    expect(body.type).toBe('template.copy');
+    expect(fs.existsSync(path.join(dir, 'src', 'page.tsx'))).toBe(true);
+  });
+});
+
+describe.skipIf(asRoot)('a swizzle that fails part-way undoes what it wrote', () => {
+  it('restores replaced files, removes created ones, and says nothing was written', async () => {
+    // Learn the component's files, in copy order, from a successful swizzle.
+    const probe = await json(['swizzle', 'Button', '--output', 'probe']);
+    expect(probe.status, JSON.stringify(probe.body).slice(0, 200)).toBe(0);
+    const files = probe.body.data.files;
+    expect(files.length).toBeGreaterThan(1);
+    const outDir = path.join(dir, 'out', path.basename(probe.body.data.outputDir));
+
+    // The first file exists (replaceable), the middle ones do not, and the
+    // last one is read-only, so --overwrite fails after writing the others.
+    const first = files[0];
+    const middle = files.slice(1, -1);
+    const last = files[files.length - 1];
+    fs.mkdirSync(outDir, {recursive: true});
+    fs.writeFileSync(path.join(outDir, first), 'before first\n');
+    fs.writeFileSync(path.join(outDir, last), 'before last\n');
+    fs.chmodSync(path.join(outDir, last), 0o444);
+
+    const {status, body} = await json([
+      'swizzle',
+      'Button',
+      '--output',
+      'out',
+      '--overwrite',
+    ]);
+    fs.chmodSync(path.join(outDir, last), 0o644);
+
+    expect(status).toBe(1);
+    expect(body.code).toBe('ERR_WRITE_FAILED');
+    expect(body.error).toContain(last);
+    expect(body.error).toContain('Nothing was written.');
+    expect(body.error).not.toContain(dir);
+    expect(fs.readFileSync(path.join(outDir, first), 'utf8')).toBe('before first\n');
+    expect(fs.readFileSync(path.join(outDir, last), 'utf8')).toBe('before last\n');
+    for (const file of middle) {
+      expect(fs.existsSync(path.join(outDir, file))).toBe(false);
+    }
+  });
+
+  it('undoes the copy when a destination cannot be read back', async () => {
+    const probe = await json(['swizzle', 'Button', '--output', 'probe']);
+    expect(probe.status, JSON.stringify(probe.body).slice(0, 200)).toBe(0);
+    const files = probe.body.data.files;
+    const outDir = path.join(dir, 'out', path.basename(probe.body.data.outputDir));
+
+    // A directory where the last file goes: the rollback snapshot cannot read
+    // it, and the earlier files are already written when the copy reaches it.
+    const first = files[0];
+    const middle = files.slice(1, -1);
+    const last = files[files.length - 1];
+    fs.mkdirSync(path.join(outDir, last), {recursive: true});
+    fs.writeFileSync(path.join(outDir, first), 'before first\n');
+
+    const {status, body} = await json([
+      'swizzle',
+      'Button',
+      '--output',
+      'out',
+      '--overwrite',
+    ]);
+
+    expect(status).toBe(1);
+    expect(body.code).toBe('ERR_WRITE_FAILED');
+    expect(body.error).toContain(last);
+    expect(body.error).toContain('Nothing was written.');
+    expect(body.error).not.toContain(dir);
+    expect(fs.readFileSync(path.join(outDir, first), 'utf8')).toBe('before first\n');
+    expect(fs.statSync(path.join(outDir, last)).isDirectory()).toBe(true);
+    for (const file of middle) {
+      expect(fs.existsSync(path.join(outDir, file))).toBe(false);
+    }
+  });
+});

package/clients/cli/index.mjs

@@ -24,7 +24,7 @@ import {emit, section, text, records} from './formatters/index.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {installJsonShim} from './lib/json-shim.mjs';
-import {addExitCodesHelp, markReportsResult} from './lib/define-command.mjs';
+import {addDocHelp, markReportsResult} from './lib/define-command.mjs';
 import {doc as manifestDoc} from './commands/manifest.doc.mjs';
 import {isAstryxInitialized} from '../../foundation/agent-docs/agent-docs.mjs';
 import * as debug from '../../foundation/debug/index.mjs';
@@ -95,6 +95,7 @@ export const JSON_SUPPORTED = new Set([
   'theme targets',
   'theme palette generate',
   'integration add',
+  'integration verify',
   'integration pack',
   'upgrade',
   'manifest',
@@ -342,16 +343,24 @@ export async function createProgram() {
     .name('astryx')
     .description('Design system CLI — components, themes, and tooling')
     .version(pkg.version)
-    .option('--zh', 'Output docs in Chinese Simplified')
-    .option('--dense', 'Output docs in compressed dense format (token-efficient)')
+    // These four change only the reads named in their text; every other
+    // command ignores them.
+    .option(
+      '--zh',
+      'Simplified Chinese for component reads and for docs topics that have a translation (English otherwise)',
+    )
+    .option('--dense', 'Token-efficient dense text for component <Name> and docs <topic> reads')
     .addOption(
       new Option(
         '--lang <locale>',
-        'Output docs in specified language/format (en, zh, dense)',
+        'Language or format for component and docs reads: en (default), zh (as --zh), or dense (as --dense)',
       ).choices(['en', 'zh', 'dense']),
     )
     .addOption(
-      new Option('--detail <level>', 'Output detail level (full, compact, brief)')
+      new Option(
+        '--detail <level>',
+        'Detail level for component, hook, and docs tree reads (e.g. docs cli/commands/build). Lists default to brief',
+      )
         .choices(['full', 'compact', 'brief'])
         .default('full'),
     )
@@ -471,6 +480,19 @@ export async function createProgram() {
     const fullName = fullCommandName(actionCommand, program);
     if (JSON_SUPPORTED.has(fullName)) return;
     process.__xdsJsonHandled = true;
+    // A group given a word it does not have reports an unknown subcommand and
+    // lists the ones it has, in JSON as in text, even when a flag follows it.
+    const extras = actionCommand.commands.length > 0 ? actionCommand.args : [];
+    const unknown = extras.find(arg => !String(arg).startsWith('-'));
+    if (unknown != null) {
+      cliError(`unknown subcommand '${fullName} ${unknown}'`, {
+        code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
+        suggestions: actionCommand.commands.map(child => ({
+          name: child.name(),
+          reason: 'available subcommand',
+        })),
+      });
+    }
     debug.setOutcome('rejected', {
       exitCode: 1,
       code: ERROR_CODES.ERR_INVALID_OPTION,
@@ -605,7 +627,7 @@ export async function createProgram() {
         text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
       );
     });
-  addExitCodesHelp(manifestCommand, manifestDoc.exitCodes);
+  addDocHelp(manifestCommand, manifestDoc);
   markReportsResult(manifestCommand);
 
   // Hidden command used by package.json postinstall scripts

package/clients/cli/lib/define-command.mjs

@@ -25,6 +25,8 @@
  */
 
 import {recordCommandResult} from '../../../foundation/debug/index.mjs';
+import {routeSegment} from '../../../foundation/discovery/docs-section-key.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
 import {text} from '../formatters/index.mjs';
 
 /**
@@ -143,10 +145,11 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
     cmd.addOption(option);
   }
 
-  // Help ends with the documented exit codes. `choices` stay in the option
-  // text: Commander `.choices()` would replace the api layer's
-  // ERR_INVALID_ARGUMENT validation.
-  addExitCodesHelp(cmd, doc.exitCodes);
+  // Help ends with the documented exit codes, the examples, and the docs
+  // route that reads the whole command. `choices` stay in the option text:
+  // Commander `.choices()` would replace the api layer's ERR_INVALID_ARGUMENT
+  // validation.
+  addDocHelp(cmd, doc);
 
   if (action) {
     // The recording seam. An action's job ends at "here is what I answered
@@ -165,6 +168,27 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
   return cmd;
 }
 
+/**
+ * End `cmd`'s help with what its CommandDoc says: the exit codes, then the
+ * examples, then `More:`, the `astryx docs` route that reads the whole command.
+ * @param {import('commander').Command} cmd
+ * @param {import('@astryxdesign/cli/authoring').CommandDoc} doc
+ */
+export function addDocHelp(cmd, doc) {
+  addExitCodesHelp(cmd, doc.exitCodes);
+  // Rendered when help is shown, so the run prefix (npx astryx, pnpm astryx,
+  // ...) is looked up then, not on every start.
+  cmd.addHelpText('after', () => {
+    const examples = (doc.examples ?? []).flatMap(({label, cli}) => [
+      ...(label ? [`  # ${label}`] : []),
+      `  ${formatCliCommand(cli)}`,
+    ]);
+    const more = `More: ${formatCliCommand(`docs cli/commands/${routeSegment(doc.name)}`)}`;
+    const blocks = examples.length > 0 ? [['Examples:', ...examples].join('\n'), more] : [more];
+    return `\n${text(blocks.join('\n\n')).toString()}`;
+  });
+}
+
 /**
  * End `cmd`'s help with a CommandDoc's exit codes.
  * @param {import('commander').Command} cmd

package/clients/cli/lib/define-command.test.mjs

@@ -7,6 +7,7 @@
 import {Command} from 'commander';
 import {describe, it, expect} from 'vitest';
 import {defineCommand} from './define-command.mjs';
+import {formatCliCommand} from '../../../foundation/env/package-manager.mjs';
 import {doc as searchCommand} from '../commands/search.doc.mjs';
 import {doc as searchFn} from '../../../api/search/search.doc.mjs';
 
@@ -46,4 +47,57 @@ describe('defineCommand', () => {
     expect(cmd.name()).toBe('build');
     expect(cmd.registeredArguments.map(a => a.name())).toEqual(['file']);
   });
+
+  it('ends help with the exit codes, the examples, and the docs route', () => {
+    const program = new Command();
+    const group = program.command('grp');
+    const cmd = defineCommand(
+      group,
+      {
+        type: 'command',
+        name: 'grp sub',
+        displayName: 'astryx grp sub',
+        summary: 'Sub.',
+        examples: [
+          {label: 'Run it', cli: 'astryx grp sub x'},
+          {cli: 'astryx grp sub y --json'},
+        ],
+        exitCodes: [{code: 0, when: 'it works'}],
+      },
+      {action: () => {}},
+    );
+    let out = '';
+    cmd.configureOutput({writeOut: s => (out += s)});
+    cmd.outputHelp();
+    const stem = formatCliCommand('');
+    expect(out.slice(out.indexOf('\nExit codes:\n'))).toBe(
+      [
+        '',
+        'Exit codes:',
+        '  0  it works',
+        '',
+        'Examples:',
+        '  # Run it',
+        `  ${stem} grp sub x`,
+        `  ${stem} grp sub y --json`,
+        '',
+        `More: ${stem} docs cli/commands/grp-sub`,
+        '',
+      ].join('\n'),
+    );
+  });
+
+  it('still names the docs route when a command has no examples', () => {
+    const program = new Command();
+    const cmd = defineCommand(
+      program,
+      {type: 'command', name: 'solo', summary: 'Solo.', exitCodes: [{code: 0, when: 'ok'}]},
+      {action: () => {}},
+    );
+    let out = '';
+    cmd.configureOutput({writeOut: s => (out += s)});
+    cmd.outputHelp();
+    expect(out).not.toContain('Examples:');
+    expect(out.endsWith(`\n\nMore: ${formatCliCommand('docs cli/commands/solo')}\n`)).toBe(true);
+  });
 });

package/clients/cli/lib/exit-codes.test.mjs

@@ -41,7 +41,7 @@ describe('command exit codes', () => {
   });
 
   it.each(commandDocs.map((d) => [d.name, d]))(
-    '`astryx %s --help` lists the documented exit codes',
+    '`astryx %s --help` lists the documented exit codes, then the examples and the docs route',
     async (name, doc) => {
       const {status, stdout} = await runCli([...name.split(' '), '--help']);
       expect(status).toBe(0);
@@ -51,6 +51,22 @@ describe('command exit codes', () => {
       for (const {code, when} of doc.exitCodes) {
         expect(section).toContain(`\n  ${code}  ${when}\n`);
       }
+      // Examples follow the exit codes, each under its label, and a `More:`
+      // line names the route that reads the whole command.
+      const examples = section.indexOf('\nExamples:\n');
+      expect(examples > 0, stdout).toBe((doc.examples ?? []).length > 0);
+      for (const {label, cli} of doc.examples ?? []) {
+        const line = ` ${cli.replace(/^astryx\s+/, '')}\n`;
+        expect(section.slice(examples), stdout).toContain(
+          label ? `\n  # ${label}\n` : line,
+        );
+        expect(section.slice(examples)).toContain(line);
+      }
+      const route = `docs cli/commands/${name.replace(/ /g, '-')}`;
+      expect(section, stdout).toMatch(
+        new RegExp(`\\n\\nMore: \\S.* ${route}\\n`),
+      );
+      expect(section.indexOf('\nMore: ')).toBeGreaterThan(examples);
     },
   );
 

package/clients/cli/lib/json-shim.mjs

@@ -33,10 +33,12 @@
  *      shows help because the invocation failed (`help <unknown>`, or a
  *      command group with no subcommand), which exits 1.
  *
- * Non-JSON behavior is preserved exactly: every code path that printed
- * to stderr before still prints to stderr. Commander writes its
- * "error: ..." line via configureOutput.writeErr, which we pass
- * through verbatim outside of --json mode.
+ * Commander writes its own "error: ..." line via configureOutput.writeErr.
+ * The shim drops that line in both modes. Under --json the error envelope
+ * replaces it; in text mode `handleCommanderError` writes the Astryx line
+ * instead (`Error: <message>`, the same message the envelope carries), so
+ * a parse failure reads like every other CLI error. Other stderr output,
+ * such as help printed as the failure report, still passes through.
  */
 
 import {API_VERSION, isJsonMode, toErrorEnvelope} from '../../../foundation/response/json.mjs';
@@ -249,11 +251,20 @@ function applyShimRecursively(cmd) {
   });
   cmd.configureOutput({
     writeOut: (str) => process.stdout.write(str),
+    // Commander's own "error: ..." line never reaches the user. Under --json a
+    // consumer parsing both streams must not see it alongside the envelope;
+    // in text mode it is Commander's format, not Astryx's, so an invalid
+    // global option (`--lang zh-Hans`) printed `error: option '--lang
+    // <locale>' argument 'zh-Hans' is invalid…` where every other CLI error
+    // prints `Error: …`. handleCommanderError writes the Astryx line below,
+    // for both modes, from the same message.
+    //
+    // ONLY that line. Commander also writes HELP through this channel when it
+    // shows help because the invocation failed (a command group with no
+    // subcommand), and that output is still wanted in text mode.
     writeErr: (str) => {
-      // Suppress Commander's "error: ..." stderr line when --json is
-      // active, so a JSON consumer parsing both streams doesn't see
-      // it alongside the envelope. Non-JSON callers are unaffected.
       if (jsonActive()) return;
+      if (/^error:\s/i.test(str)) return;
       process.stderr.write(str);
     },
   });
@@ -432,16 +443,15 @@ export function handleCommanderError(err) {
     code: commanderCodeToErrorCode(code, message),
   });
 
-  // Real error paths.
+  // Real error paths. Strip Commander's "error: " prefix once: in the envelope
+  // the key is already `error`, and in text mode the Astryx prefix replaces it.
+  const cleaned = message.replace(/^error:\s*/i, '');
   if (jsonActive()) {
-    // Strip Commander's "error: " prefix — the envelope key is `error`
-    // already, doubled "error" is noise.
-    const cleaned = message.replace(/^error:\s*/i, '');
     emitJsonError(cleaned, undefined, commanderCodeToErrorCode(code, cleaned));
   } else {
-    // Non-JSON mode: Commander already wrote the "error: ..." line
-    // to stderr via configureOutput.writeErr before throwing the
-    // CommanderError. Nothing to do — exit with the original code.
+    // Commander's own line was suppressed above, so a parse failure reads the
+    // same as every other CLI error — the `Error: …` line cliError prints.
+    process.stderr.write(`Error: ${cleaned}\n`);
   }
   process.exit(exitCode || 1);
 }