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

package/clients/cli/commands/layout.mjs

@@ -0,0 +1,275 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layout command — thin CLI wrapper around api/layout.mjs.
+ *
+ * Subcommands:
+ *   astryx layout expand "<expr>" [path]   compressed expression → validated TSX
+ *   astryx layout check "<expr>"           validate + echo both canonical surfaces
+ *   astryx layout grammar                  agent cheatsheet (alias table is branch-generated)
+ *
+ * The expression argument may also come from --file or stdin (`-`),
+ * which is how multi-line outline (XLO) input usually arrives.
+ *
+ * The command surface (group + subcommand descriptions, args, flags) is sourced
+ * from the colocated CommandDocs via `defineCommand`; this file supplies only the
+ * actions.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {jsonOut} from '../../../foundation/response/json.mjs';
+import {emit, section, text, list, record, code, WARN} from '../formatters/index.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {layoutExpand, layoutCheck, layoutGrammar} from '../../../api/layout/layout.mjs';
+import {defineCommand} from '../lib/define-command.mjs';
+import {doc as layoutGroup} from './layout.doc.mjs';
+import {doc as layoutExpandCommand} from './layout-expand.doc.mjs';
+import {doc as layoutCheckCommand} from './layout-check.doc.mjs';
+import {doc as layoutGrammarCommand} from './layout-grammar.doc.mjs';
+import {doc as layoutExpandFn} from '../../../api/layout/layoutExpand.doc.mjs';
+import {doc as layoutCheckFn} from '../../../api/layout/layoutCheck.doc.mjs';
+import {doc as layoutGrammarFn} from '../../../api/layout/layoutGrammar.doc.mjs';
+import {NO_RESULT_SET, resultSet} from '../../../foundation/debug/index.mjs';
+
+/**
+ * The api layer's @returns for these functions widen the `type` discriminator
+ * to `string`, so annotate the command-local result with the precise response
+ * shapes from the colocated api/layout/layout.type.mjs so narrowing + jsonOut
+ * typecheck.
+ *
+ * @typedef {import('../../../api/layout/layout.type.mjs').LayoutExpandResponse} LayoutExpandResponse
+ * @typedef {import('../../../api/layout/layout.type.mjs').LayoutCheckResponse} LayoutCheckResponse
+ * @typedef {import('../../../api/layout/layout.type.mjs').LayoutGrammarResponse} LayoutGrammarResponse
+ */
+
+/**
+ * @typedef {object} LayoutExpandOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @property {string} [name]
+ * @property {boolean} [loose]
+ */
+
+/**
+ * @typedef {object} LayoutCheckOptions
+ * @property {string} [file]
+ * @property {'compact'|'outline'|'auto'} [form]
+ * @property {boolean} [loose]
+ */
+
+/** The largest layout expression read from --file or stdin. */
+const MAX_EXPRESSION_BYTES = 5 * 1024 * 1024; // 5 MB
+
+/**
+ * Resolve the expression from arg, --file, or stdin ('-').
+ * @param {string} [expr]
+ * @param {{file?: string}} [options]
+ * @returns {Promise<string>}
+ */
+async function readExpression(expr, options = {}) {
+  if (options.file) {
+    // Validate the file exists + is a regular file + is reasonably sized.
+    // We intentionally do NOT confine the read path (the user running the CLI
+    // controls --file; this is a read, not a write). The size cap prevents OOM
+    // from infinite streams like /dev/zero.
+    const filePath = path.resolve(process.cwd(), options.file);
+    const stat = fs.statSync(filePath, {throwIfNoEntry: false});
+    if (!stat || !stat.isFile()) {
+      cliError(`File not found: ${options.file}`, {
+        code: ERROR_CODES.ERR_FILE_NOT_FOUND,
+      });
+    }
+    if (stat.size > MAX_EXPRESSION_BYTES) {
+      cliError(
+        `File "${options.file}" is too large (${(stat.size / 1024 / 1024).toFixed(1)} MB, max 5 MB)`,
+        {code: ERROR_CODES.ERR_FILE_NOT_FOUND},
+      );
+    }
+    try {
+      return fs.readFileSync(filePath, 'utf-8');
+    } catch (e) {
+      const errno = /** @type {NodeJS.ErrnoException} */ (e);
+      if (errno && errno.code === 'ENOENT') {
+        // A --file pointing at a missing file is foreseeable — surface a
+        // stable code, not the raw ENOENT errno (and no stack in human mode).
+        cliError(`File not found: ${options.file}`, {
+          code: ERROR_CODES.ERR_FILE_NOT_FOUND,
+        });
+      }
+      throw e;
+    }
+  }
+  if (expr === '-') {
+    // Capped like --file: an endless stream must not be buffered whole.
+    /** @type {Buffer[]} */
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+      size += /** @type {Buffer} */ (chunk).length;
+      if (size > MAX_EXPRESSION_BYTES) {
+        cliError('The layout expression on stdin is too large (max 5 MB)', {
+          code: ERROR_CODES.ERR_INVALID_ARGUMENT,
+        });
+      }
+      chunks.push(/** @type {Buffer} */ (chunk));
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+  }
+  return expr ?? '';
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+export function registerLayout(program) {
+  const layoutCmd = defineCommand(program, layoutGroup);
+
+  defineCommand(layoutCmd, layoutExpandCommand, {
+    fn: layoutExpandFn,
+    action: async (/** @type {string} */ expression, /** @type {string} */ targetPath, /** @type {LayoutExpandOptions} */ options) => {
+      const json = program.opts().json || false;
+      const source = await readExpression(expression, options);
+      if (!source || source.trim() === '') {
+        return cliError(
+          'No layout expression given — pass it as an argument, via --file, or on stdin',
+          {code: ERROR_CODES.ERR_MISSING_ARGUMENT},
+        );
+      }
+      /** @type {LayoutExpandResponse} */
+      let result;
+      try {
+        result = /** @type {LayoutExpandResponse} */ (await layoutExpand(source, {
+          targetPath,
+          form: options.form,
+          loose: options.loose || false,
+          name: options.name,
+          cwd: process.cwd(),
+        }));
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+      }
+      // Expanding turns an expression into TSX — a transformation, not a
+      // lookup. What it produced is in the output; there is no set to count.
+      if (json) {
+        jsonOut(result);
+        return NO_RESULT_SET;
+      }
+
+      /** @type {import('../formatters/index.mjs').Block[]} */
+      const out = [];
+      if (result.data.warnings.length > 0) {
+        out.push(text(result.data.warnings.map(w => `${WARN} ${w}`).join('\n')));
+      }
+      if (result.data.written) {
+        out.push(
+          text(`[ok] Expanded to ${result.data.written}`),
+          // Field names are the JSON keys; todos are summarised, not listed.
+          record(
+            {componentsUsed: result.data.componentsUsed, todos: result.data.todos},
+            {
+              format: {
+                todos: (/** @type {string[]} */ todos) =>
+                  `${todos.length} (search for "TODO(xle)")`,
+              },
+            },
+          ),
+        );
+      } else {
+        // Raw expanded TSX (no target path) — preformatted, emitted verbatim.
+        out.push(code(result.data.code));
+      }
+      emit(...out);
+      return NO_RESULT_SET;
+    },
+  });
+
+  defineCommand(layoutCmd, layoutCheckCommand, {
+    fn: layoutCheckFn,
+    action: async (/** @type {string} */ expression, /** @type {LayoutCheckOptions} */ options) => {
+      const json = program.opts().json || false;
+      const source = await readExpression(expression, options);
+      if (!source || source.trim() === '') {
+        return cliError(
+          'No layout expression given — pass it as an argument, via --file, or on stdin',
+          {code: ERROR_CODES.ERR_MISSING_ARGUMENT},
+        );
+      }
+      /** @type {LayoutCheckResponse} */
+      let result;
+      try {
+        result = /** @type {LayoutCheckResponse} */ (await layoutCheck(source, {
+          form: options.form,
+          loose: options.loose || false,
+          cwd: process.cwd(),
+        }));
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+      }
+      // Exit code is the contract and must NOT depend on --json vs human: an
+      // invalid (but parseable) layout exits 1 in BOTH modes so `layout check`
+      // works as a CI gate / agent check without parsing stdout. Decide it
+      // before the JSON return (parity with doctor integration validate).
+      if (!result.data.valid) process.exitCode = 1;
+
+      // A verdict on one expression: valid or not, with the errors that made
+      // it so. Nothing was looked up.
+      if (json) {
+        jsonOut(result);
+        return NO_RESULT_SET;
+      }
+
+      const {valid, form, errors, warnings, compact, outline} = result.data;
+      if (!valid) {
+        // Each error: the formatted issue, with a hanging "did you mean" line.
+        const items = errors.map(e =>
+          e.suggestions && e.suggestions.length > 0
+            ? [e.formatted, `did you mean: ${e.suggestions.join(', ')}?`]
+            : [e.formatted],
+        );
+        emit(
+          text(`[fail] Invalid (${errors.length} error${errors.length === 1 ? '' : 's'}):`),
+          list(items),
+        );
+        return NO_RESULT_SET;
+      }
+
+      /** @type {import('../formatters/index.mjs').Block[]} */
+      const out = [text(`[ok] Valid (parsed as ${form})`)];
+      if (warnings.length > 0) {
+        out.push(text(warnings.map(w => `${WARN} ${w}`).join('\n')));
+      }
+      // The canonical compact/outline surfaces are preformatted — emit verbatim.
+      out.push(section('compact'), code(compact), section('outline'), code(outline));
+      emit(...out);
+      return NO_RESULT_SET;
+    },
+  });
+
+  defineCommand(layoutCmd, layoutGrammarCommand, {
+    fn: layoutGrammarFn,
+    action: async () => {
+      const json = program.opts().json || false;
+      /** @type {LayoutGrammarResponse} */
+      let result;
+      try {
+        result = /** @type {LayoutGrammarResponse} */ (await layoutGrammar({cwd: process.cwd()}));
+      } catch (e) {
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        return cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
+      }
+      // One document, the same one every time: the grammar cheatsheet.
+      const answered = resultSet({count: 1, resultKind: 'doc'});
+      if (json) {
+        jsonOut(result);
+        return answered;
+      }
+      // The cheatsheet is a preformatted document — emit verbatim.
+      emit(code(result.data.text));
+      return answered;
+    },
+  });
+}

package/clients/cli/commands/layout.path-help.test.mjs

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout expand` and `layout check` document their input modes (the
+ * argument, `-` for stdin, --file) and where `layout expand` writes.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+import {isFilePathArg} from '../../../foundation/fs/path-safety.mjs';
+
+const SLOW = 30_000;
+
+describe('layout argument behavior is documented', () => {
+  it('layout expand help covers stdin, --file precedence and the output path rule', async () => {
+    const {status, stdout} = await runCli(['layout', 'expand', '--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Pass - to read it from stdin/);
+    expect(stdout).toMatch(/instead of the argument/);
+    expect(stdout).toContain('<Name>.tsx');
+    expect(stdout).toMatch(/existing file there is replaced/);
+    const exts = [...(stdout.match(/ends in ([.\w, ]+ or \.\w+)/)?.[1] ?? '').matchAll(/\.\w+/g)];
+    expect(exts.length).toBeGreaterThan(0);
+    for (const [ext] of exts) expect(isFilePathArg(`src/Page${ext}`)).toBe(true);
+  }, SLOW);
+
+  it('layout check help covers stdin and --file precedence', async () => {
+    const {status, stdout} = await runCli(['layout', 'check', '--help']);
+    expect(status).toBe(0);
+    expect(stdout).toMatch(/Pass - to read it from stdin/);
+    expect(stdout).toMatch(/instead of the argument/);
+  }, SLOW);
+});

package/clients/cli/commands/layout.stdin-cap.test.mjs

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout check -` reads the expression from stdin under the same 5 MB
+ * cap as --file, instead of buffering whatever the pipe delivers. Spawns the
+ * real bin, since the in-process harness has no stdin.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {spawnSync} from 'node:child_process';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BIN = path.resolve(HERE, '../bin/astryx.mjs');
+// Run against the monorepo root so @astryxdesign/core is discoverable.
+const REPO = path.resolve(HERE, '../../../..');
+const SLOW = 60_000;
+
+/** @param {string} input @param {string[]} [extra] */
+function checkFromStdin(input, extra = []) {
+  return spawnSync(process.execPath, [BIN, 'layout', 'check', '-', ...extra], {
+    cwd: REPO,
+    input,
+    encoding: 'utf-8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+describe('layout check - (stdin)', () => {
+  it('refuses more than 5 MB with ERR_INVALID_ARGUMENT, in both modes', () => {
+    // Valid once trimmed, so only the cap can reject it.
+    const big = ' '.repeat(5 * 1024 * 1024 + 1) + 'V';
+    const json = checkFromStdin(big, ['--json']);
+    expect(json.status).toBe(1);
+    expect(JSON.parse(json.stdout).code).toBe('ERR_INVALID_ARGUMENT');
+    const human = checkFromStdin(big);
+    expect(human.status).toBe(1);
+    expect(human.stderr + human.stdout).toMatch(/too large/);
+  }, SLOW);
+
+  it('still reads a normal expression', () => {
+    const r = checkFromStdin('V > B', ['--json']);
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout).data.valid).toBe(true);
+  }, SLOW);
+});

