@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

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',
@@ -103,6 +104,9 @@ export const JSON_SUPPORTED = new Set([
   'doctor integration templates',
   'doctor integration components',
   'doctor integration docs',
+  'layout expand',
+  'layout check',
+  'layout grammar',
 ]);
 
 /**
@@ -261,6 +265,7 @@ const commands = [
   {name: 'gap-report', path: './commands/gap-report.mjs', register: 'registerGapReport'},
   // agent-docs folded into init — functions still importable from agent-docs.mjs
   {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
+  {name: 'layout', path: './commands/layout.mjs', register: 'registerLayout'},
   {name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
   {name: 'theme', path: './commands/build-theme.mjs', register: 'registerTheme'},
   {name: 'integration', path: './commands/integration.mjs', register: 'registerIntegration'},
@@ -338,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'),
     )
@@ -467,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,
@@ -601,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

@@ -34,14 +34,14 @@ manifest.commands.forEach(walk);
 
 describe('command exit codes', () => {
   it('every CommandDoc documents its exit codes', () => {
-    expect(commandDocs.length).toBeGreaterThan(25);
+    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',
+    '`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,9 +51,32 @@ 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);
     },
   );
 
+  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/);

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

@@ -225,6 +225,23 @@ describe('--json shim: help shown for a failed invocation is an error envelope',
     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));
@@ -240,9 +257,6 @@ describe('--json shim: help shown for a failed invocation is an error envelope',
   });
 
   it('a group added after install gets the same error envelope', () => {
-    // This is the only coverage of the no-subcommand path: every group the CLI
-    // ships has an action of its own (see command-result-coverage.test.mjs), so
-    // a group without one has to be built here.
     const program = new Command('astryx');
     installJsonShim(program);
     // Added later, so only the prototype-level patch covers its outputHelp.
@@ -268,11 +282,11 @@ describe('--json shim: help shown for a failed invocation is an error envelope',
     expect(parsed.suggestions).toEqual([{name: 'late child', reason: 'available subcommand'}]);
   });
 
-  it('astryx help theme --json still emits the help envelope, exit 0', async () => {
-    const {status, stdout} = await runCli(['help', 'theme', '--json']);
+  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 theme');
+    expect(parsed.data.command).toBe('astryx layout');
   });
 });

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
@@ -92,16 +93,28 @@ 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'],
   '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'],
 };
 
+/**
+ * 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[]>}
@@ -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'],
@@ -180,6 +193,11 @@ const EXAMPLES = {
     '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'],
 };
 
 /**

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.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}
  */

package/foundation/discovery/docs-section-key.mjs

@@ -95,7 +95,7 @@ function legacyTitleMatchIndex(sections, query) {
 
 /**
  * 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}
  */

package/foundation/discovery/template-adapter.mjs

@@ -4,7 +4,7 @@
  * @file Shared template discovery + IO.
  *
  * Owns everything the template leaves (list/show/skeleton/copy) AND other
- * commands (component, search, init, discover, Doctor integration)
+ * commands (component, layout, search, init, discover, Doctor integration)
  * share: template discovery across core/external/integration sources, the
  * template-spec loaders, and the cross-command helpers (stripTemplateAssetRefs,
  * findShowcase, findRelatedBlocks, extractComponents, listTemplates). The