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

package/clients/cli/commands/doctor-integration.package-json.test.mjs

@@ -0,0 +1,53 @@
+// 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 {runCli} from '../../../test-utils/run-cli.mjs';
+import {validateIntegration} from '../../../api/integration/validate-integration.mjs';
+
+const NO_MANIFEST = 'No astryx.integration.* found next to package.json.';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-doctor-pkgjson-'));
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "@acme/widgets",}\n');
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.integration.mjs'),
+    "export default {\n  templates: './templates',\n};\n",
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('doctor integration with a malformed package.json', () => {
+  it('keeps a null name for the no-manifest case only', async () => {
+    const result = await validateIntegration(undefined, {cwd: tmpDir});
+
+    expect(result.data.name).toBe('(local package)');
+    expect(result.data.issues.map(issue => issue.code)).toEqual([
+      'invalid_package_json',
+    ]);
+  });
+
+  for (const leaf of ['validate', 'templates', 'components', 'docs']) {
+    it(`${leaf} prints the package.json error instead of "no manifest"`, async () => {
+      const text = await runCli(['doctor', 'integration', leaf], tmpDir);
+      const json = await runCli(
+        ['doctor', 'integration', leaf, '--json'],
+        tmpDir,
+      );
+
+      expect(text.status).toBe(1);
+      expect(json.status).toBe(1);
+      expect(text.stdout).not.toContain(NO_MANIFEST);
+      expect(text.stdout).toContain('invalid_package_json');
+      expect(JSON.parse(json.stdout).data.issues).toContainEqual(
+        expect.objectContaining({code: 'invalid_package_json'}),
+      );
+    });
+  }
+});

package/clients/cli/commands/doctor-integration.test.mjs

