@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

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.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/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);
 }

package/clients/cli/lib/manifest.mjs

@@ -14,7 +14,8 @@
  * `type` discriminators it can emit — are layered on from:
  *
  *   - JSON_SUPPORTED  (the allowlist in index.mjs), and
- *   - RESPONSE_TYPES  (the declarative map below).
+ *   - RESPONSE_TYPES  (the declarative map below; ROOT_RESPONSE_TYPES names the
+ *     two, help and version, that no single command owns).
  *
  * A drift-guard test (manifest.test.mjs) asserts every registered command
  * appears in the manifest and every JSON-supported command has a response-type
@@ -51,6 +52,7 @@ export const RESPONSE_TYPES = {
   init: ['init.run', 'init.remove'],
   component: [
     'component.list',
+    'component.batch',
     'component.detail',
     'component.detail.props',
     'component.detail.source',
@@ -69,6 +71,7 @@ export const RESPONSE_TYPES = {
     'discover.list',
     'discover.detail',
     'discover.detail.doc',
+    'discover.item',
     'discover.search',
   ],
   search: ['search'],
@@ -90,8 +93,9 @@ export const RESPONSE_TYPES = {
   'theme targets': ['theme.targets'],
   'theme palette generate': ['theme.palette.generate'],
   'integration add': ['integration.add'],
+  'integration verify': ['integration.pack-check'],
   'integration pack': ['integration.pack-check'],
-  upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
+  upgrade: ['upgrade.list', 'upgrade.registry', 'upgrade.status', 'upgrade.run'],
   manifest: ['manifest'],
   doctor: ['doctor'],
   'doctor integration validate': ['integration.validate'],
@@ -103,6 +107,14 @@ export const RESPONSE_TYPES = {
   'layout grammar': ['layout.grammar'],
 };
 
+/**
+ * Response types no single command owns: `help` (a bare `astryx --json`, and
+ * `--help --json` on any command) and `version` (`astryx --version --json`).
+ * The response-types enum lists them beside {@link RESPONSE_TYPES}.
+ * @type {readonly string[]}
+ */
+export const ROOT_RESPONSE_TYPES = Object.freeze(['help', 'version']);
+
 /**
  * Example invocations per fully-qualified command. Optional, agent-facing.
  * @type {Record<string, string[]>}
@@ -111,6 +123,7 @@ const EXAMPLES = {
   component: [
     'astryx component',
     'astryx component XDSButton',
+    'astryx component Button Badge Text',
     'astryx component XDSButton --props --json',
   ],
   docs: [
@@ -118,7 +131,7 @@ const EXAMPLES = {
     'astryx docs spacing --json',
     'astryx docs theme',
     'astryx docs theme quick-start',
-    'astryx docs cli/integrations --full',
+    'astryx docs cli/integrations/quick-start --full',
   ],
   discover: ['astryx discover --json'],
   search: [
@@ -126,7 +139,7 @@ const EXAMPLES = {
     'astryx search button --type component --json',
   ],
   build: ['astryx build', 'astryx build "analytics dashboard" --json'],
-  swizzle: ['astryx swizzle XDSButton'],
+  swizzle: ['astryx swizzle Button'],
   'gap-report': [
     'astryx gap-report --list-categories',
     "astryx gap-report Button --category docs_gap --reason 'Missing keyboard example'",
@@ -159,7 +172,7 @@ const EXAMPLES = {
     'astryx integration add component AcmeWidget',
     'astryx integration add doc deploying --dry-run --json',
   ],
-  'integration pack': ['astryx integration pack --check --json'],
+  'integration verify': ['astryx integration verify --json'],
   upgrade: ['astryx upgrade --json'],
   manifest: ['astryx manifest --json', 'astryx --json'],
   doctor: ['astryx doctor', 'astryx doctor --json'],

package/clients/cli/lib/manifest.test.mjs

@@ -156,7 +156,10 @@ describe('manifest: shape', () => {
 
   it('derives arguments from Commander metadata', () => {
     const component = allEntries.find((c) => c.name === 'component');
-    expect(component.arguments.map((a) => a.name)).toContain('name');
+    const names = component.arguments.find((a) => a.name === 'names');
+    expect(names.required).toBe(false);
+    expect(names.variadic).toBe(true);
+    expect(names.description).toContain('Two or more return one ordered batch');
     const themeBuild = allEntries.find((c) => c.name === 'theme build');
     expect(themeBuild.arguments.map((a) => a.name)).toContain('files');
     const files = themeBuild.arguments.find((a) => a.name === 'files');
@@ -193,7 +196,7 @@ describe('manifest: e2e', () => {
     // Enriched: the full structured manifest is embedded.
     expect(parsed.data.manifest).toBeDefined();
     expect(parsed.data.manifest.commands.find((c) => c.name === 'component').responseTypes)
-      .toContain('component.list');
+      .toEqual(expect.arrayContaining(['component.list', 'component.batch']));
   });
 });
 

package/clients/cli/lib/parse-error-format.test.mjs

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A parse failure reads like every other Astryx error in text mode.
+ *
+ * `astryx theme list --lang zh-Hans` printed Commander's own line —
+ * `error: option '--lang <locale>' argument 'zh-Hans' is invalid…` — while
+ * every other CLI error prints `Error: …`. `--json` was already correct
+ * (ERR_INVALID_LANG), so text and JSON disagreed on everything except the exit
+ * code. Commander writes that line before any Astryx code runs, so the shim is
+ * the only place that can speak for it.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {Command} from 'commander';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {installJsonShim} from './json-shim.mjs';
+
+describe('a parse error prints the Astryx error format', () => {
+  it.each([
+    ['invalid --lang value', ['theme', 'list', '--lang', 'zh-Hans'], 'ERR_INVALID_LANG'],
+    ['invalid --detail value', ['theme', 'list', '--detail', 'nope'], 'ERR_INVALID_DETAIL'],
+    ['unknown option', ['component', '--bogus-flag'], 'ERR_INVALID_OPTION'],
+    ['missing argument', ['theme', 'build'], 'ERR_MISSING_ARGUMENT'],
+  ])('%s', async (_label, args, code) => {
+    const human = await runCli(args);
+
+    expect(human.status).toBe(1);
+    expect(human.stderr).toContain('Error: ');
+    // Commander's own lowercase line must not reach the user.
+    expect(human.stderr).not.toMatch(/(^|\n)error: /);
+
+    // --json is unchanged, and the two modes agree on the exit code.
+    const json = await runCli(['--json', ...args]);
+    expect(json.status).toBe(human.status);
+    expect(JSON.parse(json.stdout).code).toBe(code);
+    expect(json.stderr).toBe('');
+  });
+
+  it('carries Commander\'s explanation, not just a generic line', async () => {
+    const {stderr} = await runCli(['theme', 'list', '--lang', 'zh-Hans']);
+    expect(stderr).toContain("'zh-Hans' is invalid");
+    expect(stderr).toContain('en, zh, dense');
+  });
+
+  it('leaves --help and --version at exit 0 with nothing on stderr', async () => {
+    for (const args of [['--help'], ['theme', '--help']]) {
+      const r = await runCli(args);
+      expect(r.status).toBe(0);
+      expect(r.stderr).toBe('');
+    }
+  });
+
+  // Commander writes help through the same stderr channel when it shows help
+  // BECAUSE the invocation failed, so suppressing that channel wholesale would
+  // have taken the help with it. Driven on a throwaway program rather than a
+  // real command, so the guard outlives whichever command happens to have a
+  // subcommand group today.
+  it('still lets help reach stderr when help IS the failure report', () => {
+    const program = new Command('probe');
+    const group = program.command('group');
+    group.command('leaf').action(() => {});
+    installJsonShim(program);
+
+    /** @type {string[]} */
+    const written = [];
+    const original = process.stderr.write;
+    // @ts-expect-error test double for the write signature
+    process.stderr.write = str => {
+      written.push(String(str));
+      return true;
+    };
+    try {
+      group.outputHelp({error: true});
+    } finally {
+      process.stderr.write = original;
+    }
+
+    expect(written.join('')).toMatch(/Usage: probe group/);
+  });
+});

package/foundation/agent-docs/agent-docs.mjs

@@ -491,7 +491,7 @@ export function generateCompressedIndex(
   }
   lines.push('  docs cli           commands, API reference, integration authoring (one level at a time)');
   lines.push('  swizzle <Name>     eject component source for deep customization');
-  lines.push('  upgrade --apply    run after any Astryx or integration dependency bump');
+  lines.push('  upgrade --from <old version> --apply   run after any Astryx or integration dependency bump');
   const appendCount = agentDocs.reduce(
     (count, contribution) => count + contribution.append.length,
     0,

package/foundation/discovery/authoring-self-docs.mjs

@@ -33,6 +33,7 @@ export const AUTHORING_SELF_DOCS = [
   'config/config.doc.mjs',
   'debug/debug.doc.mjs',
   'gap-report/gap-report.doc.mjs',
+  'discover/discover.doc.mjs',
   'codemod/codemod.doc.mjs',
   'identity/identity.doc.mjs',
   'doctypes/base/graph-fields.doc.mjs',