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

package/clients/cli/lib/manifest.mjs

@@ -7,18 +7,19 @@
  * lets an AI agent drive the entire CLI WITHOUT scraping `--help` text. It is
  * to the CLI what an OpenAPI spec is to an HTTP API.
  *
- * Most of the manifest is DERIVED from Commander metadata (program.commands,
- * cmd.options, cmd.registeredArguments, cmd.description()) so it cannot drift
- * out of sync with the real command definitions. The two pieces Commander does
- * not know about — whether a command supports `--json`, and which response
- * `type` discriminators it can emit — are layered on from:
+ * Its per-command facts come from the command's own definitions: names,
+ * arguments and options from Commander metadata (program.commands, cmd.options,
+ * cmd.registeredArguments, cmd.description()); examples from its CommandDoc;
+ * response `type` discriminators from the returns of the FunctionDoc it wraps
+ * (both attached by `defineCommand`); `--json` support from the JSON_SUPPORTED
+ * allowlist in index.mjs. The hand-kept lists are CLI_LAYER_RESPONSE_TYPES,
+ * for envelopes no API function returns, and ROOT_RESPONSE_TYPES, for the two
+ * (help and version) that no single command owns.
  *
- *   - JSON_SUPPORTED  (the allowlist in index.mjs), and
- *   - RESPONSE_TYPES  (the declarative map below).
- *
- * A drift-guard test (manifest.test.mjs) asserts every registered command
- * appears in the manifest and every JSON-supported command has a response-type
- * entry, so adding a command without describing it fails CI.
+ * Drift-guard tests (manifest.test.mjs) assert every registered command appears
+ * in the manifest, every JSON-supported command has response types, and the
+ * examples and response types equal the docs, so adding a command without
+ * describing it fails CI.
  *
  * DESIGN DECISION — manifest stays CLI-special; there is intentionally NO
  * `api/manifest`. It describes the CLI's own Commander tree, so it takes the live
@@ -39,153 +40,27 @@ 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
- * `--json` mode. Keyed by the same name Commander reports (parent + leaf,
- * space-joined), e.g. `theme build`. Commander has no knowledge of these —
- * they come from each command's `jsonOut(...)` call sites — so we keep them
- * here, close to the JSON_SUPPORTED allowlist, and guard them with a test.
- *
+ * Envelopes the CLI layer builds itself, so the wrapped FunctionDoc cannot
+ * declare them: `manifest` wraps no API function, `theme build` batches several
+ * `themeBuild()` receipts, and `theme add` with no slug (or `--list`) answers
+ * with `themeListAvailable()`'s `theme.list` instead of calling `themeAdd()`.
+ * manifest.test.mjs fails once the wrapped FunctionDoc declares one of these, so
+ * the list only shrinks.
  * @type {Record<string, string[]>}
  */
-export const RESPONSE_TYPES = {
-  init: ['init.run', 'init.remove'],
-  component: [
-    'component.list',
-    'component.detail',
-    'component.detail.props',
-    'component.detail.source',
-    'component.detail.showcase',
-    'component.detail.blocks',
-  ],
-  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.search',
-  ],
-  search: ['search'],
-  build: ['build.help', 'build.kit'],
-  swizzle: ['swizzle.list', 'swizzle.copy'],
-  'gap-report': ['gap-report.categories', 'gap-report.file'],
-  template: [
-    'template.list',
-    'template.show',
-    'template.skeleton',
-    'template.copy',
-    'template.cdn',
-  ],
-  hook: ['hook.list', 'hook.detail', 'hook.detail.params'],
-  'theme build': ['theme.build', 'theme.build.check', 'theme.build.batch'],
-  'theme list': ['theme.list'],
-  'theme add': ['theme.list', 'theme.add'],
-  'theme template': ['theme.template'],
-  'theme targets': ['theme.targets'],
-  'theme palette generate': ['theme.palette.generate'],
-  'integration add': ['integration.add'],
-  'integration pack': ['integration.pack-check'],
-  upgrade: ['upgrade.list', 'upgrade.status', 'upgrade.run'],
+const CLI_LAYER_RESPONSE_TYPES = {
   manifest: ['manifest'],
-  doctor: ['doctor'],
-  'doctor integration validate': ['integration.validate'],
-  'doctor integration templates': ['integration.template-conflicts'],
-  'doctor integration components': ['integration.component-conflicts'],
-  'doctor integration docs': ['integration.doc-conflicts'],
-  'layout expand': ['layout.expand'],
-  'layout check': ['layout.check'],
-  'layout grammar': ['layout.grammar'],
+  'theme build': ['theme.build.batch'],
+  'theme add': ['theme.list'],
 };
 
 /**
- * Example invocations per fully-qualified command. Optional, agent-facing.
- * @type {Record<string, string[]>}
+ * 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 the per-command response types.
+ * @type {readonly string[]}
  */