@@ -31,6 +31,8 @@ function writeIntegration({
   id,
   name = 'Integration template',
   missingRoot = false,
+  replacements,
+  type = 'page',
 }) {
   fs.writeFileSync(
     path.join(tmpDir, 'package.json'),
@@ -44,8 +46,8 @@ function writeIntegration({
   const stem = path.join(tmpDir, 'templates', id);
   fs.mkdirSync(path.dirname(stem), {recursive: true});
   fs.writeFileSync(
-    `${stem}.template.mjs`,
-    `export default {type: 'page', name: ${JSON.stringify(name)}, description: 'fixture'};\n`,
+    `${stem}.doc.mjs`,
+    `export default {type: '${type}', name: ${JSON.stringify(name)}, description: 'fixture'${replacements?.[id] == null ? '' : `, replaces: ${JSON.stringify(replacements[id])}`}};\n`,
   );
   fs.writeFileSync(
     `${stem}.tsx`,
@@ -124,7 +126,12 @@ describe('doctor integration — command', () => {
       return true;
     });
 
-    await createProgram().parseAsync(['node', 'astryx', 'doctor', 'integration']);
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+    ]);
 
     const output = writes.join('');
     expect(output).toContain('validate [package]');
@@ -136,7 +143,9 @@ describe('doctor integration — command', () => {
 
   it('explains the optional package argument in every leaf help', () => {
     const program = createProgram();
-    const doctor = program.commands.find(command => command.name() === 'doctor');
+    const doctor = program.commands.find(
+      command => command.name() === 'doctor',
+    );
     const integration = doctor?.commands.find(
       command => command.name() === 'integration',
     );
@@ -152,7 +161,10 @@ describe('doctor integration — command', () => {
   });
 
   it('templates explains how to check an installed package when no local manifest exists', async () => {
-    fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({name: 'plain'}));
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      JSON.stringify({name: 'plain'}),
+    );
     process.chdir(tmpDir);
 
     await createProgram().parseAsync([
@@ -239,6 +251,71 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
+  it('templates reports an intentional replacement and the Core-original command', async () => {
+    const core = (await discoverCoreTemplates()).find(
+      template => template.type === 'page',
+    );
+    expect(core).toBeDefined();
+    writeIntegration({
+      id: 'acme-app-shell',
+      type: core.type,
+      replacements: {'acme-app-shell': core.dirName},
+    });
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'templates',
+    ]);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.data.issues).toEqual([]);
+    expect(parsed.data.conflicts).toEqual([
+      expect.objectContaining({
+        id: 'acme-app-shell',
+        relationship: 'replaces',
+        replaces: core.dirName,
+        severity: 'info',
+      }),
+    ]);
+    expect(parsed.data.conflicts[0].command).toContain(
+      `--package @astryxdesign/core`,
+    );
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('templates exits 1 for a missing replacement target', async () => {
+    writeIntegration({
+      id: 'acme-app-shell',
+      replacements: {'acme-app-shell': 'missing-core-shell'},
+    });
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      '--json',
+      'doctor',
+      'integration',
+      'templates',
+    ]);
+
+    const parsed = JSON.parse(logCalls.join('\n'));
+    expect(parsed.data.issues).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          code: 'missing_template_replacement_target',
+          severity: 'error',
+        }),
+      ]),
+    );
+    expect(process.exitCode).toBe(1);
+  });
+
   it('templates exits 1 when structural errors prevent a trustworthy check', async () => {
     writeIntegration({missingRoot: true});
     process.chdir(tmpDir);
@@ -278,9 +355,7 @@ describe('doctor integration — command', () => {
     const output = logCalls.join('\n');
     expect(output).toContain('[warn]');
     expect(output).toContain(core.name);
-    expect(output).toContain(
-      `component ${core.name} --package @acme/widgets`,
-    );
+    expect(output).toContain(`component ${core.name} --package @acme/widgets`);
     expect(process.exitCode).toBeUndefined();
   });
 

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

@@ -12,7 +12,7 @@ export const doc = {
   type: 'command',
   name: 'doctor',
   displayName: 'astryx doctor',
-  namespace: 'cli',
+  namespace: 'cli/commands',
   summary: 'Diagnose Astryx projects and integration packages',
   description:
     'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +

package/clients/cli/commands/doctor.mjs

@@ -17,7 +17,7 @@ import {
   validateIntegration,
 } from '../../../api/integration/validate-integration.mjs';
 import {jsonOut} from '../../../foundation/response/json.mjs';
-import {emit, section, records, text} from '../formatters/index.mjs';
+import {emit, section, record, records, text} from '../formatters/index.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as doctorCommand} from './doctor.doc.mjs';
 import {doc as doctorIntegrationGroup} from './doctor-integration.doc.mjs';
@@ -55,7 +55,7 @@ function integrationLabel(data) {
  * @param {import('../../../api/doctor/doctor.mjs').DoctorReport} report
  */
 function printHuman(report) {
-  const {pass, warn, fail, info} = report.summary;
+  const {warn, fail} = report.summary;
   const closing =
     fail > 0
       ? 'Some checks failed. Address the items marked [fail] above.'
@@ -63,18 +63,15 @@ function printHuman(report) {
         ? 'No failures — but review the [warn] warnings above when you can.'
         : 'All checks passed. Your Astryx setup looks healthy.';
 
+  // Field names are the JSON keys, so text and --json map one to one.
   emit(
     section('astryx doctor — diagnosing your setup'),
     records(report.checks, {
-      fields: ['status', 'label', 'message', 'fix'],
-      labels: {label: 'check'},
+      fields: ['id', 'status', 'label', 'message', 'fix'],
       format: {status: statusToken},
     }),
-    text(
-      `Summary: ${pass} passed, ${warn} warning${warn === 1 ? '' : 's'}, ` +
-        `${fail} failure${fail === 1 ? '' : 's'}` +
-        (info ? `, ${info} info` : ''),
-    ),
+    section('summary'),
+    record(report.summary, {fields: ['pass', 'warn', 'fail', 'info']}),
     text(closing),
   );
 }
@@ -128,14 +125,18 @@ function printTemplateConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
-  if (data.conflicts.length === 0) {
-    output.push(text('[ok] No template ids conflict with Core.'));
-  } else {
+  if (data.conflicts.length === 0 && data.issues.length === 0) {
+    output.push(
+      text('[ok] No template replacements or id conflicts with Core.'),
+    );
+  } else if (data.conflicts.length > 0) {
     output.push(
       records(data.conflicts, {
         fields: [
           'severity',
+          'relationship',
           'id',
+          'replaces',
           'integrationPackage',
           'integrationType',
           'integrationName',
@@ -144,10 +145,7 @@ function printTemplateConflicts(data) {
         ],
         format: {severity: statusToken},
       }),
-      text(
-        `${data.conflicts.length} Core template conflict(s). ` +
-          'Renaming is recommended but optional; keep the package-qualified command if the overlap is intentional.',
-      ),
+      text(`${data.conflicts.length} Core template relationship(s).`),
     );
   }
   emit(...output);
@@ -168,7 +166,13 @@ function printComponentConflicts(data) {
   } else {
     output.push(
       records(data.conflicts, {
-        fields: ['severity', 'name', 'integrationPackage', 'message', 'command'],
+        fields: [
+          'severity',
+          'name',
+          'integrationPackage',
+          'message',
+          'command',
+        ],
         format: {severity: statusToken},
       }),
       text(
@@ -190,6 +194,13 @@ function printDocConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
+  if (
+    !data.issues.some(
+      issue => issue.severity === 'error' || issue.code === 'invalid_doc_graph',
+    )
+  ) {
+    output.push(text('[ok] The docs tree and every link in these docs check out.'));
+  }
   if (data.findings.length === 0) {
     output.push(text('[ok] No doc topics overlap with Core.'));
   } else {
@@ -275,7 +286,8 @@ async function runAuthoringCheck(program, pkg, kind) {
   const structuralErrors = summarizeIssues(result.data.issues).errors;
   const docErrors =
     result.type === 'integration.doc-conflicts'
-      ? result.data.findings.filter(finding => finding.severity === 'error').length
+      ? result.data.findings.filter(finding => finding.severity === 'error')
+          .length
       : 0;
   if (structuralErrors > 0 || docErrors > 0) process.exitCode = 1;
   return NO_RESULT_SET;
@@ -290,13 +302,6 @@ export function registerDoctor(program) {
     fn: doctorFn,
     action: async () => runProjectDoctor(program),
   });
-  doctorCmd.addHelpText(
-    'after',
-    '\nExit code:\n' +
-      '  0  no failures (warnings are allowed) — safe as a CI gate\n' +
-      '  1  one or more checks failed\n',
-  );
-
   /** @type {import('commander').Command} */
   let integrationCmd;
   integrationCmd = defineCommand(doctorCmd, doctorIntegrationGroup, {

package/clients/cli/commands/doctor.test.mjs

@@ -354,3 +354,45 @@ describe('doctor — command', () => {
     }
   });
 });
+
+describe('doctor — text output mirrors the JSON', () => {
+  /** @param {string} line */
+  const field = line => /^(\w+):\s+(.*)$/.exec(line)?.slice(1) ?? [line, ''];
+
+  it('prints every check and summary field under its JSON key', async () => {
+    const prevCwd = process.cwd();
+    const prevExit = process.exitCode;
+    process.chdir(tmpDir);
+    try {
+      await createProgram().parseAsync(['node', 'astryx', '--json', 'doctor']);
+      const {checks, summary} = JSON.parse(logCalls.join('\n')).data;
+      logCalls = [];
+      await createProgram().parseAsync(['node', 'astryx', 'doctor']);
+      const blocks = logCalls
+        .join('\n')
+        .split(/\n{2,}/)
+        .map(block => block.split('\n').map(field));
+
+      for (const check of checks) {
+        const block = blocks.find(fields =>
+          fields.some(([key, value]) => key === 'id' && value === check.id),
+        );
+        expect(block, `no text record for check ${check.id}`).toBeDefined();
+        expect(
+          /** @type {string[][]} */ (block).map(([key]) => key).sort(),
+        ).toEqual(Object.keys(check).sort());
+      }
+
+      const heading = blocks.findIndex(
+        fields => fields.length === 1 && fields[0][0] === 'summary',
+      );
+      expect(heading, 'no summary section').toBeGreaterThan(-1);
+      expect(blocks[heading + 1]).toEqual(
+        Object.entries(summary).map(([key, count]) => [key, String(count)]),
+      );
+    } finally {
+      process.chdir(prevCwd);
+      process.exitCode = prevExit;
+    }
+  }, 60_000);
+});

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