package/clients/cli/commands/layout.text-fields.test.mjs

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout expand` text output names its fields after the JSON keys, so
+ * the two views stay greppable against each other.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {runCli} from '../../../test-utils/run-cli.mjs';
+
+const SLOW = 60_000;
+
+describe('layout expand text fields mirror the JSON keys', () => {
+  let cwd;
+  beforeEach(() => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-text-fields-'));
+  });
+  afterEach(() => fs.rmSync(cwd, {recursive: true, force: true}));
+
+  it('labels every record field with a key of the layout.expand data', async () => {
+    const expr = 'V > B + {not-a-real-block}';
+    const json = await runCli(['layout', 'expand', expr, './a', '--loose', '--json'], cwd);
+    expect(json.status).toBe(0);
+    const {data} = JSON.parse(json.stdout);
+    expect(data.todos.length).toBeGreaterThan(0);
+
+    const human = await runCli(['layout', 'expand', expr, './b', '--loose'], cwd);
+    expect(human.status).toBe(0);
+    const fields = human.stdout
+      .split('\n')
+      .map(line => /^([A-Za-z]+):\s/.exec(line)?.[1])
+      .filter(Boolean);
+    expect(fields).toEqual(['componentsUsed', 'todos']);
+    for (const field of fields) expect(Object.keys(data)).toContain(field);
+  }, SLOW);
+});

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,11 +372,34 @@ 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 ──
+  {
+    name: 'layout check',
+    args: ['layout', 'check', 'Button'],
+    skipFieldChecks: true,
+  },
+  {
+    name: 'layout expand',
+    args: ['layout', 'expand', 'Button'],
+    skipFieldChecks: true,
+  },
+  {
+    name: 'layout grammar',
+    args: ['layout', 'grammar'],
+    skipFieldChecks: true,
+  },
+  // ── End layout cases ──
   {
     name: 'manifest',
     args: ['manifest'],

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

package/clients/cli/commands/theme-palette-generate.doc.mjs

@@ -35,12 +35,13 @@ export const doc = {
     {
       flag: '--preview <path>',
       param: 'options.preview',
-      description: 'Write a standardized self-contained HTML preview',
+      description: 'Write a self-contained HTML preview page; the path must end in .html',
     },
     {
       flag: '-f, --overwrite',
       param: 'options.overwrite',
-      description: 'Replace existing candidate and receipt files',
+      description:
+        'Replace existing candidate, receipt, and preview files. Without it, if any of them exists, nothing is written',
     },
   ],
   examples: [

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

@@ -8,8 +8,7 @@ export const doc = {
   namespace: 'cli/commands',
   summary: 'Create and work with theme-owned color palettes',
   description:
-    'Palette authoring tools. The initial generate command creates reviewable candidates. ' +
-    'Palette inspection and diagnostic commands are intentionally deferred to follow-up work.',
+    'Palette authoring tools. generate writes a palette candidate for you to review before a theme uses it.',
   subcommands: ['generate'],
   examples: [
     {

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

@@ -20,8 +20,8 @@ export const doc = {
     'the component that declares it, and the props and states that are legal override keys ' +
     'under it. This is the whole themeable surface in one command: what auditing a theme, or ' +
     'answering "which key paints this pixel?", used to need one `astryx component <Name>` per ' +
-    'component to assemble. Pass a component name to scope it; pass any substring to search ' +
-    'keys. `--json` for a list a repo can lint its own theme against.',
+    'component to assemble. Pass a component name to scope it; pass any other text to search ' +
+    'target keys, classes, and components. `--json` for a list a repo can lint its own theme against.',
   fn: 'themeTargets',
   args: [{name: 'filter', param: 'filter', required: false}],
   examples: [