-const EXAMPLES = {
-  component: [
-    'astryx component',
-    'astryx component XDSButton',
-    'astryx component XDSButton --props --json',
-  ],
-  docs: [
-    'astryx docs',
-    'astryx docs spacing --json',
-    'astryx docs theme',
-    'astryx docs theme quick-start',
-    'astryx docs cli/integrations --full',
-  ],
-  discover: ['astryx discover --json'],
-  search: [
-    'astryx search modal --json',
-    'astryx search button --type component --json',
-  ],
-  build: ['astryx build', 'astryx build "analytics dashboard" --json'],
-  swizzle: ['astryx swizzle XDSButton'],
-  'gap-report': [
-    'astryx gap-report --list-categories',
-    "astryx gap-report Button --category docs_gap --reason 'Missing keyboard example'",
-  ],
-  template: [
-    'astryx template --json',
-    'astryx template dashboard ./src/app',
-    'astryx template --cdn',
-  ],
-  hook: ['astryx hook', 'astryx hook useFocusTrap --json'],
-  'theme build': [
-    'astryx theme build ./src/themes/ocean.ts --out ./dist/ocean.css',
-    'astryx theme build ./src/themes/ocean.ts --check',
-  ],
-  'theme list': ['astryx theme list --json'],
-  'theme add': [
-    'astryx theme add matcha',
-    'astryx theme add matcha ./src/themes/matcha',
-  ],
-  'theme template': ['astryx theme template', 'astryx theme template --json'],
-  'theme targets': [
-    'astryx theme targets Switch',
-    'astryx --json theme targets',
-  ],
-  'theme palette generate': [
-    'astryx theme palette generate palette.config.json',
-    'astryx theme palette generate palette.config.json --out ocean.palette.json',
-  ],
-  'integration add': [
-    'astryx integration add component AcmeWidget',
-    'astryx integration add doc deploying --dry-run --json',
-  ],
-  'integration pack': ['astryx integration pack --check --json'],
-  upgrade: ['astryx upgrade --json'],
-  manifest: ['astryx manifest --json', 'astryx --json'],
-  doctor: ['astryx doctor', 'astryx doctor --json'],
-  'doctor integration validate': [
-    'astryx doctor integration validate',
-    'astryx doctor integration validate @acme/widgets --json',
-  ],
-  'doctor integration templates': [
-    'astryx doctor integration templates',
-    'astryx doctor integration templates @acme/widgets --json',
-  ],
-  'doctor integration components': [
-    'astryx doctor integration components',
-    'astryx doctor integration components @acme/widgets --json',
-  ],
-  'doctor integration docs': [
-    'astryx doctor integration docs',
-    'astryx doctor integration docs @acme/widgets --json',
-  ],
-  init: ['astryx init', 'astryx init --all --json'],
-  'layout expand': [
-    `astryx layout expand 'V[g6] > C{card-callout}*4' ./src/Page.tsx`,
-  ],
-  'layout check': [`astryx layout check 'A[cp6] > L > LC > S[p6]' --json`],
-  'layout grammar': ['astryx layout grammar'],
-};
+export const ROOT_RESPONSE_TYPES = Object.freeze(['help', 'version']);
 
 /**
  * Map a Commander Option to a flag descriptor. Derives type from whether the
@@ -301,11 +176,17 @@ function describeCommand(cmd, root, jsonSupported) {
   const aliases = cmd.aliases ? cmd.aliases() : [];
   if (aliases && aliases.length > 0) entry.aliases = [...aliases];
 
-  // Response types this command can emit in --json mode (only meaningful for
-  // JSON-supported leaves). Subcommand groups (e.g. bare `theme`) have none.
-  if (RESPONSE_TYPES[name]) entry.responseTypes = [...RESPONSE_TYPES[name]];
+  // Response types this command can emit in --json mode: the returns of the
+  // FunctionDoc it wraps, then any envelope the CLI layer builds. Subcommand
+  // groups (e.g. bare `theme`) have none.
+  const responseTypes = [
+    ...(docs?.fn?.returns ?? []).map(r => r.type),
+    ...(CLI_LAYER_RESPONSE_TYPES[name] ?? []),
+  ];
+  if (responseTypes.length > 0) entry.responseTypes = responseTypes;
 
-  if (EXAMPLES[name]) entry.examples = [...EXAMPLES[name]];
+  const examples = (docs?.doc.examples ?? []).map(e => e.cli);
+  if (examples.length > 0) entry.examples = examples;
 
   const exitCodes = (docs?.doc.exitCodes ?? []).map(({code, when}) => ({
     code,
@@ -348,6 +229,15 @@ function describeGlobalOptions(program) {
   return opts;
 }
 
+/**
+ * Every command in a described tree, depth first.
+ * @param {any[]} commands
+ * @returns {any[]}
+ */
+function flattenCommands(commands) {
+  return commands.flatMap(c => [c, ...flattenCommands(c.subcommands || [])]);
+}
+
 /**
  * Build the full capability manifest from a configured Commander program.
  *
@@ -378,7 +268,9 @@ export function buildManifest(program, opts = {}) {
     // Flat index of every response `type` discriminator the CLI can emit,
     // keyed by command — lets an agent know what to expect back per call.
     responseTypes: Object.fromEntries(
-      Object.entries(RESPONSE_TYPES).map(([k, v]) => [k, [...v]]),
+      flattenCommands(commands)
+        .filter(c => c.responseTypes)
+        .map(c => [c.name, [...c.responseTypes]]),
     ),
   };
 }

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

@@ -14,11 +14,46 @@
  *      surfaces emit valid, enriched JSON.
  */
 
