@astryxdesign/cli 0.6.3 → 0.6.4-canary.10dd683

package/clients/cli/index.mjs

@@ -16,7 +16,6 @@ import {Command, Option} from 'commander';
 import {fileURLToPath} from 'node:url';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {checkForUpdate} from './lib/update-check.mjs';
 import {getCliInvocation} from '../../foundation/env/package-manager.mjs';
 import {API_VERSION, setJsonMode} from '../../foundation/response/json.mjs';
 import {buildManifest} from './lib/manifest.mjs';
@@ -25,7 +24,8 @@ 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 {markReportsResult} from './lib/define-command.mjs';
+import {addExitCodesHelp, 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';
 
@@ -275,8 +275,13 @@ const commands = [
   {name: 'doctor', path: './commands/doctor.mjs', register: 'registerDoctor'},
 ];
 
-const UPDATE_HINT_COMMANDS = new Set(['component', 'docs']);
 const SETUP_NUDGE_EXEMPT = new Set(['init', 'agent-docs']);
+/** An integration package's manifest: the package is not an app to set up. */
+const INTEGRATION_MANIFEST_FILES = [
+  'astryx.integration.ts',
+  'astryx.integration.mjs',
+  'astryx.integration.js',
+];
 
 /**
  * Build a fresh, fully-wired Astryx CLI program (root options, hooks, all
@@ -352,7 +357,7 @@ export async function createProgram() {
     )
     .option(
       '--json',
-      'Output as typed JSON. Success envelope: { type, data }. Error envelope: { error, suggestions? }.',
+      'Output as typed JSON. Success envelope: { apiVersion, type, data, meta? }. Error envelope: { apiVersion, error, code, suggestions? }.',
     )
     .addHelpCommand('help', 'Show all commands')
     .action((options, cmd) => {
@@ -499,25 +504,6 @@ export async function createProgram() {
     process.exit(1);
   });
 
-  /**
-   * Post-action hook: print update hint after any command output.
-   * Only fires for commands that produce output agents read (component, docs, etc.).
-   * Suppressed when --json is active to avoid contaminating stdout.
-   */
-  program.hook('postAction', (thisCommand, actionCommand) => {
-    if (program.opts().json) return;
-    try {
-      if (UPDATE_HINT_COMMANDS.has(actionCommand.name())) {
-        const hint = checkForUpdate();
-        if (hint) {
-          console.error(`\n${hint}`);
-        }
-      }
-    } catch {
-      // Never let update check break the CLI
-    }
-  });
-
   /**
    * Enforcement layer 3 — setup nudge. If this project hasn't run `astryx init`
    * yet (no Astryx marker in any agent-doc file — see isAstryxInitialized), remind
@@ -539,6 +525,8 @@ export async function createProgram() {
       if (SETUP_NUDGE_EXEMPT.has(actionCommand.name())) return;
       const cwd = process.cwd();
       if (!fs.existsSync(path.join(cwd, 'package.json'))) return; // not a project
+      // An integration package is not an app: `init` is not its next step.
+      if (INTEGRATION_MANIFEST_FILES.some(file => fs.existsSync(path.join(cwd, file)))) return;
       if (isAstryxInitialized(cwd)) return; // already set up — stay quiet
       // Same wording as the core/cli postinstall nudges. #4151's getCliInvocation()
       // renders the correct form for THIS project — scoped `npx @astryxdesign/cli`
@@ -557,16 +545,18 @@ export async function createProgram() {
       mod[cmd.register](program);
     } catch (e) {
       // Command fails to load but CLI still works
+      const reason = /** @type {any} */ (e).message;
       const stub = program
         .command(cmd.name)
-        .description(`(failed to load: ${/** @type {any} */ (e).message})`)
+        .description(`(failed to load: ${reason})`)
         .action(() => {
           // Nothing loaded, so nothing was answered — say that rather than
           // leaving the run's result unreported.
           debug.recordCommandResult(debug.NO_RESULT_SET);
-          console.error(`Command "${cmd.name}" failed to load:`);
-          console.error(/** @type {any} */ (e).message);
-          process.exit(1);
+          // cliError, so --json still gets its one envelope.
+          cliError(`Command "${cmd.name}" failed to load: ${reason}`, {
+            code: ERROR_CODES.ERR_UNKNOWN,
+          });
         });
       markReportsResult(stub);
     }
