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

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: [
     {

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

@@ -18,21 +18,22 @@ export const doc = {
     '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 write an annotated theme template.',
+    "steps. --features and --all print only the chosen features' guidance (no " +
+    'getting-started steps); the theme feature also writes an annotated theme template.',
   fn: 'init',
   options: [
     {
       flag: '--features <list>',
       param: 'options.features',
       description:
-        'Comma-separated features to install (agents, theme, template). An unknown feature exits 1 with ERR_UNKNOWN_FEATURE. ' +
-        'Ignored with --all or --remove-agents',
+        'Comma-separated features: agents (agent docs), theme (writes theme.template.ts), template (prints the page-building commands; writes no file). ' +
+        'An unknown feature exits 1 with ERR_UNKNOWN_FEATURE. Ignored with --all or --remove-agents',
     },
     {
       flag: '--all',
       param: 'options.all',
-      description: 'Install all features (agents, theme, template); overrides --features',
+      description:
+        'Install all features (agents, theme, template); overrides --features. Prints their guidance instead of the getting-started steps',
     },
     {
       flag: '--remove-agents',
@@ -47,7 +48,9 @@ export const doc = {
       param: 'options.agent',
       choices: ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'],
       description:
-        'Target AI tool for agent docs: claude, cursor, codex, hermes, muse, all. An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
+        'Target AI tool for agent docs: claude (CLAUDE.md or .claude/CLAUDE.md, else creates .claude/CLAUDE.md), cursor (.cursorrules if present, else AGENTS.md), ' +
+        'codex and muse (AGENTS.md), hermes (.hermes.md or HERMES.md if present, else AGENTS.md), all (every existing agent doc, else AGENTS.md and .claude/CLAUDE.md). ' +
+        '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',
     },
     {

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

@@ -8,7 +8,7 @@ export const doc = {
   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.',
+    'Writes the files one contribution needs, creates the integration manifest on first use, and declares a root only after a contribution the CLI can read exists behind it. A component or template import also needs an `exports` entry: add writes one only when package.json already has an `exports` map, so start a new package with `"exports": {}`. See {@link generic:quick-start}.',
   fn: 'integrationAdd',
   args: [
     {
@@ -60,10 +60,14 @@ export const doc = {
       flag: '--to <version>',
       param: 'options.to',
       description:
-        'Exact semver the codemod migrates to (e.g. 1.2.0); required for codemod and only valid there',
+        'Exact semver of the @astryxdesign/core version whose upgrade runs the codemod (e.g. 0.7.0); required for codemod and only valid there',
     },
   ],
   examples: [
+    {
+      label: 'Preview',
+      cli: 'astryx integration add component AcmeWidget --dry-run --json',
+    },
     {
       label: 'Add a component',
       cli: 'astryx integration add component AcmeWidget',
@@ -71,7 +75,7 @@ export const doc = {
     {label: 'Add a doc topic', cli: 'astryx integration add doc deploying'},
     {
       label: 'Add a page template',
-      cli: 'astryx integration add template dashboard',
+      cli: 'astryx integration add template acme-dashboard',
     },
     {
       label: 'Add a block template',
@@ -87,7 +91,7 @@ export const doc = {
     },
     {
       label: 'Add a guide to the package\'s own docs section',
-      cli: 'astryx integration add doc deploying --parent acme',
+      cli: 'astryx integration add doc releasing --parent acme',
     },
     {
       label: 'Add a codemod',
@@ -98,10 +102,6 @@ export const doc = {
       cli: "astryx integration add agent-doc 'Run acme verify before finishing.'",
     },
     {label: 'Add a source theme', cli: 'astryx integration add theme ocean'},
-    {
-      label: 'Preview',
-      cli: 'astryx integration add component AcmeWidget --dry-run --json',
-    },
   ],
   exitCodes: [
     {code: 0, when: 'the contribution is written or the dry run succeeds'},
@@ -110,5 +110,5 @@ export const doc = {
       when: 'the kind, name, options, package, or target files are invalid or conflict',
     },
   ],
-  related: ['integration pack', 'doctor integration validate', 'theme add'],
+  related: ['integration verify', 'doctor integration validate', 'theme add'],
 };

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

@@ -127,10 +127,7 @@ describe('integration authoring CLI', () => {
     );
     expect(added.status).toBe(0);
 
-    const checked = await runCli(
-      ['integration', 'pack', '--check', '--json'],
-      tmpDir,
-    );
+    const checked = await runCli(['integration', 'verify', '--json'], tmpDir);
     // Without an exports map, the extensionless import cannot resolve —
     // pack-check must fail, not false-green.
     expect(checked.status).not.toBe(0);
@@ -150,13 +147,67 @@ describe('integration authoring CLI', () => {
     );
   });
 
-  it('requires the explicit --check gate on pack', async () => {
-    const result = await runCli(['integration', 'pack', '--json'], tmpDir);
-    expect(result.status).not.toBe(0);
-    expect(parseEnvelope(result.stdout)).toMatchObject({
-      code: 'ERR_INVALID_ARGUMENT',
-      error: 'Pass --check to verify the integration tarball.',
+  it('keeps `integration pack --check` as a deprecated alias of `integration verify`', async () => {
+    // The old spelling runs the same check: the same JSON, the same exit code.
+    const verify = await runCli(['integration', 'verify', '--json'], tmpDir);
+    const old = await runCli(
+      ['integration', 'pack', '--check', '--json'],
+      tmpDir,
+    );
+    expect(old.status).toBe(verify.status);
+    const verifyEnvelope = parseEnvelope(verify.stdout);
+    const oldEnvelope = parseEnvelope(old.stdout);
+    expect(oldEnvelope.type).toBe('integration.pack-check');
+    expect(oldEnvelope.type).toBe(verifyEnvelope.type);
+    expect(oldEnvelope.data.packable).toBe(verifyEnvelope.data.packable);
+    expect(oldEnvelope.data.issues).toEqual(verifyEnvelope.data.issues);
+    // The global flag may come first, as agents usually write it.
+    const lead = await runCli(
+      ['--json', 'integration', 'pack', '--check'],
+      tmpDir,
+    );
+    expect(parseEnvelope(lead.stdout).type).toBe('integration.pack-check');
+    // In text, it says to use the new name, on stderr, so stdout is the same.
+    const text = await runCli(['integration', 'pack', '--check'], tmpDir);
+    const verifyText = await runCli(['integration', 'verify'], tmpDir);
+    expect(text.status).toBe(verifyText.status);
+    expect(text.stdout).toBe(verifyText.stdout);
+    expect(text.stderr).toContain('`integration pack --check` is deprecated');
+    expect(text.stderr).toContain('astryx integration verify');
+    // Without --check it fails, as it did, and names both spellings.
+    const bare = await runCli(['integration', 'pack'], tmpDir);
+    expect(bare.status).not.toBe(0);
+    expect(bare.stderr).toContain('--check');
+    expect(bare.stderr).toContain('astryx integration verify');
+    // Help lists it, marked deprecated: nothing is hidden.
+    const help = await runCli(['integration', '--help'], tmpDir);
+    expect(help.stdout).toMatch(
+      /pack .*Deprecated: the old name of `integration verify`/,
+    );
+    // `verify` itself takes no --check.
+    const flag = await runCli(['integration', 'verify', '--check'], tmpDir);
+    expect(flag.status).not.toBe(0);
+    expect(flag.stderr).toContain("unknown option '--check'");
+    // An unknown subcommand with a flag names the subcommand, in text and JSON.
+    const unknown = await runCli(['integration', 'bogus', '--check'], tmpDir);
+    expect(unknown.status).not.toBe(0);
+    expect(unknown.stderr).toContain("unknown subcommand 'integration bogus'");
+    expect(unknown.stderr).toMatch(/verify\s+\(available subcommand\)/);
+    const unknownJson = await runCli(
+      ['integration', 'bogus', '--check', '--json'],
+      tmpDir,
+    );
+    expect(parseEnvelope(unknownJson.stdout)).toMatchObject({
+      code: 'ERR_UNKNOWN_SUBCOMMAND',
+      error: "unknown subcommand 'integration bogus'",
+      suggestions: expect.arrayContaining([
+        expect.objectContaining({name: 'verify'}),
+      ]),
     });
+    // A flag alone is an unknown option, not an unknown subcommand.
+    const flagOnly = await runCli(['integration', '--bogus'], tmpDir);
+    expect(flagOnly.status).not.toBe(0);
+    expect(flagOnly.stderr).toContain("unknown option '--bogus'");
   });
 
   it('refuses kind-specific options on another kind', async () => {

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

@@ -6,22 +6,18 @@ export const doc = {
   name: 'integration pack',
   displayName: 'astryx integration pack',
   namespace: 'cli/commands',
-  summary: 'Prove the packed integration is what consumers receive',
+  summary: 'Deprecated: the old name of `integration verify`',
   description:
-    'Runs the package lifecycle, packs with npm, checks every required contribution file against the real tarball, extracts it into a scratch consumer, and compares the local and packed contribution inventories through one shared contract.',
+    '`astryx integration pack --check` is the name this check had before {@link command:integration verify}. It still runs the same check, with the same output, JSON, and exit codes, and prints a note that names `integration verify`. It will be removed in a later release.',
   fn: 'integrationPackCheck',
   options: [
     {
       flag: '--check',
-      description: 'Run the packed-package verification gate',
+      description: 'Run the check. Required, as before.',
     },
   ],
   examples: [
-    {label: 'Verify before publishing', cli: 'astryx integration pack --check'},
-    {
-      label: 'Machine-readable result',
-      cli: 'astryx integration pack --check --json',
-    },
+    {label: 'The old spelling', cli: 'astryx integration pack --check'},
   ],
   exitCodes: [
     {code: 0, when: 'the packed package exposes the same valid contributions'},
@@ -30,5 +26,5 @@ export const doc = {
       when: '--check is omitted or the tarball is incomplete or invalid',
     },
   ],
-  related: ['integration add', 'doctor integration validate'],
+  related: ['integration verify'],
 };

package/clients/cli/commands/integration-real-world.test.mjs

@@ -214,7 +214,7 @@ export const oceanTheme = defineTheme({
     ]);
 
     const checked = await runCli(
-      ['integration', 'pack', '--check', '--json'],
+      ['integration', 'verify', '--json'],
       providerDir,
     );
     expect(checked.status, checked.stderr).toBe(0);

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

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'integration verify',
+  displayName: 'astryx integration verify',
+  namespace: 'cli/commands',
+  summary: 'Check the package the way npm will publish it, before you publish',
+  description:
+    'Packs the package with npm, unpacks the tarball into a temporary app without installing its dependencies, and checks that the app sees the same components, templates, themes, docs, and codemods as the package, that every public import resolves, and that the package declares a CLI new enough to read it. It publishes nothing and leaves no tarball behind. It runs the package\'s own pack lifecycle scripts, as `npm pack` does.',
+  fn: 'integrationPackCheck',
+  examples: [
+    {label: 'Check before publishing', cli: 'astryx integration verify'},
+    {label: 'Machine-readable result', cli: 'astryx integration verify --json'},
+  ],
+  exitCodes: [
+    {code: 0, when: 'the packed package exposes the same valid contributions'},
+    {code: 1, when: 'the tarball is incomplete or invalid'},
+  ],
+  related: ['integration add', 'doctor integration validate'],
+};