+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, RESPONSE_TYPES} from './manifest.mjs';
+import {buildManifest} from './manifest.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Import every `*.doc.mjs` under `dir` whose doc has the given type, keyed by
+ * its `name`.
+ * @param {string} dir @param {string} type @returns {Promise<Map<string, any>>}
+ */
+async function loadDocs(dir, type) {
+  const out = new Map();
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true, recursive: true})) {
+    if (!entry.isFile() || !entry.name.endsWith('.doc.mjs')) continue;
+    const file = path.join(entry.parentPath, entry.name);
+    const {doc} = await import(pathToFileURL(file).href);
+    if (doc?.type === type) out.set(doc.name, doc);
+  }
+  return out;
+}
+
+const commandDocs = await loadDocs(path.join(HERE, '../commands'), 'command');
+const functionDocs = await loadDocs(path.join(HERE, '../../../api'), 'function');
+
+/**
+ * Envelopes built in the CLI layer, which no FunctionDoc can declare. Pinned so
+ * an entry is dropped once its type moves behind an API function.
+ */
+const CLI_LAYER_TYPES = {
+  manifest: ['manifest'],
+  'theme build': ['theme.build.batch'],
+  'theme add': ['theme.list'],
+};
+
 const manifest = buildManifest(program, {jsonSupported: JSON_SUPPORTED, version: '0.0.0-test'});
 
 /** Flatten the manifest command tree into fully-qualified names. */