@@ -601,20 +591,21 @@ export async function createProgram() {
       }
       // Human-readable summary as greppable records (agents should use --json).
       // One record per command: name, whether it supports --json, and the
-      // description.
+      // description. Field names are the manifest entry's own keys.
       emit(
         section(`${manifest.name} v${manifest.version} (${manifest.commands.length} commands)`),
         records(
           manifest.commands.map(c => ({
-            command: c.name,
+            name: c.name,
             json: c.json ? 'yes' : '',
             description: c.description || '',
           })),
-          {fields: ['command', 'json', 'description']},
+          {fields: ['name', 'json', 'description']},
         ),
         text(`Run \`${getCliInvocation()} manifest --json\` for the full structured manifest.`),
       );
     });
+  addExitCodesHelp(manifestCommand, manifestDoc.exitCodes);
   markReportsResult(manifestCommand);
 
   // Hidden command used by package.json postinstall scripts

package/clients/cli/latest-version-env.test.mjs

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ASTRYX_LATEST_VERSION is not a CLI control: setting it changes nothing
+ * a command prints. It used to append an update hint to `component` and
+ * `docs`.
+ */
+
+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 {runCli} from '../../test-utils/run-cli.mjs';
+
+const VARIABLE = 'ASTRYX_LATEST_VERSION';
+
+/** @type {string} */
+let dir;
+/** @type {string | undefined} */
+let saved;
+
+beforeEach(() => {
+  saved = process.env[VARIABLE];
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-latest-version-'));
+  // A project on an old core, so a "newer version" hint would have a reason to fire.
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name: 'app', private: true, dependencies: {'@astryxdesign/core': '^0.0.1'}}),
+  );
+});
+
+afterEach(() => {
+  if (saved === undefined) delete process.env[VARIABLE];
+  else process.env[VARIABLE] = saved;
+  fs.rmSync(dir, {recursive: true, force: true});
+});
+
+describe('ASTRYX_LATEST_VERSION', () => {
+  it('does not change what astryx docs prints', async () => {
+    delete process.env[VARIABLE];
+    const without = await runCli(['docs'], {cwd: dir});
+    process.env[VARIABLE] = '999.0.0';
+    const withVariable = await runCli(['docs'], {cwd: dir});
+
+    expect(withVariable.status).toBe(without.status);
+    expect(withVariable.stdout).toBe(without.stdout);
+    expect(withVariable.stderr).toBe(without.stderr);
+    expect(withVariable.stderr).not.toMatch(/newer version/i);
+  });
+});

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

@@ -133,6 +133,13 @@ describe('cliError — JSON mode', () => {
     expect(env.suggestions).toEqual([{name: 'Button', reason: 'closest match'}]);
   });
 
