@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

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;

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

@@ -20,7 +20,12 @@
  */
 
 import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {Command} from 'commander';
 import {runCli} from '../../../test-utils/run-cli.mjs';
+import {installJsonShim} from './json-shim.mjs';
+import {setJsonMode} from '../../../foundation/response/json.mjs';
 
 function parseJson(stdout) {
   return JSON.parse(stdout);
@@ -207,3 +212,81 @@ describe('--json shim: stdout discipline under --json', () => {
     }
   });
 });
+
+describe('--json shim: help shown for a failed invocation is an error envelope', () => {
+  it('astryx help bogus --json emits ERR_UNKNOWN_COMMAND, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['help', 'bogus', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const parsed = parseJson(stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.apiVersion).toBe(1);
+    expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
+    expect(parsed.error).toMatch(/bogus/);
+  });
+
+  it('astryx layout --json (group, no subcommand) emits ERR_MISSING_ARGUMENT, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['layout', '--json']);
+    expect(status).toBe(1);
+    expect(stderr).toBe('');
+    const parsed = parseJson(stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
+    expect(parsed.suggestions.map((s) => s.name)).toContain('layout expand');
+  });
+
+  it('astryx layout (no --json) still prints help to stderr, exit 1', async () => {
+    const {status, stdout, stderr} = await runCli(['layout']);
+    expect(status).toBe(1);
+    expect(stdout).toBe('');
+    expect(stderr).toMatch(/Usage: astryx layout/);
+  });
+
+  it('the real binary emits the same envelope for help bogus --json', () => {
+    // One program per process, so the root's own outputHelp patch is used here.
+    const bin = fileURLToPath(new URL('../bin/astryx.mjs', import.meta.url));
+    const res = spawnSync(process.execPath, [bin, 'help', 'bogus', '--json'], {
+      encoding: 'utf-8',
+      timeout: 20_000,
+    });
+    expect(res.status).toBe(1);
+    expect(res.stderr).toBe('');
+    const parsed = parseJson(res.stdout);
+    expect(parsed).not.toHaveProperty('type');
+    expect(parsed.code).toBe('ERR_UNKNOWN_COMMAND');
+  });
+
+  it('a group added after install gets the same error envelope', () => {
+    const program = new Command('astryx');
+    installJsonShim(program);
+    // Added later, so only the prototype-level patch covers its outputHelp.
+    const late = new Command('late');
+    late.command('child');
+    program.addCommand(late);
+    /** @type {string[]} */
+    const writes = [];
+    const origWrite = process.stdout.write;
+    // @ts-expect-error - test-only capture
+    process.stdout.write = (chunk) => writes.push(String(chunk)) > 0;
+    setJsonMode(true);
+    delete process.__xdsJsonHandled;
+    try {
+      late.outputHelp({error: true});
+    } finally {
+      process.stdout.write = origWrite;
+      setJsonMode(false);
+      delete process.__xdsJsonHandled;
+    }
+    const parsed = parseJson(writes.join(''));
+    expect(parsed.code).toBe('ERR_MISSING_ARGUMENT');
+    expect(parsed.suggestions).toEqual([{name: 'late child', reason: 'available subcommand'}]);
+  });
+
+  it('astryx help layout --json still emits the help envelope, exit 0', async () => {
+    const {status, stdout} = await runCli(['help', 'layout', '--json']);
+    expect(status).toBe(0);
+    const parsed = parseJson(stdout);
+    expect(parsed.type).toBe('help');
+    expect(parsed.data.command).toBe('astryx layout');
+  });
+});

package/clients/cli/lib/manifest.d.ts

@@ -48,6 +48,8 @@ export interface ManifestCommand {
   responseTypes?: string[];
   /** Example invocations. */
   examples?: string[];
+  /** Documented exit codes: the process exit status and when it occurs. */
+  exitCodes?: {code: number; when: string}[];
   /** Nested subcommands (e.g. `theme build` under `theme`). */
   subcommands?: ManifestCommand[];
 }

package/clients/cli/lib/manifest.mjs

@@ -35,6 +35,8 @@
  */
 
 import {API_VERSION} from '../../../foundation/response/json.mjs';
