@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ee13359

package/clients/cli/commands/gap-report.doc.mjs

@@ -10,27 +10,37 @@ export const doc = {
   type: 'command',
   name: 'gap-report',
   displayName: 'astryx gap-report',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Route a design-system gap to its owning package',
   description:
     'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability. The command selects an explicit package first, then a unique component owner, then Core. The report fans out to every effective handler: project config first, then each loaded integration in config order. Public handlers require --confirm-public per handler; internal handlers always run. A handler failure is isolated and does not prevent later handlers.',
   fn: 'gapReport',
-  args: [{name: 'component', param: 'component', required: false}],
+  args: [
+    {
+      name: 'component',
+      param: 'component',
+      required: false,
+      description:
+        'Component or design-system area the gap is about, up to 120 characters. Required unless --list-categories is set.',
+    },
+  ],
   options: [
     {
       flag: '--category <category>',
       param: 'options.category',
-      description: 'Gap category (run --list-categories for values)',
+      description:
+        'Gap category (run --list-categories for values). Required unless --list-categories is set.',
     },
     {
       flag: '--reason <reason>',
       param: 'options.reason',
-      description: 'What capability was missing or difficult',
+      description:
+        'What capability was missing or difficult, up to 2000 characters. Required unless --list-categories is set.',
     },
     {
       flag: '--additional-context <text>',
       param: 'options.detail',
-      description: 'Optional additional context',
+      description: 'Optional additional context, up to 8000 characters',
     },
     {
       flag: '--package <pkg>',
@@ -45,7 +55,8 @@ export const doc = {
     {
       flag: '--list-categories',
       param: 'options.listCategories',
-      description: 'List valid report categories without filing',
+      description:
+        'List valid report categories without filing; the component and the other gap-report options are ignored',
     },
   ],
   examples: [

package/clients/cli/commands/gap-report.test.mjs

@@ -196,3 +196,75 @@ export default {};\n`,
     });
   });
 });
+
+describe('gap-report control docs', () => {
+  const REQUIRED = 'Required unless --list-categories is set.';
+
+  it('help and manifest say which inputs are required and how long they may be', async () => {
+    const help = await runCli(['gap-report', '--help']);
+    expect(help.status).toBe(0);
+    const manifest = JSON.parse((await runCli(['manifest', '--json'])).stdout);
+    const entry = manifest.data.commands.find(
+      (/** @type {{name: string}} */ command) => command.name === 'gap-report',
+    );
+    /** @param {string} flag @returns {string} */
+    const option = flag =>
+      entry.options.find(
+        (/** @type {{flag: string}} */ item) => item.flag.split(' ')[0] === flag,
+      )?.description ?? '';
+    const component = entry.arguments[0].description;
+
+    for (const text of [component, option('--category'), option('--reason')]) {
+      expect(text).toContain(REQUIRED);
+      expect(help.stdout).toContain(text);
+    }
+    expect(option('--list-categories')).toContain(
+      'the component and the other gap-report options are ignored',
+    );
+
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-gap-limits-'));
+    try {
+      fs.writeFileSync(
+        path.join(cwd, 'package.json'),
+        JSON.stringify({name: 'fixture-app'}),
+      );
+      const base = {cwd, category: /** @type {const} */ ('docs_gap'), reason: 'x'};
+      /** @type {Array<[string, (value: string) => Promise<unknown>]>} */
+      const limits = [
+        [component, value => gapReport(value, base)],
+        [option('--reason'), value => gapReport('Button', {...base, reason: value})],
+        [
+          option('--additional-context'),
+          value => gapReport('Button', {...base, detail: value}),
+        ],
+      ];
+      for (const [text, call] of limits) {
+        const limit = Number(/up to (\d+) characters/.exec(text)?.[1]);
+        expect(limit, text).toBeGreaterThan(0);
+        await expect(call('x'.repeat(limit))).resolves.toMatchObject({
+          type: 'gap-report.file',
+        });
+        await expect(call('x'.repeat(limit + 1))).rejects.toMatchObject({
+          code: 'ERR_INVALID_ARGUMENT',
+        });
+      }
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  });
+
+  it('enforces the documented requirement', async () => {
+    for (const [component, options] of [
+      [undefined, {category: 'docs_gap', reason: 'x'}],
+      ['Button', {reason: 'x'}],
+      ['Button', {category: 'docs_gap'}],
+    ]) {
+      await expect(gapReport(component, options)).rejects.toMatchObject({
+        code: 'ERR_MISSING_ARGUMENT',
+      });
+    }
+    await expect(
+      gapReport(undefined, {listCategories: true, category: 'not_real', package: 'nope'}),
+    ).resolves.toMatchObject({type: 'gap-report.categories'});
+  });
+});

package/clients/cli/commands/hook/index.mjs

@@ -20,7 +20,6 @@ import {defineCommand} from '../../lib/define-command.mjs';
 import {resultSet} from '../../../../foundation/debug/index.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
 import {hook as hookApi} from '../../../../api/hook/hook.mjs';
-import {findRelatedBlocks} from '../../../../api/template/template.mjs';
 import {doc as hookCommand} from '../hook.doc.mjs';
 import {doc as hookFn} from '../../../../api/hook/hook.doc.mjs';
 
@@ -169,24 +168,15 @@ export function registerHook(program) {
                   )
                 : formatHookFull(result.data);
 
-          // Show related block templates from relatedComponents
-          const relatedComps = result.data.relatedComponents || [];
-          /** @type {import('../../../../api/template/template.mjs').DiscoveredTemplate[]} */
-          const allBlocks = [];
-          for (const comp of relatedComps) {
-            const blocks = await findRelatedBlocks(comp);
-            for (const b of blocks) {
-              if (!allBlocks.some(existing => existing.dirName === b.dirName)) {
-                allBlocks.push(b);
-              }
-            }
-          }
-
+          // Text projects the envelope only. Block templates are JSON-backed
+          // under `component <name> --blocks`.
+          const related = result.data.relatedComponents ?? [];
           emit(
             code(doc),
-            allBlocks.length > 0 && section('Related block templates'),
-            allBlocks.length > 0 &&
-              records(allBlocks, {fields: ['dirName', 'description']}),
+            related.length > 0 &&
+              text(
+                `Block templates: ${run} component <name> --blocks for ${related.join(', ')}`,
+              ),
           );
           break;
         }

package/clients/cli/commands/hook.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'hook',
   displayName: 'astryx hook',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'List hooks or print hook docs',
   description:
     'Resolves a hook by name and prints its authored doc, or lists the catalog grouped ' +

package/clients/cli/commands/hook.text-projection.test.mjs

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx hook <name>` text is a projection of `hook.detail`: it shows
+ * nothing the JSON envelope does not carry.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {findRelatedBlocks} from '../../../api/template/template.mjs';
+
+const HOOK = 'useAnnounce';
+
+describe('hook detail text projection', () => {
+  it('prints no block templates that the JSON envelope lacks', async () => {
+    const json = await runCli(['--json', 'hook', HOOK]);
+    expect(json.status).toBe(0);
+    const envelope = JSON.parse(json.stdout);
+    expect(envelope.type).toBe('hook.detail');
+    const related = envelope.data.relatedComponents;
+    expect(related.length).toBeGreaterThan(0);
+
+    const blockNames = [];
+    for (const component of related) {
+      for (const block of await findRelatedBlocks(component)) {
+        blockNames.push(block.dirName);
+      }
+    }
+    expect(blockNames.length).toBeGreaterThan(0);
+
+    const text = await runCli(['hook', HOOK]);
+    expect(text.status).toBe(0);
+    const shownButNotInJson = blockNames.filter(
+      name => text.stdout.includes(name) && !json.stdout.includes(name),
+    );
+    expect(shownButNotInJson).toEqual([]);
+  });
+
+  it('points at the JSON-backed block lookup for each related component', async () => {
+    const text = await runCli(['hook', HOOK]);
+    expect(text.stdout).toMatch(/component <name> --blocks/);
+    expect(text.stdout).toContain('VisuallyHidden');
+    expect(text.stdout).toContain('Toast');
+  });
+});

package/clients/cli/commands/init.doc.mjs

@@ -12,43 +12,51 @@ export const doc = {
   type: 'command',
   name: 'init',
   displayName: 'astryx init',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Initialize the design system in your project',
   description:
     'Non-interactive project setup (no prompts, so it behaves the same for humans, ' +
     'agents, and CI). By default it installs the AGENTS.md/CLAUDE.md agent-docs, ' +
     'including guidance from configured integrations, and prints getting-started ' +
     'guidance; features/--all add theme and page-building ' +
-    'guidance and can scaffold a starter template.',
+    'guidance and write an annotated theme template.',
   fn: 'init',
   options: [
     {
       flag: '--features <list>',
       param: 'options.features',
       description:
-        'Comma-separated features to install (agents, theme, template)',
+        'Comma-separated features to install (agents, theme, template). An unknown feature exits 1 with ERR_UNKNOWN_FEATURE. ' +
+        'Ignored with --all or --remove-agents',
     },
     {
       flag: '--all',
       param: 'options.all',
-      description: 'Install all features, no prompts',
+      description: 'Install all features (agents, theme, template); overrides --features',
     },
     {
       flag: '--remove-agents',
       param: 'options.removeAgents',
-      description: 'Remove AI agent docs from all agent doc files',
+      description:
+        'Remove the managed block from AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, .cursorrules, .hermes.md and HERMES.md ' +
+        "(deleting AGENTS.md or .claude/CLAUDE.md when only init's heading is left) and do nothing else. " +
+        '--features, --all, --agent and --agent-docs-path are ignored; a file written with --agent-docs-path keeps its block',
     },
     {
       flag: '--agent <tool>',
       param: 'options.agent',
       choices: ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'],
       description:
-        'Target AI tool for agent docs: claude, cursor, codex, hermes, muse, all',
+        'Target AI tool for agent docs: claude, cursor, codex, hermes, muse, all. An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
+        'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence',
     },
     {
       flag: '--agent-docs-path <path...>',
       param: 'options.agentDocsPath',
-      description: 'Explicit file path(s) for agent docs',
+      description:
+        'Explicit file path(s) for agent docs, inside the project; takes precedence over --agent. ' +
+        'If any path is outside the project, no agent docs are written and the command exits 1. ' +
+        'Used only when agent docs are installed',
     },
   ],
   examples: [
@@ -57,10 +65,13 @@ export const doc = {
     {label: 'Machine-readable receipt', cli: 'astryx init --json'},
   ],
   exitCodes: [
-    {code: 0, when: 'success'},
+    {
+      code: 0,
+      when: 'success, including agent docs that could not be written for a reason other than a path escape (reported as docsError)',
+    },
     {
       code: 1,
-      when: 'unknown --agent, an unknown feature or template, or a starter template would overwrite an existing page',
+      when: 'an unknown --agent or feature, or an --agent-docs-path outside the project',
     },
   ],
   related: ['doctor', 'upgrade', 'build', 'theme'],

package/clients/cli/commands/init.flag-help.test.mjs

@@ -0,0 +1,153 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx init` documents how its flags interact and when it exits 1, and
+ * behaves as documented. Option text is read from the generated manifest (the
+ * same strings `--help` prints); exit codes from the CommandDoc.
+ */
+
+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';
+import {doc as initDoc} from './init.doc.mjs';
+
+const MARKER_START = '<!-- ASTRYX:START -->';
+
+/** @type {string} */
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-init-flags-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** @param {string} rel */
+const exists = rel => fs.existsSync(path.join(tmpDir, rel));
+/** @param {string} rel */
+const read = rel => fs.readFileSync(path.join(tmpDir, rel), 'utf8');
+
+/**
+ * init's option descriptions from the manifest, keyed by long flag.
+ * @returns {Promise<Record<string, string>>}
+ */
+async function initOptions() {
+  const {stdout} = await runCli(['--json', 'manifest'], tmpDir);
+  const init = JSON.parse(stdout).data.commands.find(
+    (/** @type {{name: string}} */ c) => c.name === 'init',
+  );
+  return Object.fromEntries(
+    init.options.map((/** @type {{flag: string, description: string}} */ o) => [
+      o.flag.match(/--[a-z-]+/)?.[0],
+      o.description,
+    ]),
+  );
+}
+
+/** @param {string[]} args */
+async function initJson(args) {
+  const result = await runCli(['--json', 'init', ...args], tmpDir);
+  return {status: result.status, envelope: JSON.parse(result.stdout)};
+}
+
+/** @param {number} code */
+const exitWhen = code => initDoc.exitCodes?.find(e => e.code === code)?.when ?? '';
+
+describe('astryx init flag interactions', () => {
+  it('--remove-agents: help says it only removes the block, and it ignores every install flag', async () => {
+    const help = (await initOptions())['--remove-agents'];
+    for (const flag of ['--features', '--all', '--agent', '--agent-docs-path']) {
+      expect(help).toContain(flag);
+    }
+    for (const file of ['AGENTS.md', '.claude/CLAUDE.md', '.cursorrules', '.hermes.md', 'HERMES.md']) {
+      expect(help).toContain(file);
+    }
+    expect(help).toMatch(/--agent-docs-path keeps its block/);
+
+    await initJson(['--agent-docs-path', 'docs/AI.md']);
+    await initJson([]);
+    expect(exists('AGENTS.md')).toBe(true);
+
+    const removed = await initJson([
+      '--remove-agents',
+      '--features',
+      'bogus',
+      '--all',
+      '--agent',
+      'bogus',
+      '--agent-docs-path',
+      'docs/AI.md',
+    ]);
+    expect(removed.status).toBe(0);
+    expect(removed.envelope.type).toBe('init.remove');
+    expect(exists('AGENTS.md')).toBe(false);
+    expect(exists('theme.template.ts')).toBe(false);
+    expect(read('docs/AI.md')).toContain(MARKER_START);
+  });
+
+  it('--all: help says it overrides --features, and an unknown feature beside it is not checked', async () => {
+    const options = await initOptions();
+    expect(options['--all']).toMatch(/overrides --features/);
+    expect(options['--features']).toMatch(/Ignored with --all or --remove-agents/);
+    expect(options['--features']).toContain('ERR_UNKNOWN_FEATURE');
+
+    const {status, envelope} = await initJson(['--all', '--features', 'bogus']);
+    expect(status).toBe(0);
+    expect(envelope.data.features).toEqual(['agents', 'theme', 'template']);
+  });
+
+  it('--agent and --agent-docs-path: help states their scope and precedence, and the CLI follows it', async () => {
+    const options = await initOptions();
+    expect(options['--agent']).toMatch(/Used only when agent docs are installed/);
+    expect(options['--agent']).toMatch(/--agent-docs-path takes precedence/);
+    expect(options['--agent']).toContain('ERR_UNKNOWN_AGENT');
+    expect(options['--agent-docs-path']).toMatch(/takes precedence over --agent/);
+    expect(options['--agent-docs-path']).toMatch(/outside the project.*exits 1/);
+    expect(options['--agent-docs-path']).toMatch(/Used only when agent docs are installed/);
+
+    const unused = await initJson([
+      '--features',
+      'theme',
+      '--agent',
+      'bogus',
+      '--agent-docs-path',
+      '../outside.md',
+    ]);
+    expect(unused.status).toBe(0);
+    expect(unused.envelope.data.docsWritten).toEqual([]);
+
+    const explicit = await initJson(['--agent', 'claude', '--agent-docs-path', 'docs/AI.md']);
+    expect(explicit.status).toBe(0);
+    expect(explicit.envelope.data.docsWritten).toEqual(['docs/AI.md']);
+    expect(exists('CLAUDE.md') || exists('.claude/CLAUDE.md')).toBe(false);
+  });
+});
+
+describe('astryx init exit codes', () => {
+  it('exit 1: the CommandDoc lists an --agent-docs-path escape, which exits 1 in both modes and writes nothing', async () => {
+    expect(exitWhen(1)).toMatch(/--agent-docs-path outside the project/);
+    // The CLI never scaffolds a page template, so no template case can exit 1.
+    expect(exitWhen(1)).not.toMatch(/template/);
+
+    const text = await runCli(['init', '--agent-docs-path', 'ok.md', '../outside.md'], tmpDir);
+    const json = await initJson(['--agent-docs-path', 'ok.md', '../outside.md']);
+    expect(text.status).toBe(1);
+    expect(json.status).toBe(1);
+    expect(json.envelope.data.docsError.kind).toBe('path-safety');
+    expect(exists('ok.md')).toBe(false);
+  });
+
+  it('exit 0: the CommandDoc says a soft agent-docs failure still exits 0, and it does', async () => {
+    expect(exitWhen(0)).toMatch(/docsError/);
+
+    // A directory where AGENTS.md belongs makes the write fail without a path escape.
+    fs.mkdirSync(path.join(tmpDir, 'AGENTS.md'));
+    const {status, envelope} = await initJson([]);
+    expect(status).toBe(0);
+    expect(envelope.data.docsError).toEqual({kind: 'install-failed'});
+  });
+});

package/clients/cli/commands/integration-add.controls.test.mjs

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {createProgram} from '../index.mjs';
+import {buildManifest} from '../lib/manifest.mjs';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {doc as fnDoc} from '../../../api/integration/integrationAdd.doc.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(
+    path.join(process.cwd(), '.astryx-integration-add-controls-'),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    `${JSON.stringify({name: '@acme/widgets', version: '1.0.0'})}\n`,
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** What each `integration add` control must define on the discovery surfaces. */
+const DEFINITIONS = {
+  name: [
+    'PascalCase for component',
+    'lowercase kebab-case for template, codemod, and theme',
+    'letters, digits, _ and - for doc',
+    'literal guidance line for agent-doc',
+  ],
+  '--type <type>': ['page (default) or block', 'only valid for template'],
+  '--replaces <topic>': ['only valid for doc', 'not with --extends'],
+  '--extends <topic>': ['only valid for doc', 'not with --replaces'],
+  '--to <version>': ['Exact semver', 'required for codemod and only valid there'],
+};
+
+describe('integration add control definitions', () => {
+  it('defines accepted values, defaults, and interactions in help', async () => {
+    const program = await createProgram();
+    const add = program.commands
+      .find(command => command.name() === 'integration')
+      ?.commands.find(command => command.name() === 'add');
+    const help = add?.helpInformation() ?? '';
+
+    for (const phrases of Object.values(DEFINITIONS)) {
+      for (const phrase of phrases) expect(help).toContain(phrase);
+    }
+  });
+
+  it('defines the same controls in the manifest', async () => {
+    const manifest = buildManifest(await createProgram());
+    const add = manifest.commands
+      .find(command => command.name === 'integration')
+      ?.subcommands?.find(command => command.name === 'integration add');
+    /** @type {Record<string, string>} */
+    const described = {};
+    for (const arg of add?.arguments ?? []) described[arg.name] = arg.description;
+    for (const option of add?.options ?? []) {
+      described[option.flag] = option.description;
+    }
+
+    for (const [control, phrases] of Object.entries(DEFINITIONS)) {
+      for (const phrase of phrases) {
+        expect(described[control], control).toContain(phrase);
+      }
+    }
+  });
+
+  it('defines the same controls for integrationAdd()', () => {
+    /** @param {string} name */
+    const param = name => fnDoc.params?.find(item => item.name === name);
+
+    for (const phrase of DEFINITIONS.name.slice(0, 3)) {
+      expect(param('name')?.description).toContain(phrase);
+    }
+    expect(param('options.templateType')?.default).toBe("'page'");
+    expect(param('options.replaces')?.description).toContain(
+      'not with options.extends',
+    );
+    expect(param('options.extends')?.description).toContain(
+      'not with options.replaces',
+    );
+    expect(param('options.to')?.description).toContain('Exact target semver');
+    expect(param('options.to')?.description).toContain('only valid there');
+  });
+
+  it('behaves as the definitions say', async () => {
+    const both = await runCli(
+      [
+        'integration',
+        'add',
+        'doc',
+        'acme-guide',
+        '--replaces',
+        'getting-started',
+        '--extends',
+        'theme',
+        '--json',
+      ],
+      tmpDir,
+    );
+    expect(both.status).toBe(1);
+    expect(JSON.parse(both.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+
+    const looseVersion = await runCli(
+      ['integration', 'add', 'codemod', 'rename-prop', '--to', '1.2', '--json'],
+      tmpDir,
+    );
+    expect(looseVersion.status).toBe(1);
+    expect(JSON.parse(looseVersion.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+
+    const typeElsewhere = await runCli(
+      ['integration', 'add', 'component', 'AcmeWidget', '--type', 'page', '--json'],
+      tmpDir,
+    );
+    expect(typeElsewhere.status).toBe(1);
+    expect(JSON.parse(typeElsewhere.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+
+    const page = await runCli(
+      ['integration', 'add', 'template', 'acme-page', '--json'],
+      tmpDir,
+    );
+    expect(page.status).toBe(0);
+    expect(
+      fs.readFileSync(path.join(tmpDir, 'templates', 'acme-page.doc.mjs'), 'utf-8'),
+    ).toContain("type: 'page'");
+  });
+});

package/clients/cli/commands/integration-add.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'command',
   name: 'integration add',
   displayName: 'astryx integration add',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Add one working contribution to an integration package',
   description:
     'Writes the complete minimum shape the selected contribution needs, creates the integration manifest on first use, declares the root only after a valid contribution exists, and verifies the result through the same discovery contract the packed-package check uses.',
@@ -22,7 +22,7 @@ export const doc = {
       param: 'name',
       required: true,
       description:
-        'Contribution name; for agent-doc this is the literal guidance line',
+        'Contribution name: PascalCase for component (AcmeWidget); lowercase kebab-case for template, codemod, and theme (account-card); letters, digits, _ and - for doc; the literal guidance line for agent-doc',
     },
   ],
   options: [
@@ -35,22 +35,32 @@ export const doc = {
       flag: '--type <type>',
       param: 'options.templateType',
       choices: ['page', 'block'],
-      description: 'Template type (page or block); only valid for template',
+      description:
+        'Template type: page (default) or block; only valid for template',
     },
     {
       flag: '--replaces <topic>',
       param: 'options.replaces',
-      description: 'Replace an existing doc topic; only valid for doc',
+      description:
+        'Existing doc topic this one replaces (letters, digits, _ and -); only valid for doc and not with --extends',
     },
     {
       flag: '--extends <topic>',
       param: 'options.extends',
-      description: 'Extend an existing doc topic; only valid for doc',
+      description:
+        'Existing doc topic this one extends (letters, digits, _ and -); only valid for doc and not with --replaces',
+    },
+    {
+      flag: '--parent <namespace>',
+      param: 'options.parent',
+      description:
+        "Namespace of this package to place the doc in, as a guide in its `guides` slot; writes the namespace doc when it is missing, and declares the CLI that reads it as an optional `@astryxdesign/cli` peer. Only valid for doc, and not with --replaces or --extends",
     },
     {
       flag: '--to <version>',
       param: 'options.to',
-      description: 'Target version for a codemod; required for codemod',
+      description:
+        'Exact semver the codemod migrates to (e.g. 1.2.0); required for codemod and only valid there',
     },
   ],
   examples: [
@@ -63,6 +73,22 @@ export const doc = {
       label: 'Add a page template',
       cli: 'astryx integration add template dashboard',
     },
+    {
+      label: 'Add a block template',
+      cli: 'astryx integration add template account-card --type block',
+    },
+    {
+      label: 'Replace a doc topic',
+      cli: 'astryx integration add doc acme-getting-started --replaces getting-started',
+    },
+    {
+      label: 'Extend a doc topic',
+      cli: 'astryx integration add doc acme-theming --extends theme',
+    },
+    {
+      label: 'Add a guide to the package\'s own docs section',
+      cli: 'astryx integration add doc deploying --parent acme',
+    },
     {
       label: 'Add a codemod',
       cli: 'astryx integration add codemod rename-widget --to 1.2.0',