@@ -64,17 +99,73 @@ describe('manifest: drift guards', () => {
 
   it('declares response types for every JSON-supported command', () => {
     for (const name of JSON_SUPPORTED) {
+      const entry = allEntries.find((c) => c.name === name);
       expect(
-        RESPONSE_TYPES[name],
-        `JSON-supported command "${name}" has no response-type entry`,
-      ).toBeDefined();
-      expect(RESPONSE_TYPES[name].length).toBeGreaterThan(0);
+        entry?.responseTypes?.length,
+        `JSON-supported command "${name}" has no response types`,
+      ).toBeGreaterThan(0);
+      expect(manifest.responseTypes[name]).toEqual(entry.responseTypes);
     }
   });
 
   it('has no response-type entry for a command that does not exist', () => {
-    for (const name of Object.keys(RESPONSE_TYPES)) {
-      expect(allNames.has(name), `RESPONSE_TYPES key "${name}" is not a real command`).toBe(true);
+    for (const name of Object.keys(manifest.responseTypes)) {
+      expect(allNames.has(name), `responseTypes key "${name}" is not a real command`).toBe(true);
+    }
+  });
+
+  it('takes every command example from its CommandDoc', () => {
+    for (const [name, doc] of commandDocs) {
+      const entry = allEntries.find((c) => c.name === name);
+      expect(entry, `CommandDoc "${name}" has no manifest entry`).toBeDefined();
+      expect(entry.examples ?? [], name).toEqual((doc.examples ?? []).map((e) => e.cli));
+    }
+  });
+
+  it('lists every response type the wrapped API function returns', () => {
+    for (const [name, doc] of commandDocs) {
+      if (!doc.fn) continue;
+      const entry = allEntries.find((c) => c.name === name);
+      for (const {type} of functionDocs.get(doc.fn).returns) {
+        expect(entry.responseTypes, `${name} can emit ${type}`).toContain(type);
+      }
+    }
+  });
+
+  it('lists upgrade.registry, which `upgrade --registry --json` emits', async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-manifest-'));
+    fs.writeFileSync(path.join(cwd, 'package.json'), '{"name":"app","version":"1.0.0"}');
+    const {status, stdout} = await runCli(['--json', 'upgrade', '--registry'], {cwd});
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).type).toBe('upgrade.registry');
+    expect(manifest.responseTypes.upgrade).toContain('upgrade.registry');
+  });
+
+  it('lists theme.list for theme add, which lists themes when given no slug', async () => {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-manifest-'));
+    fs.writeFileSync(path.join(cwd, 'package.json'), '{"name":"app","version":"1.0.0"}');
+    const {status, stdout} = await runCli(['--json', 'theme', 'add'], {cwd});
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).type).toBe('theme.list');
+    expect(manifest.responseTypes['theme add']).toContain('theme.list');
+  });
+
+  it('takes response types from the wrapped FunctionDoc, plus CLI-layer envelopes', () => {
+    for (const [name, doc] of commandDocs) {
+      const entry = allEntries.find((c) => c.name === name);
+      const returns = doc.fn ? functionDocs.get(doc.fn).returns.map((r) => r.type) : [];
+      const expected = [...returns, ...(CLI_LAYER_TYPES[name] ?? [])];
+      expect(entry.responseTypes ?? [], name).toEqual(expected);
+    }
+  });
+
+  it('pins only CLI-layer envelopes that no FunctionDoc declares', () => {
+    for (const [name, types] of Object.entries(CLI_LAYER_TYPES)) {
+      const fn = commandDocs.get(name)?.fn;
+      const declared = fn ? functionDocs.get(fn).returns.map((r) => r.type) : [];
+      for (const type of types) {
+        expect(declared, `${type} is declared by ${fn}(); unpin it`).not.toContain(type);
+      }
     }
   });
 
@@ -156,7 +247,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 +287,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/agent-docs/agent-docs.test.mjs

