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

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'],
+};

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

@@ -8,16 +8,16 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Author and verify an Astryx integration package',
   description:
-    'Add contributions that are valid on arrival, then prove the packed package exposes the same contributions a consumer will receive.',
-  subcommands: ['add', 'pack'],
+    'Add contributions to your package, then check the packed package the way an app receives it. The guides start at {@link namespace:integrations}.',
+  subcommands: ['add', 'verify', 'pack'],
   examples: [
     {
       label: 'Add a component',
       cli: 'astryx integration add component AcmeWidget',
     },
     {
-      label: 'Check the package tarball',
-      cli: 'astryx integration pack --check',
+      label: 'Check the package before publishing',
+      cli: 'astryx integration verify',
     },
   ],
   exitCodes: [

package/clients/cli/commands/integration.mjs

@@ -12,6 +12,7 @@ import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {doc as integrationGroup} from './integration.doc.mjs';
 import {doc as integrationAddCommand} from './integration-add.doc.mjs';
+import {doc as integrationVerifyCommand} from './integration-verify.doc.mjs';
 import {doc as integrationPackCommand} from './integration-pack.doc.mjs';
 import {doc as integrationAddFn} from '../../../api/integration/integrationAdd.doc.mjs';
 import {doc as integrationPackCheckFn} from '../../../api/integration/integrationPackCheck.doc.mjs';
@@ -24,8 +25,16 @@ import {doc as integrationPackCheckFn} from '../../../api/integration/integratio
  */
 function showGroupOrUnknown(command, label, options, invoked) {
   const extras = invoked?.args ?? [];
-  if (extras.length > 0) {
-    return cliError(`unknown subcommand '${label} ${String(extras[0])}'`, {
+  // allowUnknownOption keeps an unknown flag among the args: a word there is
+  // an unknown subcommand, and a flag alone is an unknown option.
+  const word = extras.find(arg => !String(arg).startsWith('-'));
+  if (word == null && extras.length > 0) {
+    return cliError(`unknown option '${String(extras[0])}'`, {
+      code: ERROR_CODES.ERR_INVALID_OPTION,
+    });
+  }
+  if (word != null) {
+    return cliError(`unknown subcommand '${label} ${String(word)}'`, {
       suggestions: (command.commands ?? []).map(child => ({
         name: child.name(),
         reason: 'available subcommand',
@@ -37,6 +46,48 @@ function showGroupOrUnknown(command, label, options, invoked) {
   return NO_RESULT_SET;
 }
 
+/**
+ * Run `integration verify` and print its result, as text or JSON.
+ * @param {import('commander').Command} program
+ */
+async function verifyPackage(program) {
+  const result = await integrationPackCheck({cwd: process.cwd()});
+  if (program.opts().json) {
+    jsonOut(result);
+  } else {
+    const {name, version, packable, tarball, inventory, issues} = result.data;
+    const identity = [name, version].filter(Boolean).join('@');
+    const blocks = [
+      section(
+        packable
+          ? 'Integration package ready'
+          : 'Integration package check failed',
+      ),
+      text(`${packable ? '[ok]' : '[fail]'} ${identity || 'local package'}`),
+    ];
+    if (tarball != null) {
+      blocks.push(
+        text(
+          `${tarball.fileCount} packed files; ${inventory.packedFiles}/${inventory.expectedFiles} required files present.`,
+        ),
+      );
+    }
+    if (issues.length > 0) {
+      blocks.push(
+        list(
+          issues.map(
+            issue =>
+              `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
+          ),
+        ),
+      );
+    }
+    emit(...blocks);
+  }
+  if (!result.data.packable) process.exitCode = 1;
+  return NO_RESULT_SET;
+}
+
 /** @param {import('commander').Command} program */
 export function registerIntegration(program) {
   /** @type {import('commander').Command} */
@@ -45,6 +96,10 @@ export function registerIntegration(program) {
     action: (options, command) =>
       showGroupOrUnknown(integration, 'integration', options, command),
   });
+  // An unknown subcommand given with a flag reports the unknown subcommand
+  // and lists the ones the group has, not the unknown option. Each subcommand
+  // still parses its own options.
+  integration.allowUnknownOption(true);
 
   defineCommand(integration, integrationAddCommand, {
     fn: integrationAddFn,
@@ -102,53 +157,29 @@ export function registerIntegration(program) {
     },
   });
 
+  defineCommand(integration, integrationVerifyCommand, {
+    fn: integrationPackCheckFn,
+    action: async () => verifyPackage(program),
+  });
+  // The name this check had before `integration verify`. It stays as a
+  // deprecated alias, listed as one in help, so scripts that call it keep
+  // working; it runs the same check with the same output and exit codes.
   defineCommand(integration, integrationPackCommand, {
     fn: integrationPackCheckFn,
     action: async options => {
       if (!options.check) {
-        return cliError('Pass --check to verify the integration tarball.', {
-          code: ERROR_CODES.ERR_INVALID_ARGUMENT,
-        });
+        return cliError(
+          'Pass --check to verify the integration tarball, or run `astryx integration verify`.',
+          {code: ERROR_CODES.ERR_INVALID_ARGUMENT},
+        );
       }
-
-      const result = await integrationPackCheck({cwd: process.cwd()});
-      if (program.opts().json) {
-        jsonOut(result);
-      } else {
-        const {name, version, packable, tarball, inventory, issues} =
-          result.data;
-        const identity = [name, version].filter(Boolean).join('@');
-        const blocks = [
-          section(
-            packable
-              ? 'Integration package ready'
-              : 'Integration package check failed',
-          ),
-          text(
-            `${packable ? '[ok]' : '[fail]'} ${identity || 'local package'}`,
-          ),
-        ];
-        if (tarball != null) {
-          blocks.push(
-            text(
-              `${tarball.fileCount} packed files; ${inventory.packedFiles}/${inventory.expectedFiles} required files present.`,
-            ),
-          );
-        }
-        if (issues.length > 0) {
-          blocks.push(
-            list(
-              issues.map(
-                issue =>
-                  `[${issue.severity === 'error' ? 'fail' : 'warn'}] ${issue.message}`,
-              ),
-            ),
-          );
-        }
-        emit(...blocks);
+      // stderr, and only in text: JSON callers get the same envelope as verify.
+      if (!program.opts().json) {
+        console.error(
+          'Note: `integration pack --check` is deprecated. Run `astryx integration verify`: it runs the same check.',
+        );
       }
-      if (!result.data.packable) process.exitCode = 1;
-      return NO_RESULT_SET;
+      return verifyPackage(program);
     },
   });
 }

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

@@ -20,7 +20,7 @@ export const doc = {
     'tooling to introspect. Intended to be run with --json.',
   examples: [
     {label: 'Full manifest', cli: 'astryx manifest --json'},
-    {label: 'Shorthand', cli: 'astryx --json'},
+    {label: 'The same manifest, under data.manifest (type "help")', cli: 'astryx --json'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},

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

@@ -16,9 +16,12 @@ export const doc = {
   summary: 'Search components, hooks, docs, and templates in one ranked list',
   description:
     'Terminal front-end to search(): prints one ranked, greppable list across ' +
-    'every content domain, each row carrying a follow-up command to act on it.',
+    'every content domain, each row carrying a follow-up command to act on it. ' +
+    'Outside an app, where @astryxdesign/core is not installed, it searches the docs.',
   fn: 'search',
-  args: [{name: 'query', param: 'query', required: true}],
+  // Every word after `search` is the query: `astryx search dark mode` searches
+  // for "dark mode", with no quotes needed.
+  args: [{name: 'query', param: 'query', required: true, variadic: true}],
   options: [
     {
       flag: '--type <domain>',
@@ -38,6 +41,10 @@ export const doc = {
   ],
   examples: [
     {label: 'Ranked results', cli: 'astryx search button'},
+    {
+      label: 'Several words, no quotes',
+      cli: 'astryx search dark mode --type doc',
+    },
     {
       label: 'Filter + JSON',
       cli: 'astryx search "data table" --type template --json',
@@ -47,7 +54,7 @@ export const doc = {
     {code: 0, when: 'success (including zero matches)'},
     {
       code: 1,
-      when: 'invalid --type, a --limit that is not a positive integer, or @astryxdesign/core cannot be found',
+      when: 'invalid --type, a --limit that is not a positive integer, or --type component, hook, or template where @astryxdesign/core cannot be found',
     },
   ],
   related: ['component', 'hook', 'docs', 'template', 'build'],

package/clients/cli/commands/search.mjs

@@ -14,6 +14,7 @@
  *
  * Usage:
  *   astryx search button                 Ranked results across all domains
+ *   astryx search dark mode              Every word is part of the query
  *   astryx search modal --type component Filter to a single domain
  *   astryx search forms --limit 5        Cap the result count
  *   astryx search button --verbose       Also print score / reason
@@ -31,6 +32,7 @@ import {cliError} from '../lib/cli-error.mjs';
 import {defineCommand} from '../lib/define-command.mjs';
 import {search as searchApi} from '../../../api/search/search.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {warnOnIntegrationIssues} from '../../../foundation/integrations/integration-warnings.mjs';
 import {doc as searchCommand} from './search.doc.mjs';
 import {doc as searchFn} from '../../../api/search/search.doc.mjs';
@@ -42,10 +44,13 @@ export function registerSearch(program) {
   defineCommand(program, searchCommand, {
     fn: searchFn,
     action: async (
-      /** @type {string} */ query,
+      /** @type {string[] | string} */ words,
       /** @type {{type?: import('../../../api/search/search.type.mjs').SearchDomain, limit?: string, verbose?: boolean}} */ options,
     ) => {
       const json = program.opts().json || false;
+      // The query is variadic: `astryx search dark mode` is one query, "dark
+      // mode". Taking only the first word dropped the rest without a word.
+      const query = Array.isArray(words) ? words.join(' ') : words;
 
       try {
         const project = await Project.load(process.cwd());
@@ -99,12 +104,25 @@ export function registerSearch(program) {
       // ── Text output ──────────────────────────────────────────────
       const run = getCliInvocation();
       const {query: q, matchCount, results} = result.data;
+      // Outside an app an open search covers the docs alone. Say so, so a
+      // docs-only list does not read as "Astryx has no such component".
+      const note =
+        !options.type && !findCoreDir(process.cwd())
+          ? [
+              text(
+                '@astryxdesign/core is not installed here, so only the docs were searched.',
+              ),
+            ]
+          : [];
 
       // No matches is a valid, successful outcome — clean message, exit 0.
       if (results.length === 0) {
         emit(
           text(`No results for "${q}".`),
-          text(`Try a broader term, or browse: ${run} component --list`),
+          ...note,
+          text(
+            `Try a broader term, or browse: ${run} ${note.length > 0 ? 'docs' : 'component --list'}`,
+          ),
         );
         return answered;
       }
@@ -155,6 +173,7 @@ export function registerSearch(program) {
           fields,
           format: {command: formatCliCommand, parent: formatCliCommand},
         }),
+        ...note,
       );
       return answered;
     },

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

@@ -191,6 +191,18 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('No results');
   });
 
+  it('takes every word after `search` as one query', async () => {
+    // Commander took only the first word, so `search dark mode` searched for
+    // "dark" and dropped "mode" without a word.
+    const json = await runCli(['--json', 'search', 'dark', 'mode', '--type', 'doc'], REPO_ROOT);
+    expect(json.status).toBe(0);
+    const env = JSON.parse(json.stdout);
+    expect(env.data.query).toBe('dark mode');
+    expect(env.data.results[0]).toMatchObject({name: 'theme', section: 'light-dark-mode'});
+    const text = await runCli(['search', 'dark', 'mode', '--type', 'doc'], REPO_ROOT);
+    expect(text.stdout).toContain('Results for "dark mode"');
+  }, SCAN_TIMEOUT);
+
   it('exits 1 for an invalid --type', async () => {
     const r = await runCli(['search', 'x', '--type', 'bogus'], REPO_ROOT);
     expect(r.status).toBe(1);
@@ -299,14 +311,19 @@ describe('search CLI — exit codes + JSON contract', () => {
     expect(r.stdout).toContain('reason:');
   });
 
-  it('exits 1 with ERR_CORE_NOT_FOUND when no @astryxdesign/core is reachable', async () => {
+  it('searches the docs when no @astryxdesign/core is reachable, and exits 1 for --type component', async () => {
     const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-search-cli-no-core-'));
     try {
-      const json = await runCli(['--json', 'search', 'button'], empty);
+      const open = await runCli(['--json', 'search', 'make', 'an', 'integration'], empty);
+      expect(open.status).toBe(0);
+      expect(JSON.parse(open.stdout).data.results[0]).toMatchObject({domain: 'doc'});
+      // The text says the search covered the docs alone.
+      const text = await runCli(['search', 'button'], empty);
+      expect(text.status).toBe(0);
+      expect(text.stdout).toContain('only the docs were searched');
+      const json = await runCli(['--json', 'search', 'button', '--type', 'component'], empty);
       expect(json.status).toBe(1);
       expect(JSON.parse(json.stdout)).toMatchObject({code: 'ERR_CORE_NOT_FOUND'});
-      const text = await runCli(['search', 'button'], empty);
-      expect(text.status).toBe(1);
     } finally {
       fs.rmSync(empty, {recursive: true, force: true});
     }

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

@@ -46,7 +46,7 @@ export const doc = {
   ],
   examples: [
     {label: 'List swizzlable components', cli: 'astryx swizzle --list'},
-    {label: 'Eject a component', cli: 'astryx swizzle XDSButton'},
+    {label: 'Eject a component', cli: 'astryx swizzle Button'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},

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

@@ -14,7 +14,7 @@ export const doc = {
   name: 'template',
   displayName: 'astryx template',
   namespace: 'cli/commands',
-  summary: 'Inject a page or block template',
+  summary: 'List, show, or scaffold page and block templates',
   description:
     'One entry point for the template family: with no name it lists the discovered ' +
     'templates; with a name it shows the source or a layout skeleton, or scaffolds it ' +

package/clients/cli/commands/text-json-parity.test.mjs

@@ -372,9 +372,15 @@ const CASES = [
     skipFieldChecks: true,
   },
   {
+    name: 'integration verify',
+    args: ['integration', 'verify'],
+    // Needs a packable project; pack itself may exit differently.
+    skipFieldChecks: true,
+  },
+  {
+    // The deprecated alias of `integration verify`.
     name: 'integration pack',
     args: ['integration', 'pack', '--check'],
-    // Needs a packable project; pack itself may exit differently.
     skipFieldChecks: true,
   },
   // ── Layout command: remove these cases when the layout command is deleted ──

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

@@ -41,7 +41,7 @@ export const doc = {
   examples: [
     {label: 'Scaffold a theme', cli: 'astryx theme add matcha'},
     {
-      label: 'Select an integration theme',
+      label: 'Pick the owner when two packages ship the same slug',
       cli: 'astryx theme add ocean --package @acme/themes',
     },
   ],