+import {commandDocsOf} from './define-command.mjs';
+import {doc as manifestDoc} from '../commands/manifest.doc.mjs';
 
 /**
  * Response `type` discriminators each fully-qualified command can emit in
@@ -55,12 +57,19 @@ export const RESPONSE_TYPES = {
     'component.detail.showcase',
     'component.detail.blocks',
   ],
-  docs: ['docs.list', 'docs.index', 'docs.detail', 'docs.detail.section'],
+  docs: [
+    'docs.list',
+    'docs.index',
+    'docs.detail',
+    'docs.detail.section',
+    'docs.node',
+  ],
   blog: ['blog.list', 'blog.detail'],
   discover: [
     'discover.list',
     'discover.detail',
     'discover.detail.doc',
+    'discover.item',
     'discover.search',
   ],
   search: ['search'],
@@ -108,8 +117,9 @@ const EXAMPLES = {
   docs: [
     'astryx docs',
     'astryx docs spacing --json',
-    'astryx docs theme --index',
+    'astryx docs theme',
     'astryx docs theme quick-start',
+    'astryx docs cli/integrations --full',
   ],
   discover: ['astryx discover --json'],
   search: [
@@ -237,6 +247,18 @@ function fullName(cmd, root) {
   return parts.join(' ');
 }
 
+/**
+ * The docs a command was built from. `manifest` is registered by hand in
+ * index.mjs, so its CommandDoc is read here.
+ * @param {import('commander').Command} cmd
+ * @param {string} name
+ */
+function docsOf(cmd, name) {
+  return (
+    commandDocsOf(cmd) ?? (name === 'manifest' ? {doc: manifestDoc} : undefined)
+  );
+}
+
 /**
  * Recursively describe a Commander command and its subcommands.
  *
@@ -252,6 +274,8 @@ function describeCommand(cmd, root, jsonSupported) {
   // `_hidden` is a Commander internal not present on its public types.
   if (!name || /** @type {any} */ (cmd)._hidden || name === 'help') return null;
 
+  const docs = docsOf(cmd, name);
+
   const subcommands = /** @type {object[]} */ (
     (cmd.commands || [])
       .map(sub => describeCommand(sub, root, jsonSupported))
@@ -284,6 +308,12 @@ function describeCommand(cmd, root, jsonSupported) {
 
   if (EXAMPLES[name]) entry.examples = [...EXAMPLES[name]];
 
+  const exitCodes = (docs?.doc.exitCodes ?? []).map(({code, when}) => ({
+    code,
+    when,
+  }));
+  if (exitCodes.length > 0) entry.exitCodes = exitCodes;
+
   // Sort subcommands by name for a stable, agent-facing contract — the same
   // guarantee the top-level command list makes. Otherwise Commander
   // registration order leaks into the manifest and a pure reorder of

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

@@ -196,3 +196,20 @@ describe('manifest: e2e', () => {
       .toContain('component.list');
   });
 });
+
+describe('manifest: text projection', () => {
+  it('astryx manifest (text) uses the JSON entry keys as its field names', async () => {
+    const text = await runCli(['manifest']);
+    expect(text.status).toBe(0);
+    const json = JSON.parse((await runCli(['manifest', '--json'])).stdout);
+    const jsonKeys = new Set(json.data.commands.flatMap((c) => Object.keys(c)));
+    const textKeys = new Set(
+      text.stdout
+        .split('\n')
+        .map((line) => /^([A-Za-z]+):\s/.exec(line)?.[1])
+        .filter(Boolean),
+    );
+    expect(textKeys).toContain('name');
+    for (const key of textKeys) expect(jsonKeys).toContain(key);
+  });
+});

package/foundation/agent-docs/agent-docs.d.mts

@@ -78,8 +78,9 @@ export function detectStylingSystem(targetDir: string): "stylex" | "tailwind" |
  * Generate the agent cheat sheet from live CLI metadata.
  *
  * Structured as: workflow (behavioral) → rules (error prevention) → CLI reference.
- * Templates are positioned first in the workflow to teach agents the
- * "look at reference code" reflex before writing any UI.
+ * Templates lead the workflow: every page starts from a scaffolded template,
+ * because the template already carries the frame and spacing that an agent
+ * composing from components would have to re-derive, and usually gets wrong.
  *
  * `stylingSystem` tailors the custom-styling guidance to what the project has
  * configured (see {@link detectStylingSystem}) so the agent never reaches for a
@@ -182,6 +183,8 @@ export function removeXdsBlock(filePath: string, { deleteIfEmpty }?: {
 /**
  * Remove Astryx section from all known agent doc files.
  * @param {string} targetDir
+ * @throws {PathSafetyError} `ERR_PATH_TRAVERSAL` when a file it would change
+ *   resolves outside `targetDir`; nothing is changed.
  */
 export function removeAgentDocs(targetDir: string): void;
 /**
@@ -208,6 +211,8 @@ export function removeAgentDocs(targetDir: string): void;
  * @param {string} [options.renderedBlock] - Fully rendered expected block. Init
  *   and upgrade pass one shared block to every target.
  * @returns {string[]} List of files written
+ * @throws {import('../fs/path-safety.mjs').PathSafetyError} when a file it would
+ *   write resolves outside `targetDir`; nothing is written.
  */
 export function installAgentDocs(targetDir: string, { zh, lang, agent, paths, onlyReplace, topics, renderedBlock, }?: {
     zh?: boolean | undefined;