@astryxdesign/cli 0.6.4 → 0.6.5-canary.031021b

package/clients/cli/commands/discover.sources.test.mjs

@@ -0,0 +1,267 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx discover` with a discover source: the list, a package page, a
+ * search, and the refused option pair, driven through the real CLI against a
+ * hermetic project whose astryx.config sets `discover`. Saved copies go to a
+ * temp cache directory, never the project.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const CONFIG = `
+const packages = [
+  {
+    package: '@test/kit',
+    integration: 'test-kit',
+    aliases: [],
+    latest: '3.2.0',
+    versions: [
+      {version: '3.2.0', publishedAt: '2026-09-29T00:00:00.000Z', prerelease: false, status: 'ok'},
+      {version: '3.1.4', publishedAt: '2026-09-01T00:00:00.000Z', prerelease: false, status: 'ok'},
+    ],
+    contributions: [{kind: 'component', name: 'Dial'}],
+  },
+  {
+    package: '@test/charts',
+    integration: 'test-charts',
+    aliases: [],
+    latest: '2.0.0',
+    versions: [
+      {version: '2.1.0-beta.1', publishedAt: '2026-09-25T00:00:00.000Z', prerelease: true, status: 'ok'},
+      {version: '2.0.0', publishedAt: '2026-09-20T00:00:00.000Z', prerelease: false, status: 'ok'},
+    ],
+    contributions: [
+      {kind: 'component', name: 'Chart'},
+      {kind: 'template', name: 'pages/Report'},
+    ],
+  },
+  {
+    package: '@test/boards',
+    integration: 'test-boards',
+    aliases: [],
+    latest: '1.0.0',
+    versions: [
+      {version: '1.0.0', publishedAt: '2026-09-10T00:00:00.000Z', prerelease: false, status: 'ok'},
+    ],
+    contributions: [{kind: 'template', name: 'pages/DialBoard'}],
+  },
+];
+
+export default {
+  integrations: ['@test/kit'],
+  async discover({package: name}) {
+    return {
+      schemaVersion: 1,
+      source: {name: 'Test catalog', generatedAt: '2026-09-30T00:00:00.000Z', complete: true},
+      packages: packages.filter(p => name == null || p.package === name),
+    };
+  },
+};
+`;
+
+let tmpDir;
+let project;
+/** @type {Record<string, string | undefined>} */
+let savedEnv;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-discover-sources-'));
+  project = path.join(tmpDir, 'project');
+  const pkgDir = path.join(project, 'node_modules', '@test', 'kit');
+  fs.mkdirSync(path.join(pkgDir, 'components'), {recursive: true});
+  fs.writeFileSync(
+    path.join(project, 'package.json'),
+    JSON.stringify({
+      name: 'proj',
+      version: '1.0.0',
+      dependencies: {'@test/kit': '3.1.4'},
+    }),
+  );
+  fs.writeFileSync(path.join(project, 'astryx.config.mjs'), CONFIG);
+  fs.writeFileSync(
+    path.join(pkgDir, 'package.json'),
+    JSON.stringify({name: '@test/kit', version: '3.1.4'}),
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'astryx.integration.mjs'),
+    `export default {components: './components'};\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'components', 'Dial.doc.mjs'),
+    `export const docs = {name: 'Dial', usage: {description: 'A dial.'}};\n`,
+  );
+  fs.writeFileSync(
+    path.join(pkgDir, 'components', 'Dial.tsx'),
+    `export function Dial() { return null; }\n`,
+  );
+  // The saved copy lives in the per-user cache; point it at the temp dir.
+  savedEnv = {
+    HOME: process.env.HOME,
+    XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
+    LOCALAPPDATA: process.env.LOCALAPPDATA,
+  };
+  process.env.HOME = path.join(tmpDir, 'home');
+  process.env.XDG_CACHE_HOME = path.join(tmpDir, 'cache');
+  process.env.LOCALAPPDATA = path.join(tmpDir, 'localappdata');
+});
+
+afterEach(() => {
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/** The per-user cache directory this platform uses under the redirected env. */
+function userCacheDir() {
+  if (process.platform === 'win32') {
+    return path.join(tmpDir, 'localappdata', 'astryx', 'Cache');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(tmpDir, 'home', 'Library', 'Caches', 'astryx');
+  }
+  return path.join(tmpDir, 'cache', 'astryx');
+}
+
+describe('astryx discover with a discover source', () => {
+  it('lists what the project has and what it could add, in --json', async () => {
+    const {status, stdout} = await runCli(['discover', '--json'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    const {data, meta} = JSON.parse(stdout);
+    expect(data).toEqual([
+      expect.objectContaining({
+        name: '@test/kit',
+        components: ['Dial'],
+        version: '3.1.4',
+        latest: '3.2.0',
+      }),
+    ]);
+    expect(meta.available).toEqual([
+      {
+        name: '@test/charts',
+        components: ['Chart'],
+        version: '2.0.0',
+        templates: ['pages/Report'],
+        source: 'Test catalog',
+      },
+      {
+        name: '@test/boards',
+        components: [],
+        version: '1.0.0',
+        templates: ['pages/DialBoard'],
+        source: 'Test catalog',
+      },
+    ]);
+    expect(meta.sources).toEqual([
+      expect.objectContaining({
+        name: 'Test catalog',
+        from: 'astryx.config',
+        status: 'fresh',
+      }),
+    ]);
+  });
+
+  it('prints both sides as records', async () => {
+    const {status, stdout} = await runCli(['discover'], {cwd: project});
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^Installed$/m);
+    expect(stdout).toMatch(/^Available$/m);
+    expect(stdout).toMatch(/^name:\s+@test\/charts$/m);
+    expect(stdout).toMatch(/^latest:\s+3\.2\.0$/m);
+  });
+
+  it('shows a package it does not have with its releases and the command that adds it, and never runs it', async () => {
+    const {status, stdout} = await runCli(['discover', '@test/charts'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/^installed:\s+false$/m);
+    expect(stdout).toContain('- 2.0.0  2026-09-20  latest');
+    expect(stdout).not.toContain('2.1.0-beta.1  ');
+    expect(stdout).toContain('1 prerelease is not listed.');
+    // The verb follows the detected package manager.
+    expect(stdout).toMatch(
+      /^(npm install|pnpm add|yarn add|bun add) @test\/charts$/m,
+    );
+    expect(
+      fs.existsSync(path.join(project, 'node_modules', '@test', 'charts')),
+    ).toBe(false);
+  });
+
+  it('says which item is missing from a package only a source lists', async () => {
+    const {status, stdout} = await runCli(
+      ['discover', '@test/charts/Nope', '--json'],
+      {cwd: project},
+    );
+
+    expect(status).toBe(1);
+    const {code, error} = JSON.parse(stdout);
+    expect(code).toBe('ERR_UNKNOWN_COMPONENT');
+    expect(error).toBe('"Nope" not found in @test/charts');
+  });
+
+  it('searches every kind in every source', async () => {
+    const {status, stdout} = await runCli(['discover', 'report', '--json'], {
+      cwd: project,
+    });
+
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).data.matches).toEqual([
+      {
+        package: '@test/charts',
+        component: 'pages/Report',
+        kind: 'template',
+        installed: false,
+      },
+    ]);
+  });
+
+  it('refuses --installed with --available', async () => {
+    const {status, stdout} = await runCli(
+      ['discover', '--installed', '--available', '--json'],
+      {cwd: project},
+    );
+
+    expect(status).toBe(1);
+    expect(JSON.parse(stdout).code).toBe('ERR_INVALID_OPTION');
+  });
+
+  it('lists every match for a free-text query, even an exact component name, and opens one by its package path', async () => {
+    const exact = await runCli(['discover', 'Dial', '--json'], {cwd: project});
+    const {type, data} = JSON.parse(exact.stdout);
+    expect(type).toBe('discover.search');
+    expect(data.matches.map(m => [m.component, m.installed])).toEqual([
+      ['Dial', true],
+      ['pages/DialBoard', false],
+    ]);
+
+    const opened = await runCli(['discover', '@test/kit/Dial', '--json'], {
+      cwd: project,
+    });
+    expect(JSON.parse(opened.stdout).type).toBe('discover.detail.doc');
+  });
+
+  it('saves the answer in the user cache and writes nothing into the project', async () => {
+    const before = fs.readdirSync(project).sort();
+    await runCli(['discover', '--json'], {cwd: project});
+
+    expect(fs.readdirSync(project).sort()).toEqual(before);
+    expect(fs.existsSync(path.join(project, 'node_modules', '.cache'))).toBe(
+      false,
+    );
+    expect(fs.readdirSync(path.join(userCacheDir(), 'discover'))).toHaveLength(
+      1,
+    );
+  });
+});

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

@@ -47,7 +47,7 @@ export const doc = {
     {label: 'One section', cli: 'astryx docs theme quick-start'},
     {label: 'The CLI docs tree', cli: 'astryx docs cli'},
     {label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
-    {label: 'A whole guide', cli: 'astryx docs cli/integrations --full'},
+    {label: 'A whole guide', cli: 'astryx docs cli/integrations/quick-start --full'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},

package/clients/cli/commands/docs.mjs

@@ -7,7 +7,8 @@
  * open one section by its key, and `--full` prints the whole topic. `--json`
  * keeps the docs() contract: a topic returns its whole doc, and `--index` its
  * sections.
- * Supports --detail (full|compact|brief) and --lang (en|zh|dense).
+ * Supports --detail (full|compact|brief) and --lang (en|zh|dense). A code
+ * block's label prints above its fence, and table cells escape their pipes.
  *
  * Usage:
  *   astryx docs                          List available topics
@@ -42,21 +43,35 @@ import {doc as docsFn} from '../../../api/docs/docs.doc.mjs';
 
 // ─── Formatting ──────────────────────────────────────────────────────────────
 
+/**
+ * A table cell with its pipes escaped. Columns are separated by ` | `, and a
+ * union type such as `'light' | 'dark'` is spelled with the same character,
+ * so an unescaped cell reads as extra columns. `astryx component` escapes its
+ * prop tables the same way.
+ * @param {string | undefined} cell
+ * @returns {string}
+ */
+function tableCell(cell) {
+  return (cell || '').replaceAll('|', '\\|');
+}
+
 /**
  * @param {string[]} headers
  * @param {string[][]} rows
  * @returns {string}
  */
 function formatTable(headers, rows) {
-  const widths = headers.map((h, i) =>
-    Math.max(h.length, ...rows.map(r => (r[i] || '').length)),
+  const head = headers.map(tableCell);
+  const cells = rows.map(r => r.map(tableCell));
+  const widths = head.map((h, i) =>
+    Math.max(h.length, ...cells.map(r => (r[i] || '').length)),
   );
   const sep = widths.map(w => '-'.repeat(w)).join(' | ');
-  const head = headers.map((h, i) => h.padEnd(widths[i])).join(' | ');
-  const body = rows
-    .map(r => r.map((c, i) => (c || '').padEnd(widths[i])).join(' | '))
+  const top = head.map((h, i) => h.padEnd(widths[i])).join(' | ');
+  const body = cells
+    .map(r => r.map((c, i) => c.padEnd(widths[i])).join(' | '))
     .join('\n');
-  return `${head}\n${sep}\n${body}`;
+  return `${top}\n${sep}\n${body}`;
 }
 
 /**
@@ -65,15 +80,19 @@ function formatTable(headers, rows) {
  * @returns {string}
  */
 function formatTableCompact(headers, rows) {
-  return rows.map(r => r.join(' = ')).join('\n');
+  // An empty cell, such as a Default with none, adds nothing to the line.
+  return rows
+    .map(r => r.filter(cell => String(cell ?? '').trim() !== '').join(' = '))
+    .join('\n');
 }
 
 /**
+ * One content block as text. Exported for its tests.
  * @param {import('@astryxdesign/cli/authoring').ReferenceContentBlock} block
  * @param {'full' | 'compact' | 'brief'} detail
  * @returns {string | null}
  */
-function formatBlock(block, detail) {
+export function formatBlock(block, detail) {
   switch (block.type) {
     case 'prose':
       return block.text;
@@ -84,13 +103,20 @@ function formatBlock(block, detail) {
     case 'code':
       if (detail === 'compact' || detail === 'brief') return null;
       {
-        const label = block.label ? `// ${block.label}\n` : '';
-        return `\`\`\`${block.lang}\n${label}${block.code}\n\`\`\``;
+        // The label names the block, so it prints above the fence, not
+        // inside it: `// label` is not a comment in bash, CSS, JSON, or
+        // HTML, and a reader who copies the block would copy it too.
+        const label = block.label
+          ? `${block.label.replace(/:\s*$/, '')}:\n`
+          : '';
+        return `${label}\`\`\`${block.lang}\n${block.code}\n\`\`\``;
       }
 
     case 'table':
       if (detail === 'brief') {
-        return block.rows.map(r => r.slice(0, 2).join('=')).join(' | ');
+        return block.rows
+          .map(r => r.slice(0, 2).map(tableCell).join('='))
+          .join(' | ');
       }
       if (detail === 'compact') {
         return formatTableCompact(block.headers, block.rows);
@@ -202,16 +228,23 @@ function emitIndex(index, run) {
 }
 
 /**
- * One child row of a namespace: its route name, then the doc's own title when
- * it is not the route name (`assertResponse()`, `search()`), then its summary.
+ * One child row of a namespace. Namespace and guide route names are already
+ * readable, so repeating their titles adds noise (`start-a-template  Start a
+ * template`). Typed docs keep a distinct title when it carries the real symbol
+ * name (`assert-response  assertResponse()`).
  * @param {import('../../../api/docs/docs.type.mjs').DocsNodeChild} child
  * @returns {{name: string, summary: string}}
  */
 function childRow(child) {
+  const titleAddsIdentity =
+    child.kind !== 'namespace' &&
+    child.kind !== 'generic' &&
+    child.title !== child.name;
   return {
     name: child.name,
-    summary:
-      child.title === child.name ? child.summary : `${child.title}: ${child.summary}`,
+    summary: titleAddsIdentity
+      ? `${child.title}: ${child.summary}`
+      : child.summary,
   };
 }
 
@@ -227,6 +260,17 @@ function emitNode(node, detail, run) {
   if (node.kind === 'namespace') {
     emit(
       section(node.title, wrapText(node.summary)),
+      // A namespace may author intro `blocks`; they render above its children.
+      ...(node.content?.length
+        ? [
+            text(
+              node.content
+                .map(b => formatBlock(b, detail))
+                .filter(Boolean)
+                .join('\n\n'),
+            ),
+          ]
+        : []),
       ...node.slots.flatMap(slot => [
         // A namespace with one slot titled like itself needs no second heading.
         ...(node.slots.length === 1 && slot.title === node.title
@@ -235,7 +279,6 @@ function emitNode(node, detail, run) {
         records(slot.children.map(childRow), {
           fields: ['name', 'summary'],
           layout: 'inline',
-          overflow: 'truncate',
         }),
       ]),
       text(

package/clients/cli/commands/doctor-integration-docs.doc.mjs

@@ -10,9 +10,10 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Check an integration\'s docs: the docs tree they add, every link, and overlaps with Core topics',
   description:
-    'Reports intentional Core topic replacements and extensions as information. ' +
+    'Checks the docs tree the package adds, every link in its docs, and overlaps with Core topics. ' +
+    'Intentional replacements and extensions are information. ' +
     'A same-name topic without `replaces` or `extends` is an accidental conflict ' +
-    'and fails until the author declares the relationship or renames it.',
+    'and fails until the author declares the relationship or renames it. See {@link generic:check-your-docs}.',
   fn: 'integrationDocConflicts',
   args: [
     {

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

@@ -13,6 +13,7 @@ vi.mock('../../../foundation/discovery/template-conflict-release.mjs', () => ({
   expandedTemplateConflictSchemaActive: () => true,
 }));
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import {Command} from 'commander';
 import {discoverCoreTemplates} from '../../../foundation/discovery/template-adapter.mjs';
@@ -344,6 +345,35 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBe(1);
   });
 
+  it('components exits 1 when Core is missing, with no [ok] after the failure', async () => {
+    // Outside the repo, so nothing above the package resolves Core.
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-no-core-'));
+    const previousTmp = tmpDir;
+    tmpDir = outside;
+    try {
+      writeComponentIntegration('AcmeCarousel');
+      expect(findCoreDir(outside)).toBeNull();
+      process.chdir(outside);
+
+      await createProgram().parseAsync([
+        'node',
+        'astryx',
+        'doctor',
+        'integration',
+        'components',
+      ]);
+
+      const printed = logCalls.join('\n');
+      expect(printed).toContain('core_not_found');
+      expect(printed).not.toContain('[ok]');
+      expect(process.exitCode).toBe(1);
+    } finally {
+      tmpDir = previousTmp;
+      process.chdir(previousCwd);
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  });
+
   it('components warns with the exact package-qualified command', async () => {
     const coreDir = findCoreDir(tmpDir);
     expect(coreDir).not.toBeNull();
@@ -433,6 +463,29 @@ describe('doctor integration — command', () => {
     expect(process.exitCode).toBeUndefined();
   });
 
+  it('docs exits 1 for a placement that hides a guide, with no [ok] after the failure', async () => {
+    writeDocIntegration({name: 'deploying'});
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'deploying.doc.mjs'),
+      "export default {type: 'generic', name: 'deploying', title: 'Deploying', description: 'Deploy.', placement: {parent: 'namespace:nope', slot: 'guides'}, sections: [{title: 'Deploy', content: [{type: 'prose', text: 'Deploy.'}]}]};\n",
+    );
+    process.chdir(tmpDir);
+
+    await createProgram().parseAsync([
+      'node',
+      'astryx',
+      'doctor',
+      'integration',
+      'docs',
+    ]);
+
+    const printed = logCalls.join('\n');
+    expect(printed).toContain('[fail]');
+    expect(printed).toContain('invalid_doc_graph');
+    expect(printed).not.toContain('[ok]');
+    expect(process.exitCode).toBe(1);
+  });
+
   it('docs exits 1 for an accidental same-name Core topic', async () => {
     const [coreTopic] = Object.keys(discoverBuiltinTopics());
     writeDocIntegration({name: coreTopic});

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

@@ -16,7 +16,9 @@ export const doc = {
   summary: 'Diagnose Astryx projects and integration packages',
   description:
     'Runs read-only project health diagnostics by default: Node version, @astryxdesign/core ' +
-    'install and version alignment, themes, config, agent docs, and package manager. ' +
+    'install and version alignment, themes, config, integrations (linked without a config entry, ' +
+    'provider identity, contribution issues), agent docs, core peer dependencies, package manager, ' +
+    "and the docs the CLI reads. It writes nothing, but loading astryx.config runs that file's code. " +
     'The `integration` subcommands provide authoring checks for one integration package.',
   fn: 'doctor',
   subcommands: ['integration'],

package/clients/cli/commands/doctor.mjs

@@ -36,6 +36,8 @@ import {doc as integrationTemplateConflictsFn} from '../../../api/integration/in
 import {doc as integrationComponentConflictsFn} from '../../../api/integration/integrationComponentConflicts.doc.mjs';
 import {doc as integrationDocConflictsFn} from '../../../api/integration/integrationDocConflicts.doc.mjs';
 import {NO_RESULT_SET} from '../../../foundation/debug/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 
 const STATUS = {
   pass: '[ok]',
@@ -181,8 +183,10 @@ function printComponentConflicts(data) {
     ),
     ...issueBlocks(data.issues),
   ];
+  // An [ok] after a failed check reads as a pass: say nothing it could not check.
+  const failed = data.issues.some(issue => issue.severity === 'error');
   if (data.conflicts.length === 0) {
-    output.push(text('[ok] No component names conflict with Core.'));
+    if (!failed) output.push(text('[ok] No component names conflict with Core.'));
   } else {
     output.push(
       records(data.conflicts, {
@@ -224,7 +228,9 @@ function printDocConflicts(data) {
     );
   }
   if (data.findings.length === 0) {
-    output.push(text('[ok] No doc topics overlap with Core.'));
+    if (!data.issues.some(issue => issue.severity === 'error')) {
+      output.push(text('[ok] No doc topics overlap with Core.'));
+    }
   } else {
     output.push(
       records(data.findings, {
@@ -315,19 +321,57 @@ async function runAuthoringCheck(program, pkg, kind) {
   return NO_RESULT_SET;
 }
 
+/**
+ * The first word after a command group, which names a subcommand it does not
+ * have, or null.
+ * @param {import('commander').Command | undefined} invoked
+ * @returns {string | null}
+ */
+function unknownWord(invoked) {
+  const word = (invoked?.args ?? []).find(arg => !String(arg).startsWith('-'));
+  return word == null ? null : String(word);
+}
+
+/**
+ * Report an unknown subcommand, in text as in JSON, with the ones the group has.
+ * @param {import('commander').Command} group
+ * @param {string} label the group's full name
+ * @param {string} word
+ */
+function unknownSubcommand(group, label, word) {
+  return cliError(`unknown subcommand '${label} ${word}'`, {
+    suggestions: group.commands.map(child => ({
+      name: child.name(),
+      reason: 'available subcommand',
+    })),
+    code: ERROR_CODES.ERR_UNKNOWN_SUBCOMMAND,
+  });
+}
+
 /**
  * Register `astryx doctor` and its integration-authoring leaves.
  * @param {import('commander').Command} program
  */
 export function registerDoctor(program) {
-  const doctorCmd = defineCommand(program, doctorCommand, {
+  /** @type {import('commander').Command} */
+  let doctorCmd;
+  doctorCmd = defineCommand(program, doctorCommand, {
     fn: doctorFn,
-    action: async () => runProjectDoctor(program),
+    // `doctor integrations` is a mistyped subcommand, not a project check.
+    action: async (options, invoked) => {
+      const word = unknownWord(invoked);
+      if (word != null) return unknownSubcommand(doctorCmd, 'doctor', word);
+      return runProjectDoctor(program);
+    },
   });
   /** @type {import('commander').Command} */
   let integrationCmd;
   integrationCmd = defineCommand(doctorCmd, doctorIntegrationGroup, {
-    action: () => {
+    action: (options, invoked) => {
+      const word = unknownWord(invoked);
+      if (word != null) {
+        return unknownSubcommand(integrationCmd, 'doctor integration', word);
+      }
       integrationCmd.outputHelp();
       return NO_RESULT_SET;
     },

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

@@ -11,9 +11,12 @@ export const doc = {
   name: 'gap-report',
   displayName: 'astryx gap-report',
   namespace: 'cli/commands',
-  summary: 'Route a design-system gap to its owning package',
+  summary: 'Report a missing component or feature to the package that owns it',
   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.',
+    'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability to the package that owns it: the --package you name, else the one package that provides the component, else Core. ' +
+    'Every configured handler receives the report: the project config handler first, then each integration handler in config order. Public handlers run only with --confirm-public; internal handlers always run. A failing handler does not stop the others. ' +
+    "With no handler it files a GitHub issue for the owning package, only with --confirm-public (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " +
+    'The report records whether an agent or a person ran it.',
   fn: 'gapReport',
   args: [
     {
@@ -45,12 +48,14 @@ export const doc = {
     {
       flag: '--package <pkg>',
       param: 'options.package',
-      description: 'Route to a specific loaded package',
+      description:
+        'Package that owns the gap: @astryxdesign/core or a loaded integration. Overrides automatic routing; needed when more than one package provides the component',
     },
     {
       flag: '--confirm-public',
       param: 'options.confirmPublic',
-      description: 'Consent to public handlers or GitHub issue creation',
+      description:
+        'Allow public delivery: public handlers run, and with no handler it files a GitHub issue with your gh login',
     },
     {
       flag: '--list-categories',
@@ -62,13 +67,9 @@ export const doc = {
   examples: [
     {label: 'List categories', cli: 'astryx gap-report --list-categories'},
     {
-      label: 'Route an agent report',
+      label: 'Prepare a report (nothing public happens without --confirm-public)',
       cli: "astryx gap-report Button --category missing_variant --reason 'Need a compact size'",
     },
-    {
-      label: 'Confirm public filing',
-      cli: "astryx gap-report Button --category docs_gap --reason 'Missing keyboard example' --confirm-public",
-    },
   ],
   exitCodes: [
     {