+  it('replaces an unregistered code with ERR_UNKNOWN', () => {
+    expect(() =>
+      cliError('EACCES: permission denied', {code: 'EACCES'}),
+    ).toThrow('__exit_1__');
+    expect(JSON.parse(stdout[0]).code).toBe('ERR_UNKNOWN');
+  });
+
   it('always exits 1 in JSON mode (custom exitCode is ignored — contract)', () => {
     expect(() => cliError('msg', {exitCode: 2})).toThrow('__exit_1__');
     expect(exitCode).toBe(1);

package/clients/cli/lib/component-format.mjs

@@ -71,7 +71,7 @@ function formatPropsTable(props) {
   lines.push('| Prop | Type | Default | Description |');
   lines.push('|------|------|---------|-------------|');
   for (const p of props) {
-    const def = p.default ? `\`${mdCell(p.default)}\`` : '—';
+    const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
     lines.push(
       `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
@@ -190,11 +190,11 @@ function formatTargetsTable(docs, themeData) {
       ...themeVariants.map((/** @type {string} */ v) => `${v}*`),
     ];
 
-    const variantsStr = variantParts.length > 0 ? variantParts.join(', ') : '—';
-    const statesStr = states.length > 0 ? states.join(', ') : '—';
+    const variantsStr = variantParts.length > 0 ? variantParts.join(', ') : '-';
+    const statesStr = states.length > 0 ? states.join(', ') : '-';
     const dataAttrs = getTargetDataAttributes(target);
     const dataAttrsStr =
-      dataAttrs.length > 0 ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '—';
+      dataAttrs.length > 0 ? dataAttrs.map(attr => `\`${attr}\``).join(', ') : '-';
 
     const className = target.deprecatedFor
       ? `\`${target.className}\` _(deprecated; use \`${target.deprecatedFor}\`)_`
@@ -342,7 +342,7 @@ export function formatFull(docs, options = {}) {
       const publicVars = docs.theming.vars.filter((/** @type {any} */ v) => !v.private && !v.derived);
 
       if (publicVars.length > 0) {
-        sections.push('**Themeable CSS variables** — additional properties that can be overridden in `defineTheme` component overrides.\n');
+        sections.push('**Themeable CSS variables** - additional properties that can be overridden in `defineTheme` component overrides.\n');
         const varLines = [];
         varLines.push('| CSS Variable | Default | Description |');
         varLines.push('|-------------|---------|-------------|');
@@ -544,7 +544,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
     signatureProps.length > 0
       ? `${displayName}(${signatureProps.join(', ')})`
       : displayName;
-  output.push(importHint ? `${sigStr}  ← from '${importHint}'` : sigStr);
+  output.push(importHint ? `${sigStr}  <- from '${importHint}'` : sigStr);
 
   // Description (shortened)
   if (description) {
@@ -569,7 +569,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
   // Derived properties (if any)
   if (docs.theming?.derived?.length) {
     const derivedNames = docs.theming.derived
-      .map((/** @type {any} */ d) => d.expand === 'container' ? `${d.property} → container tokens` : `${d.property} → ${(d.vars || []).join(', ')}`)
+      .map((/** @type {any} */ d) => d.expand === 'container' ? `${d.property} -> container tokens` : `${d.property} -> ${(d.vars || []).join(', ')}`)
       .join('; ');
     output.push(`  Derived: ${derivedNames}`);
   }
@@ -579,7 +579,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
     const { themeData = null } = options;
     const targetParts = docs.theming.targets.map((/** @type {any} */ t) => {
       const parts = [t.className];
-      if (t.deprecatedFor) parts.push(`deprecated→${t.deprecatedFor}`);
+      if (t.deprecatedFor) parts.push(`deprecated->${t.deprecatedFor}`);
       const dataAttrs = getTargetDataAttributes(t);
       if (dataAttrs.length) parts.push(`preferred attrs: ${dataAttrs.join(', ')}`);
       if (t.visualProps?.length) parts.push(`variants: ${t.visualProps.join(', ')}`);
@@ -595,7 +595,7 @@ export function formatBrief(docs, componentName, importHint, options = {}) {
 
   // Other props
   if (otherProps.length > 0) {
-    output.push(`  ${otherProps.join(' · ')}`);
+    output.push(`  ${otherProps.join(', ')}`);
   }
 
   // First code example

package/clients/cli/lib/component-format.test.mjs

@@ -157,7 +157,7 @@ describe('deprecated theming target guidance', () => {
 
   it('keeps the replacement in brief agent guidance', () => {
     expect(formatBrief(docs, 'Example')).toContain(
-      'astryx-old-target deprecated→new-target',
+      'astryx-old-target deprecated->new-target',
     );
   });
 });

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

@@ -25,6 +25,7 @@
  */
 
 import {recordCommandResult} from '../../../foundation/debug/index.mjs';
+import {text} from '../formatters/index.mjs';
 
 /**
  * Marks a Commander command that reports what it answered with, and says HOW:
@@ -78,6 +79,21 @@ export function markReportsResult(cmd) {
   return cmd;
 }
 
+/** The CommandDoc and wrapped FunctionDoc a command was built from. */
+export const COMMAND_DOCS = Symbol.for('astryx.command.docs');
+
+/**
+ * The docs a command was built from; undefined for a hand-registered command.
+ * @param {import('commander').Command} cmd
+ * @returns {{
+ *   doc: import('@astryxdesign/cli/authoring').CommandDoc,
+ *   fn?: import('@astryxdesign/cli/authoring').FunctionDoc,
+ * } | undefined}
+ */
+export function commandDocsOf(cmd) {
+  return /** @type {any} */ (cmd)?.[COMMAND_DOCS];
+}
+
 /**
  * Build a Commander command from a CommandDoc and attach it to `parent`.
  *
@@ -102,6 +118,7 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
     .join(' ');
 
   const cmd = parent.command(argSpec ? `${token} ${argSpec}` : token);
+  Object.defineProperty(cmd, COMMAND_DOCS, {value: {doc, fn}, configurable: true});
   if (doc.summary) cmd.description(doc.summary);
 
   const paramDesc = (/** @type {string | undefined} */ name) =>
@@ -126,12 +143,10 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
     cmd.addOption(option);
   }
 
-  // `choices` and `examples` are doc metadata surfaced by `astryx docs` and the
-  // doc site; they are intentionally NOT injected into `--help` here. Choices
-  // stay described in the option text (Commander `.choices()` would also change
-  // validation from the api layer's ERR_INVALID_ARGUMENT), and the current CLI
-  // help carries no per-command examples epilog. Keeping both out preserves the
-  // exact `--help`/manifest surface as registrations migrate to this converter.
+  // 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);
 
   if (action) {
     // The recording seam. An action's job ends at "here is what I answered
@@ -149,3 +164,14 @@ export function defineCommand(parent, doc, {fn, action} = {}) {
   }
   return cmd;
 }
+
+/**
+ * End `cmd`'s help with a CommandDoc's exit codes.
+ * @param {import('commander').Command} cmd
+ * @param {import('@astryxdesign/cli/authoring').CommandDoc['exitCodes']} exitCodes
+ */
+export function addExitCodesHelp(cmd, exitCodes) {
+  if (!exitCodes?.length) return;
+  const lines = exitCodes.map(({code, when}) => `  ${code}  ${when}`);
+  cmd.addHelpText('after', `\n${text(['Exit codes:', ...lines].join('\n')).toString()}`);
+}

package/clients/cli/lib/doc-text-ascii.test.mjs

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The component and hook text renderers add no non-ASCII characters of
+ * their own: given ASCII-only docs, every view they produce is plain ASCII.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+  formatBrief,
+  formatCompact,
+  formatFull,
+  formatProps,
+} from './component-format.mjs';
+import {
+  formatHookBrief,
+  formatHookCompact,
+  formatHookFull,
+  formatHookParams,
+} from './hook-format.mjs';
+
+const NON_ASCII = /[\u0080-\uffff]/g;
+
+/** @param {string} out @returns {string[]} */
+const nonAscii = out => out.match(NON_ASCII) ?? [];
+
+// Every optional field left empty and every optional path taken, so each
+// placeholder, separator, and arrow the renderers emit shows up at least once.
+const componentDoc = {
+  name: 'Widget',
+  description: 'A widget for tests.',
+  props: [
+    {name: 'variant', type: "'solid' | 'ghost'", description: 'Look.'},
+    {name: 'label', type: 'string', description: 'Label.', required: true},
+    {name: 'disabled', type: 'boolean', description: 'Disables it.'},
+    {name: 'tone', type: 'string', description: 'Tone.'},
+  ],
+  theming: {
+    vars: [{name: '--widget-gap', default: '8px', description: 'Gap.'}],
+    derived: [
+      {property: 'padding', expand: 'container'},
+      {property: 'radius', vars: ['--widget-radius']},
+    ],
+    targets: [
+      {className: 'astryx-widget', deprecatedFor: 'astryx-widget-v2'},
+      {className: 'astryx-widget-v2', visualProps: ['variant']},
+    ],
+  },
+};
+
+const hookDoc = {
+  name: 'useWidget',
+  importPath: '@astryxdesign/core/useWidget',
+  usage: {description: 'Widget behavior.'},
+  params: [
+    {name: 'options', type: 'object', description: 'Options.', required: true},
+    {name: 'delay', type: 'number', description: 'Delay.'},
+  ],
+  returns: [{name: 'open', type: 'boolean', description: 'Open state.'}],
+};
+
+describe('component text output is ASCII', () => {
+  it.each([
+    ['formatFull', () => formatFull(componentDoc)],
+    ['formatCompact', () => formatCompact(componentDoc, 'Widget')],
+    ['formatBrief', () => formatBrief(componentDoc, 'Widget', '@astryxdesign/core/Widget')],
+    ['formatProps', () => formatProps(componentDoc, 'Widget')],
+  ])('%s', (_name, render) => {
+    expect(nonAscii(render())).toEqual([]);
+  });
+});
+
+describe('hook text output is ASCII', () => {
+  it.each([
+    ['formatHookFull', () => formatHookFull(hookDoc)],
+    ['formatHookCompact', () => formatHookCompact(hookDoc, hookDoc.importPath)],
+    ['formatHookBrief', () => formatHookBrief(hookDoc)],
+    ['formatHookParams', () => formatHookParams(hookDoc)],
+  ])('%s', (_name, render) => {
+    expect(nonAscii(render())).toEqual([]);
+  });
+});

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

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Every CommandDoc's exit codes reach generated help and the manifest.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {describe, it, expect} from 'vitest';
+import {program, JSON_SUPPORTED} from '../index.mjs';
+import {buildManifest} from './manifest.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const COMMANDS = path.join(path.dirname(fileURLToPath(import.meta.url)), '../commands');
+
+/** @type {any[]} */
+const commandDocs = [];
+for (const file of fs.readdirSync(COMMANDS).sort()) {
+  if (!file.endsWith('.doc.mjs')) continue;
+  const {doc} = await import(pathToFileURL(path.join(COMMANDS, file)).href);
+  if (doc?.type === 'command') commandDocs.push(doc);
+}
+
+const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
+/** @type {Map<string, any>} */
+const entries = new Map();
+const walk = (/** @type {any} */ c) => {
+  entries.set(c.name, c);
+  (c.subcommands || []).forEach(walk);
+};
+manifest.commands.forEach(walk);
+
+describe('command exit codes', () => {
+  it('every CommandDoc documents its exit codes', () => {
+    expect(commandDocs.length).toBeGreaterThan(30);
+    for (const doc of commandDocs) {
+      expect(doc.exitCodes?.length, doc.name).toBeGreaterThan(0);
+    }
+  });
+
+  it.each(commandDocs.map((d) => [d.name, d]))(
+    '`astryx %s --help` lists the documented exit codes',
+    async (name, doc) => {
+      const {status, stdout} = await runCli([...name.split(' '), '--help']);
+      expect(status).toBe(0);
+      const section = stdout.slice(stdout.indexOf('\nExit codes:\n'));
+      expect(section.startsWith('\nExit codes:\n'), stdout).toBe(true);
+      expect(stdout.match(/\nExit codes?:\n/g), 'one exit-code section').toHaveLength(1);
+      for (const {code, when} of doc.exitCodes) {
+        expect(section).toContain(`\n  ${code}  ${when}\n`);
+      }
+    },
+  );
+
+  it('bare `astryx layout` exits 1 in both modes, as documented', async () => {
+    const doc = commandDocs.find((d) => d.name === 'layout');
+    expect(doc.exitCodes.find((e) => e.code === 1)?.when).toMatch(/^no subcommand/);
+    expect((await runCli(['layout'])).status).toBe(1);
+    expect((await runCli(['layout', '--json'])).status).toBe(1);
+  });
+
+  it('`astryx discover` with a blank query exits 1 only when packages are discovered', async () => {
+    const doc = commandDocs.find((d) => d.name === 'discover');
+    expect(doc.exitCodes.find((e) => e.code === 1)?.when).toMatch(/blank query when packages are discovered/);
+    const project = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-exit-discover-'));
+    try {
+      expect((await runCli(['discover', '   ', '--json'], {cwd: project})).status).toBe(0);
+      const pkg = path.join(project, 'node_modules/@acme/ui');
+      fs.mkdirSync(path.join(pkg, 'components'), {recursive: true});
+      fs.writeFileSync(path.join(pkg, 'package.json'), '{"name":"@acme/ui","version":"1.0.0","type":"module"}');
+      fs.writeFileSync(path.join(pkg, 'astryx.integration.mjs'), "export default {components: './components'};\n");
+      fs.writeFileSync(
+        path.join(pkg, 'components/Widget.doc.mjs'),
+        'export const doc = {type: "component", name: "Widget", description: "A widget"};\n',
+      );
+      fs.writeFileSync(path.join(pkg, 'components/Widget.tsx'), 'export function Widget() { return null; }\n');
+      fs.writeFileSync(path.join(project, 'package.json'), '{"name":"app","type":"module"}');
+      fs.writeFileSync(path.join(project, 'astryx.config.mjs'), "export default {integrations: ['@acme/ui']};\n");
+      expect((await runCli(['discover', '--json'], {cwd: project})).status).toBe(0);
+      const blank = await runCli(['discover', '   ', '--json'], {cwd: project});
+      expect(blank.status).toBe(1);
+      expect(JSON.parse(blank.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+    } finally {
+      fs.rmSync(project, {recursive: true, force: true});
+    }
+  });
+
+  it('the manifest carries every command exit code', () => {
+    for (const doc of commandDocs) {
+      expect(entries.get(doc.name)?.exitCodes, doc.name).toEqual(
+        doc.exitCodes.map(({code, when}) => ({code, when})),
+      );
+    }
+  });
+});

package/clients/cli/lib/hook-format.mjs

@@ -9,7 +9,10 @@
  * - Brief: signature line with import hint, description, key params
  */
 
-import {discoverHooks, findHookDoc} from '../../../foundation/discovery/hook-discovery.mjs';
+import {
+  discoverHooks,
+  findHookDoc,
+} from '../../../foundation/discovery/hook-discovery.mjs';
 import {loadDocs} from '../../../foundation/discovery/component-loader.mjs';
 import {formatAccessibility, mdCell} from './component-format.mjs';
 
@@ -23,7 +26,9 @@ function buildSignature(docs) {
   const name = docs.name;
 
   // Build params string — only top-level params (skip options.foo nested params)
-  const topParams = (docs.params || []).filter((/** @type {any} */ p) => !p.name.includes('.'));
+  const topParams = (docs.params || []).filter(
+    (/** @type {any} */ p) => !p.name.includes('.'),
+  );
   const paramStr = topParams
     .map((/** @type {any} */ p) => {
       const opt = p.required ? '' : '?';
@@ -57,7 +62,7 @@ function formatParamsTable(params) {
   lines.push('| Param | Type | Default | Description |');
   lines.push('|-------|------|---------|-------------|');
   for (const p of params) {
-    const def = p.default ? `\`${mdCell(p.default)}\`` : '\u2014';
+    const def = p.default ? `\`${mdCell(p.default)}\`` : '-';
     const req = p.required ? ' **(required)**' : '';
     lines.push(
       `| \`${mdCell(p.name)}\` | \`${mdCell(p.type)}\` | ${def} | ${mdCell(p.description)}${req} |`,
@@ -150,7 +155,9 @@ export function formatHookCompact(docs, importPath) {
   const imp = importPath || docs.importPath;
   if (imp) {
     sections.push('## Import\n');
-    sections.push(`\`\`\`tsx\nimport { ${docs.name} } from '${imp}';\n\`\`\`\n`);
+    sections.push(
+      `\`\`\`tsx\nimport { ${docs.name} } from '${imp}';\n\`\`\`\n`,
+    );
   }
 
   // Best Practices (matches component compact)
@@ -198,7 +205,7 @@ export function formatHookCompact(docs, importPath) {
 /**
  * Format a brief, LLM-optimized hook summary.
  * Matches component formatBrief conventions:
- *   signature  ← from 'import/path'
+ *   signature  <- from 'import/path'
  *   description
  *   key params
  * @param {any} docs
@@ -211,7 +218,7 @@ export function formatHookBrief(docs) {
   // Signature line with import hint (matches component brief)
   const sig = buildSignature(docs);
   const imp = docs.importPath;
-  output.push(imp ? `${sig}  \u2190 from '${imp}'` : sig);
+  output.push(imp ? `${sig}  <- from '${imp}'` : sig);
 
   // Description (shortened, matches component brief)
   const desc = docs.usage?.description || '';
@@ -225,12 +232,14 @@ export function formatHookBrief(docs) {
     output.push(`  Related: ${docs.relatedComponents.join(', ')}`);
   }
 
-  // Key params (matches component brief 'prop · prop' line)
+  // Key params (matches component brief 'prop, prop' line)
   const paramNames = (docs.params || [])
     .filter((/** @type {any} */ p) => !p.name.includes('.'))
-    .map((/** @type {any} */ p) => p.required ? `${p.name}: ${p.type.split('|')[0].trim()}` : p.name);
+    .map((/** @type {any} */ p) =>
+      p.required ? `${p.name}: ${p.type.split('|')[0].trim()}` : p.name,
+    );
   if (paramNames.length > 0) {
-    output.push(`  ${paramNames.join(' \u00b7 ')}`);
+    output.push(`  ${paramNames.join(', ')}`);
   }
 
   return output.join('\n') + '\n';
@@ -253,7 +262,7 @@ export async function formatHookBriefAll(coreDir) {
       const docPath = findHookDoc(coreDir, hookName);
       if (docPath) {
         try {
-          const docs = await loadDocs(docPath);
+          const docs = await loadDocs(docPath, {root: 'hooks'});
           output.push(formatHookBrief(docs));
         } catch {
           output.push(`${hookName}\n  (no docs)\n`);

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

@@ -29,6 +29,9 @@
  *   4. Routing unknown-subcommand attempts through the same error
  *      envelope path (so `astryx bogus-cmd --json` gets exit 1 + envelope
  *      instead of exit 0 + help envelope).
+ *   5. Emitting an error envelope, not the help envelope, when Commander
+ *      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
@@ -117,6 +120,35 @@ export function buildHelpEnvelope(cmd) {
   };
 }
 
+/**
+ * The error envelope for help Commander shows because the invocation failed
+ * (it then exits 1): `help <name>` for an unknown name on the root, or a
+ * command group run without a subcommand.
+ *
+ * @param {import('commander').Command} cmd the command whose help was shown
+ * @returns {ReturnType<typeof toErrorEnvelope>}
+ */
+export function buildHelpErrorEnvelope(cmd) {
+  const available = cmd.commands
+    .filter(s => !(/** @type {any} */ (s))._hidden && s.name() !== 'help')
+    .map(s => s.name());
+  if (!cmd.parent) {
+    // Commander dispatches `help <name>` with ['help', <name>, ...] in args.
+    const requested = cmd.args[1];
+    return toErrorEnvelope(
+      requested ? `unknown command '${requested}'` : 'unknown command',
+      available.map(name => ({name, reason: 'available command'})),
+      ERROR_CODES.ERR_UNKNOWN_COMMAND,
+    );
+  }
+  const group = fullNameOf(cmd);
+  return toErrorEnvelope(
+    `'${group}' needs a subcommand`,
+    available.map(name => ({name: `${group} ${name}`, reason: 'available subcommand'})),
+    ERROR_CODES.ERR_MISSING_ARGUMENT,
+  );
+}
+
 /**
  * Emit a JSON error envelope to stdout (the JSON contract uses stdout
  * for both success and error).
@@ -310,7 +342,9 @@ function patchOutputHelp(cmd) {
     if (jsonActive()) {
       if (!process.__xdsJsonHandled) {
         process.__xdsJsonHandled = true;
-        const env = buildHelpEnvelope(cmd);
+        const env = contextOptions?.error
+          ? buildHelpErrorEnvelope(cmd)
+          : buildHelpEnvelope(cmd);
         process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
       }
       return;
@@ -334,7 +368,9 @@ function patchPrototype(CommandCtor) {
     if (jsonActive()) {
       if (!process.__xdsJsonHandled) {
         process.__xdsJsonHandled = true;
-        const env = buildHelpEnvelope(this);
+        const env = contextOptions?.error
+          ? buildHelpErrorEnvelope(this)
+          : buildHelpEnvelope(this);
         process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
       }
       return;