@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

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

@@ -11,12 +11,9 @@ export const doc = {
   name: 'gap-report',
   displayName: 'astryx gap-report',
   namespace: 'cli/commands',
-  summary: 'Report a missing component or feature to the package that owns it',
+  summary: 'Route a design-system gap to its owning package',
   description:
-    '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.',
+    'Reports a missing component, variant, layout, styling, accessibility, API, or documentation capability. The command selects an explicit package first, then a unique component owner, then Core. The report fans out to every effective handler: project config first, then each loaded integration in config order. Public handlers require --confirm-public per handler; internal handlers always run. A handler failure is isolated and does not prevent later handlers.',
   fn: 'gapReport',
   args: [
     {
@@ -48,14 +45,12 @@ export const doc = {
     {
       flag: '--package <pkg>',
       param: 'options.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',
+      description: 'Route to a specific loaded package',
     },
     {
       flag: '--confirm-public',
       param: 'options.confirmPublic',
-      description:
-        'Allow public delivery: public handlers run, and with no handler it files a GitHub issue with your gh login',
+      description: 'Consent to public handlers or GitHub issue creation',
     },
     {
       flag: '--list-categories',
@@ -67,9 +62,13 @@ export const doc = {
   examples: [
     {label: 'List categories', cli: 'astryx gap-report --list-categories'},
     {
-      label: 'Prepare a report (nothing public happens without --confirm-public)',
+      label: 'Route an agent report',
       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,22 +18,21 @@ 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 ' +
-    "steps. --features and --all print only the chosen features' guidance (no " +
-    'getting-started steps); the theme feature also writes an annotated theme template.',
+    'guidance; features/--all add theme and page-building ' +
+    'guidance and write an annotated theme template.',
   fn: 'init',
   options: [
     {
       flag: '--features <list>',
       param: 'options.features',
       description:
-        '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',
+        'Comma-separated features to install (agents, theme, template). An unknown feature exits 1 with ERR_UNKNOWN_FEATURE. ' +
+        'Ignored with --all or --remove-agents',
     },
     {
       flag: '--all',
       param: 'options.all',
-      description:
-        'Install all features (agents, theme, template); overrides --features. Prints their guidance instead of the getting-started steps',
+      description: 'Install all features (agents, theme, template); overrides --features',
     },
     {
       flag: '--remove-agents',
@@ -48,9 +47,7 @@ export const doc = {
       param: 'options.agent',
       choices: ['claude', 'cursor', 'codex', 'hermes', 'muse', 'all'],
       description:
-        '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. ' +
+        'Target AI tool for agent docs: claude, cursor, codex, hermes, muse, all. An unknown tool exits 1 with ERR_UNKNOWN_AGENT. ' +
         'Used only when agent docs are installed (the default, --all, or --features agents); --agent-docs-path takes precedence',
     },
     {

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 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}.',
+    '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.',
   fn: 'integrationAdd',
   args: [
     {
@@ -60,14 +60,10 @@ export const doc = {
       flag: '--to <version>',
       param: 'options.to',
       description:
-        'Exact semver of the @astryxdesign/core version whose upgrade runs the codemod (e.g. 0.7.0); required for codemod and only valid there',
+        'Exact semver the codemod migrates to (e.g. 1.2.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',
@@ -75,7 +71,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 acme-dashboard',
+      cli: 'astryx integration add template dashboard',
     },
     {
       label: 'Add a block template',
@@ -91,7 +87,7 @@ export const doc = {
     },
     {
       label: 'Add a guide to the package\'s own docs section',
-      cli: 'astryx integration add doc releasing --parent acme',
+      cli: 'astryx integration add doc deploying --parent acme',
     },
     {
       label: 'Add a codemod',
@@ -102,6 +98,10 @@ 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 verify', 'doctor integration validate', 'theme add'],
+  related: ['integration pack', 'doctor integration validate', 'theme add'],
 };

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

@@ -127,7 +127,10 @@ describe('integration authoring CLI', () => {
     );
     expect(added.status).toBe(0);
 
-    const checked = await runCli(['integration', 'verify', '--json'], tmpDir);
+    const checked = await runCli(
+      ['integration', 'pack', '--check', '--json'],
+      tmpDir,
+    );
     // Without an exports map, the extensionless import cannot resolve —
     // pack-check must fail, not false-green.
     expect(checked.status).not.toBe(0);
@@ -147,67 +150,13 @@ describe('integration authoring CLI', () => {
     );
   });
 
-  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'}),
-      ]),
+  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.',
     });
-    // 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,18 +6,22 @@ export const doc = {
   name: 'integration pack',
   displayName: 'astryx integration pack',
   namespace: 'cli/commands',
-  summary: 'Deprecated: the old name of `integration verify`',
+  summary: 'Prove the packed integration is what consumers receive',
   description:
-    '`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.',
+    '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.',
   fn: 'integrationPackCheck',
   options: [
     {
       flag: '--check',
-      description: 'Run the check. Required, as before.',
+      description: 'Run the packed-package verification gate',
     },
   ],
   examples: [
-    {label: 'The old spelling', cli: 'astryx integration pack --check'},
+    {label: 'Verify before publishing', cli: 'astryx integration pack --check'},
+    {
+      label: 'Machine-readable result',
+      cli: 'astryx integration pack --check --json',
+    },
   ],
   exitCodes: [
     {code: 0, when: 'the packed package exposes the same valid contributions'},
@@ -26,5 +30,5 @@ export const doc = {
       when: '--check is omitted or the tarball is incomplete or invalid',
     },
   ],
-  related: ['integration verify'],
+  related: ['integration add', 'doctor integration validate'],
 };

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

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

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 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'],
+    'Add contributions that are valid on arrival, then prove the packed package exposes the same contributions a consumer will receive.',
+  subcommands: ['add', 'pack'],
   examples: [
     {
       label: 'Add a component',
       cli: 'astryx integration add component AcmeWidget',
     },
     {
-      label: 'Check the package before publishing',
-      cli: 'astryx integration verify',
+      label: 'Check the package tarball',
+      cli: 'astryx integration pack --check',
     },
   ],
   exitCodes: [

package/clients/cli/commands/integration.mjs

@@ -12,7 +12,6 @@ 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';
@@ -25,16 +24,8 @@ import {doc as integrationPackCheckFn} from '../../../api/integration/integratio
  */
 function showGroupOrUnknown(command, label, options, invoked) {
   const extras = invoked?.args ?? [];
-  // 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)}'`, {
+  if (extras.length > 0) {
+    return cliError(`unknown subcommand '${label} ${String(extras[0])}'`, {
       suggestions: (command.commands ?? []).map(child => ({
         name: child.name(),
         reason: 'available subcommand',
@@ -46,48 +37,6 @@ 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} */
@@ -96,10 +45,6 @@ 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,
@@ -157,29 +102,53 @@ 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, or run `astryx integration verify`.',
-          {code: ERROR_CODES.ERR_INVALID_ARGUMENT},
-        );
+        return cliError('Pass --check to verify the integration tarball.', {
+          code: ERROR_CODES.ERR_INVALID_ARGUMENT,
+        });
       }
-      // 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.',
-        );
+
+      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);
       }
-      return verifyPackage(program);
+      if (!result.data.packable) process.exitCode = 1;
+      return NO_RESULT_SET;
     },
   });
 }

package/clients/cli/commands/layout-check.doc.mjs

@@ -0,0 +1,65 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx layout check`. The terminal binding of the
+ * `layoutCheck()` function (referenced via `fn`); its args/flags map to that
+ * function's params so a converter can build Commander config + --help from one
+ * source of truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'layout check',
+  displayName: 'astryx layout check',
+  namespace: 'cli/commands',
+  summary:
+    'Validate a layout expression and echo canonical compact/outline forms',
+  description:
+    'Parses and validates a compressed XLE/XLO expression without generating any TSX, and ' +
+    'echoes it back in both canonical surfaces (compact and outline). An invalid but ' +
+    'parseable expression is reported with line/col and suggestions, and exits non-zero.',
+  fn: 'layoutCheck',
+  args: [
+    {
+      name: 'expression',
+      param: 'expression',
+      required: false,
+      description:
+        'The XLE/XLO expression. Pass - to read it from stdin; --file reads it from a file instead.',
+    },
+  ],
+  options: [
+    {
+      flag: '--file <file>',
+      description: 'Read the expression from a file (used instead of the argument when both are given)',
+    },
+    {
+      flag: '--form <form>',
+      param: 'options.form',
+      choices: ['compact', 'outline', 'auto'],
+      default: 'auto',
+      description: 'Input surface: compact, outline, or auto',
+    },
+    {
+      flag: '--loose',
+      param: 'options.loose',
+      description: 'Downgrade unknown {block} hints to TODO placeholders',
+    },
+  ],
+  examples: [
+    {
+      label: 'Validate an expression',
+      cli: "astryx layout check 'A[cp6] > L > LC > S[p6]' --json",
+    },
+  ],
+  exitCodes: [
+    {code: 0, when: 'the expression is valid'},
+    {
+      code: 1,
+      when: 'the expression is invalid, empty or over 5 MB (from stdin or --file), has a syntax error, or a bad --form',
+    },
+  ],
+  related: ['layout expand', 'layout grammar'],
+};

package/clients/cli/commands/layout-expand.doc.mjs

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx layout expand`. The terminal binding of the
+ * `layoutExpand()` function (referenced via `fn`); its args/flags map to that
+ * function's params so a converter can build Commander config + --help from one
+ * source of truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'layout expand',
+  displayName: 'astryx layout expand',
+  namespace: 'cli/commands',
+  summary: 'Expand a layout expression into validated XDS TSX',
+  description:
+    'Parses and validates a compressed XLE/XLO expression, then expands it into ' +
+    'ready-to-use XDS TSX, routing children into slots, scaffolding typed useState for ' +
+    'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
+  fn: 'layoutExpand',
+  args: [
+    {
+      name: 'expression',
+      param: 'expression',
+      required: false,
+      description:
+        'The XLE/XLO expression. Pass - to read it from stdin; --file reads it from a file instead.',
+    },
+    {
+      name: 'path',
+      param: 'options.targetPath',
+      required: false,
+      description:
+        'Where to write the TSX, relative to the project root. A path that ends in .tsx, .ts, .jsx, .js, .mjs, .cjs, .css, .scss, .json, .md or .html is the file to write; ' +
+        'any other path is a directory, which receives <Name>.tsx (see --name). An existing file there is replaced. ' +
+        'Omit it to print the code.',
+    },
+  ],
+  options: [
+    {
+      flag: '--file <file>',
+      description: 'Read the expression from a file (used instead of the argument when both are given)',
+    },
+    {
+      flag: '--form <form>',
+      param: 'options.form',
+      choices: ['compact', 'outline', 'auto'],
+      default: 'auto',
+      description: 'Input surface: compact, outline, or auto',
+    },
+    {
+      flag: '--name <name>',
+      param: 'options.name',
+      default: 'GeneratedLayout',
+      description: 'Generated component name (PascalCase)',
+    },
+    {
+      flag: '--loose',
+      param: 'options.loose',
+      description: 'Downgrade unknown {block} hints to TODO placeholders',
+    },
+  ],
+  examples: [
+    {
+      label: 'Expand to a file',
+      cli: "astryx layout expand 'V[g6] > C{card-callout}*4' ./src/Page.tsx",
+    },
+    {
+      label: 'From a file, named',
+      cli: 'astryx layout expand --file layout.xlo --name Dashboard',
+    },
+  ],
+  exitCodes: [
+    {code: 0, when: 'success'},
+    {
+      code: 1,
+      when: 'a missing, empty or over-5 MB expression (from stdin or --file), a bad --name or --form, a parse/validation error, or a path escape',
+    },
+  ],
+  related: ['layout check', 'layout grammar'],
+};

package/clients/cli/commands/layout-grammar.doc.mjs

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CommandDoc for `astryx layout grammar`. The terminal binding of the
+ * `layoutGrammar()` function (referenced via `fn`); it carries only CLI-surface
+ * facts so a converter can build Commander config + --help from one source of
+ * truth.
+ * @position packages/cli/clients/cli/commands — command documentation
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').CommandDoc} */
+export const doc = {
+  type: 'command',
+  name: 'layout grammar',
+  displayName: 'astryx layout grammar',
+  namespace: 'cli/commands',
+  summary:
+    'Print the XLE/XLO cheatsheet (alias table generated from this branch)',
+  description:
+    'Prints the XLE/XLO grammar cheatsheet for writing layout expressions, with the alias ' +
+    "table generated from this install's registry so short names always reflect the " +
+    'components actually available.',
+  fn: 'layoutGrammar',
+  examples: [{label: 'Get the cheatsheet', cli: 'astryx layout grammar'}],
+  exitCodes: [
+    {code: 0, when: 'success'},
+    {code: 1, when: 'the component registry cannot be read'},
+  ],
+  related: ['layout expand', 'layout check'],
+};