@@ -105,7 +105,8 @@ describe('generateCompressedIndex', () => {
 
   it('includes upgrade command and migration rule', () => {
     const result = generateCompressedIndex('1.0.0');
-    expect(result).toContain('upgrade --apply');
+    // `upgrade --apply` alone stops with "Missing required --from".
+    expect(result).toContain('upgrade --from <old version> --apply');
     expect(result).toMatch(/after any Astryx or integration dependency bump/);
   });
 
@@ -201,7 +202,7 @@ describe('generateCompressedIndex', () => {
       ],
     });
 
-    expect(result.indexOf('upgrade --apply')).toBeLessThan(
+    expect(result.indexOf('upgrade --from <old version> --apply')).toBeLessThan(
       result.indexOf('INTEGRATIONS:'),
     );
     expect(result.indexOf('INTEGRATIONS:')).toBeLessThan(

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',

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

@@ -63,7 +63,9 @@ describe('authoring self-docs', () => {
 describe('what the authoring docs say about the docs tree', () => {
   it('marks exactly the fields the docs tree does not read yet', () => {
     const notReadYet = graphFieldsDoc.fields
-      .filter(field => /Not read yet/.test(field.description))
+      .filter(field =>
+        /^Reserved: .*Nothing reads it today/.test(field.description),
+      )
       .map(field => field.name);
     // The tree reads `placement` for every guide (spec:AST-046); the other
     // graph fields are still refused by every topic reader.
@@ -79,7 +81,9 @@ describe('what the authoring docs say about the docs tree', () => {
     expect(placement.description).toMatch(
       /Read for every guide, the CLI's and each integration's/,
     );
-    expect(graphFieldsDoc.description).toMatch(/not built yet/);
+    expect(graphFieldsDoc.description).toMatch(
+      /Nothing reads `aliases` or `audience` today/,
+    );
   });
 
   it('keeps graph blocks behind the separate GraphContentBlock type, and a section takes a reference block', () => {

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

@@ -315,12 +315,20 @@ function functionSection(fn, index) {
   }
   const params = fn.params ?? [];
   if (params.length > 0) {
+    // A Default column only when some parameter declares a default, so a
+    // function with none keeps a three-column table.
+    const defaults = params.some(
+      (/** @type {any} */ p) => typeof p.default === 'string' && p.default !== '',
+    );
     content.push({
       type: 'table',
-      headers: ['Parameter', 'Type', 'Description'],
+      headers: defaults
+        ? ['Parameter', 'Type', 'Default', 'Description']
+        : ['Parameter', 'Type', 'Description'],
       rows: params.map((/** @type {any} */ p) => [
-        `\`${p.name}\``,
+        `\`${p.name}\`${p.required ? ' (required)' : ''}`,
         `\`${p.type ?? ''}\``,
+        ...(defaults ? [p.default ?? ''] : []),
         p.description ?? '',
       ]),
     });
@@ -405,6 +413,12 @@ export function cliDocSection(doc, index) {
   if (doc.type === 'command') return commandSection(doc, index);
   if (doc.type === 'function') return functionSection(doc, index);
   if (doc.type === 'enum') return enumSection(doc);
+  if (doc.type === 'namespace')
+    return {
+      id: routeSegment(doc.name),
+      title: doc.title,
+      content: doc.blocks ?? [],
+    };
   return {...selfDocSection(doc), id: routeSegment(doc.name)};
 }
 

package/foundation/discovery/cli-self-docs.test.mjs

@@ -315,6 +315,26 @@ describe('cliDocSection', () => {
     ]);
   });
 
+  it('marks required parameters and adds a Default column when a parameter has a default', () => {
+    const beta = fn('beta', {
+      params: [
+        {name: 'slug', type: 'string', description: 'The slug.', required: true},
+        {name: 'options.limit', type: 'number', description: 'How many.', default: '20'},
+      ],
+    });
+    const table = cliDocSection(beta, indexOf([beta])).content.find(
+      (/** @type {any} */ block) => block.type === 'table',
+    );
+    expect(table).toEqual({
+      type: 'table',
+      headers: ['Parameter', 'Type', 'Default', 'Description'],
+      rows: [
+        ['`slug` (required)', '`string`', '', 'The slug.'],
+        ['`options.limit`', '`number`', '20', 'How many.'],
+      ],
+    });
+  });
+
   it('renders an API function, an enum, and a schema', () => {
     const alpha = fn('alpha', {
       description: 'Longer.',

package/foundation/discovery/docs-discovery.mjs

@@ -626,7 +626,11 @@ function findMergeTarget(sections, section) {
   const sameTitle = sections.findIndex(
     candidate => sourceTitle(candidate) === title,
   );
-  return sameTitle;
+  if (sameTitle !== -1) return sameTitle;
+  // A base section retitled later keeps its old key as its `id`, so an
+  // extension that still names it by the old title finds it by that id. A
+  // title variant of a section with no id stays a separate section.
+  return sections.findIndex(candidate => candidate.id === key);
 }
 
 /**

package/foundation/discovery/docs-discovery.test.mjs

@@ -509,6 +509,27 @@ describe('mergeTopic', () => {
     expect(base.sections[0].content[0].text).toBe('npm i');
   });
 
+  it('finds a retitled base section by the key its old title derives', () => {
+    // A base section retitled later keeps its old key as its `id`; an
+    // extension that still names it by the old title replaces it.
+    const merged = mergeTopic(
+      {
+        ...base,
+        sections: [
+          {id: 'quick-start', title: 'Wrap your app in a theme', content: []},
+          {id: 'tokens', title: 'Tokens', content: []},
+        ],
+      },
+      {sections: [{title: 'Quick Start', content: []}]},
+    );
+    expect(merged.sections.map(section => [section.id, section.title])).toEqual(
+      [
+        ['quick-start', 'Quick Start'],
+        ['tokens', 'Tokens'],
+      ],
+    );
+  });
+
   it('replaces a section by stable ID even when its title changes', () => {
     const merged = mergeTopic(
       {

package/foundation/discovery/docs-section-key.d.mts

@@ -32,7 +32,7 @@ export function sectionTitleKey(title: unknown): string;
 export function sectionKey(section: any): string;
 /**
  * A name as a docs-tree route segment: lowercase words joined by hyphens, so
- * `integrationPackCheck` and `integration pack` both read naturally.
+ * `integrationPackCheck` and `integration verify` both read naturally.
  * @param {string} name
  * @returns {string}
  */