@astryxdesign/cli 0.6.4-canary.f0355e3 → 0.6.4

package/foundation/integrations/cli-requirement.mjs

@@ -6,9 +6,8 @@
  * @input A package.json object.
  * @output Whether its `peerDependencies` range for `@astryxdesign/cli` admits
  *   only CLIs that read namespace docs, and the package.json that declares it.
- * @position foundation/integrations; read by `integration add doc --parent`
- *   and `integration add theme`, which declare the peer, and
- *   `integration verify`, which requires it.
+ * @position foundation/integrations; read by `integration add doc --parent`,
+ *   which declares the peer, and `integration pack --check`, which requires it.
  */
 
 import {semverCompare} from '../env/semver.mjs';
@@ -17,12 +16,10 @@ export const CLI_PACKAGE = '@astryxdesign/cli';
 
 /**
  * The first CLI release that reads an integration's docs tree (namespace docs
- * and placed guides), its templates' `replaces`, and its typed theme
- * descriptors. A release before it can hide every doc topic a package with a
- * namespace doc or a placed guide ships, with no warning; it rejects
- * `replaces`, drops that template, and hides the package's doc topics; and it
- * rejects a themes root without the `manifest.json` catalog the CLI no longer
- * writes, withholding the package's themes and doc topics.
+ * and placed guides) and its templates' `replaces`. A release before it can
+ * hide every doc topic a package with a namespace doc or a placed guide
+ * ships, with no warning, and it rejects `replaces` and withholds the
+ * package's templates and doc topics.
  */
 export const DOCS_TREE_CLI = '0.7.0';
 
@@ -95,11 +92,11 @@ function cliRangeProblem(pkg, feature, loss) {
   const range = pkg?.peerDependencies?.[CLI_PACKAGE];
   const fix = `"${CLI_PACKAGE}": ">=${DOCS_TREE_CLI}" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required)`;
   if (typeof range !== 'string') {
-    return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A stable CLI before ${DOCS_TREE_CLI} ${loss}. Declare ${fix}.`;
+    return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A CLI older than ${DOCS_TREE_CLI} ${loss}. Declare ${fix}.`;
   }
   const lowest = lowestAdmitted(range);
   if (lowest == null || semverCompare(lowest, DOCS_TREE_CLI) < 0) {
-    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a stable CLI before ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
+    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a CLI older than ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
   }
   return null;
 }
@@ -122,8 +119,8 @@ export function docsTreeCliProblem(pkg) {
 }
 
 /**
- * Why a package with a template that sets `replaces` would lose templates and
- * doc topics on an older CLI (spec:AST-035), or null when its declared CLI
+ * Why a package with a template that sets `replaces` would lose its templates
+ * and doc topics on an older CLI (spec:AST-035), or null when its declared CLI
  * range admits only CLIs that read the field.
  * @param {any} pkg package.json
  * @returns {string | null}
@@ -132,39 +129,7 @@ export function replacesCliProblem(pkg) {
   return cliRangeProblem(
     pkg,
     'has a template that sets `replaces`',
-    "rejects the field, drops that template, and hides the package's doc topics",
-  );
-}
-
-/**
- * Why a package with a doc section that sets `id` would lose its doc topics on
- * an older CLI, or null when its declared CLI range admits only CLIs that read
- * the field. Published 0.6.3 rejects a section `id` and hides every doc topic
- * the package ships.
- * @param {any} pkg package.json
- * @returns {string | null}
- */
-export function sectionIdsCliProblem(pkg) {
-  return cliRangeProblem(
-    pkg,
-    'has a doc section that sets `id`',
-    'rejects the field, and can hide every doc topic the package ships',
-  );
-}
-
-/**
- * Why a package that ships a theme would lose its themes and doc topics on an
- * older CLI, or null when its declared CLI range admits only CLIs that read
- * typed theme descriptors. Published 0.6.3 rejects a themes root with no
- * `manifest.json` catalog, which `integration add theme` no longer writes.
- * @param {any} pkg package.json
- * @returns {string | null}
- */
-export function themesCliProblem(pkg) {
-  return cliRangeProblem(
-    pkg,
-    'ships a theme',
-    "cannot read typed theme descriptors, and can drop the package's themes and hide its doc topics",
+    "rejects the field, and withholds the package's templates and doc topics",
   );
 }
 

package/foundation/integrations/cli-requirement.test.mjs

@@ -32,11 +32,6 @@ describe('docsTreeCliProblem', () => {
     expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
       'declares no @astryxdesign/cli peer',
     );
-    // Stable releases: a canary built from main before its release reports
-    // the older version and reads every feature.
-    expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
-      'A stable CLI before 0.7.0 does not read the docs tree',
-    );
   });
 
   it.each(['^0.6.0', '^0.6.0 || >=0.7.0', '*', '>=0.6.3'])(
@@ -44,7 +39,7 @@ describe('docsTreeCliProblem', () => {
     range => {
       expect(
         docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
-      ).toContain('admits a stable CLI before');
+      ).toContain('admits a CLI older than');
     },
   );
 
@@ -81,7 +76,7 @@ describe('replacesCliProblem', () => {
     );
     expect(
       replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '^0.6.0'}}),
-    ).toContain('admits a stable CLI before');
+    ).toContain('admits a CLI older than');
     expect(
       replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),
     ).toBeNull();

package/foundation/integrations/contribution-inventory.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Contribution inventory for `astryx integration verify`.
+ * @file Contribution inventory for integration pack-check.
  *
  * Enumerates the files and contribution identities an integration package
  * declares, for cross-referencing against the npm tarball. The file inventory

package/foundation/integrations/integrations.d.mts

@@ -45,7 +45,7 @@ export function findManifestPaths(dir: string): string[];
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, agentDocsError?: string}>}
  */
 export function loadManifest(file: string, label?: string, { fresh }?: {
     fresh?: boolean;
@@ -55,8 +55,6 @@ export function loadManifest(file: string, label?: string, { fresh }?: {
     debug?: import("../../authoring/debug/type").DebugEventHandler;
     gapReport?: import("../../authoring/gap-report/type").GapReportHandler;
     gapReportError?: string;
-    discover?: import("../../authoring/discover/type").DiscoverSource;
-    discoverError?: string;
     agentDocsError?: string;
 }>;
 /**
@@ -156,9 +154,6 @@ export function loadIntegrations(specs?: string[], { cwd, fresh, resolveProvider
  *   validated package-owned handler from the `gapReport` NAMED export.
  * @property {string} [__gapReportError] isolated named-handler validation error.
  *   Named exports are not manifest keys — see {@link loadManifest}.
- * @property {import('../../authoring/discover/type').DiscoverSource} [__discover]
- *   validated catalog source from the `discover` NAMED export.
- * @property {string} [__discoverError] isolated discover-source validation error.
  */
 /** Conventional manifest basenames, in load-precedence order. */
 export const MANIFEST_BASENAMES: string[];
@@ -250,12 +245,4 @@ export type LoadedIntegration = {
      * Named exports are not manifest keys — see {@link loadManifest}.
      */
     __gapReportError?: string | undefined;
-    /**
-     * validated catalog source from the `discover` NAMED export.
-     */
-    __discover?: import("../../authoring/discover/type").DiscoverSource | undefined;
-    /**
-     * isolated discover-source validation error.
-     */
-    __discoverError?: string | undefined;
 };

package/foundation/integrations/integrations.mjs

@@ -29,7 +29,6 @@ import {
 } from '../../authoring/integration/schema.mjs';
 import {importUserModule, findPresentFiles} from '../fs/module-loader.mjs';
 import {parseGapReportHandler} from '../../authoring/gap-report/parse.mjs';
-import {parseDiscoverSource} from '../../authoring/discover/parse.mjs';
 import {resolveProviders} from './provider-resolution.mjs';
 
 /**
@@ -81,9 +80,6 @@ import {resolveProviders} from './provider-resolution.mjs';
  *   validated package-owned handler from the `gapReport` NAMED export.
  * @property {string} [__gapReportError] isolated named-handler validation error.
  *   Named exports are not manifest keys — see {@link loadManifest}.
- * @property {import('../../authoring/discover/type').DiscoverSource} [__discover]
- *   validated catalog source from the `discover` NAMED export.
- * @property {string} [__discoverError] isolated discover-source validation error.
  */
 
 /** Conventional manifest basenames, in load-precedence order. */
@@ -171,23 +167,6 @@ function parseGapReportHandlerExport(value, label) {
   }
 }
 
-/**
- * Parse the optional named discover source the same way: a malformed one is
- * isolated from every other contribution and reported by `astryx discover`.
- *
- * @param {unknown} value
- * @param {string} label
- * @returns {{source?: import('../../authoring/discover/type').DiscoverSource, error?: string}}
- */
-function parseDiscoverSourceExport(value, label) {
-  if (value === undefined) return {};
-  try {
-    return {source: parseDiscoverSource(value, `${label} named export "discover"`)};
-  } catch (error) {
-    return {error: error instanceof Error ? error.message : String(error)};
-  }
-}
-
 /**
  * Load and validate a manifest module's default export, while isolating the
  * optional `agentDocs` contribution from the manifest's other fields.
@@ -204,7 +183,7 @@ function parseDiscoverSourceExport(value, label) {
  * @param {string} file absolute manifest path
  * @param {string} [label] used in error messages
  * @param {{fresh?: boolean}} [options]
- * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, discover?: import('../../authoring/discover/type').DiscoverSource, discoverError?: string, agentDocsError?: string}>}
+ * @returns {Promise<{manifest: import('../../authoring/integration/type').AstryxIntegration, unknownKeys: string[], debug?: import('../../authoring/debug/type').DebugEventHandler, gapReport?: import('../../authoring/gap-report/type').GapReportHandler, gapReportError?: string, agentDocsError?: string}>}
  */
 export async function loadManifest(
   file,
@@ -215,7 +194,6 @@ export async function loadManifest(
   const raw = mod?.default;
   const baseManifest = parseIntegrationBase(raw, label);
   const gapReport = parseGapReportHandlerExport(mod?.gapReport, label);
-  const discover = parseDiscoverSourceExport(mod?.discover, label);
   const hasAgentDocs =
     raw != null &&
     typeof raw === 'object' &&
@@ -250,8 +228,6 @@ export async function loadManifest(
         : undefined,
     gapReport: gapReport.handler,
     gapReportError: gapReport.error,
-    discover: discover.source,
-    discoverError: discover.error,
     agentDocsError,
   };
 }
@@ -369,10 +345,6 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
   let gapReportHandler;
   /** @type {string | undefined} */
   let gapReportError;
-  /** @type {import('../../authoring/discover/type').DiscoverSource | undefined} */
-  let discoverSource;
-  /** @type {string | undefined} */
-  let discoverError;
   /** @type {string | undefined} */
   let agentDocsError;
   try {
@@ -382,8 +354,6 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
       debug: debugHandler,
       gapReport: gapReportHandler,
       gapReportError,
-      discover: discoverSource,
-      discoverError,
       agentDocsError,
     } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
   } catch (err) {
@@ -427,8 +397,6 @@ export async function loadLocalIntegration(packageDir, {fresh = false} = {}) {
     __debug: debugHandler,
     __gapReport: gapReportHandler,
     __gapReportError: gapReportError,
-    __discover: discoverSource,
-    __discoverError: discoverError,
     __spec: spec,
     __packageDir: packageDir,
     __packageExports: pkg.exports ?? null,
@@ -480,10 +448,6 @@ export async function loadIntegrations(
     let gapReportHandler;
     /** @type {string | undefined} */
     let gapReportError;
-    /** @type {import('../../authoring/discover/type').DiscoverSource | undefined} */
-    let discoverSource;
-    /** @type {string | undefined} */
-    let discoverError;
     /** @type {string | undefined} */
     let agentDocsError;
     try {
@@ -493,8 +457,6 @@ export async function loadIntegrations(
         debug: debugHandler,
         gapReport: gapReportHandler,
         gapReportError,
-        discover: discoverSource,
-        discoverError,
         agentDocsError,
       } = await loadManifest(manifestFile, `Integration ${spec}`, {fresh}));
     } catch (err) {
@@ -545,8 +507,6 @@ export async function loadIntegrations(
       __debug: debugHandler,
       __gapReport: gapReportHandler,
       __gapReportError: gapReportError,
-      __discover: discoverSource,
-      __discoverError: discoverError,
       __spec: spec,
       __packageDir: packageDir,
       __packageExports: pkg.exports ?? null,

package/foundation/integrations/integrations.test.mjs

@@ -785,34 +785,3 @@ describe('the `gapReport` named export', () => {
     expect(loaded.__unknownKeys).toEqual(['gapReport']);
   });
 });
-
-describe('the `discover` named export', () => {
-  it('is carried out of the manifest module as __discover', async () => {
-    writeManifestPackage(tmpDir, {
-      body:
-        `export async function discover() { return {schemaVersion: 1}; }\n` +
-        `export default {issuesUrl: 'https://example.com/i'};\n`,
-    });
-
-    const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
-
-    expect(typeof loaded.__discover).toBe('function');
-    expect(loaded.__discoverError).toBeUndefined();
-    expect(loaded.__unknownKeys).toEqual([]);
-    expect(loaded.issuesUrl).toBe('https://example.com/i');
-  });
-
-  it('keeps the manifest and records why when the export is not a function', async () => {
-    writeManifestPackage(tmpDir, {
-      body:
-        `export const discover = {url: 'https://example.com/catalog.json'};\n` +
-        `export default {issuesUrl: 'https://example.com/i'};\n`,
-    });
-
-    const [loaded] = await loadIntegrations(['@acme/widgets'], {cwd: tmpDir});
-
-    expect(loaded.__discover).toBeUndefined();
-    expect(loaded.__discoverError).toContain('must be a function');
-    expect(loaded.issuesUrl).toBe('https://example.com/i');
-  });
-});

package/foundation/response/error-codes.doc.mjs

@@ -36,16 +36,17 @@ export const doc = {
     {
       value: 'ERR_INVALID_OPTION',
       description:
-        'An unknown option was passed, --json was given to a command without JSON output, or layout --form got a value other than compact, outline, or auto.',
+        'An unknown flag/option was passed (Commander `unknownOption`).',
     },
     {
       value: 'ERR_INVALID_ARGUMENT',
       description:
-        'An argument or option value is invalid: wrong type, out of range, an unknown choice, an extra argument, or a conflicting combination.',
+        "An option/argument had a value Commander's parser rejected.",
     },
     {
       value: 'ERR_MISSING_ARGUMENT',
-      description: 'A required argument or option value was omitted.',
+      description:
+        'A required positional argument was omitted (Commander `missingArgument`).',
     },
     {
       value: 'ERR_INVALID_LANG',
@@ -133,11 +134,12 @@ export const doc = {
     },
     {
       value: 'ERR_UNKNOWN_PACKAGE',
-      description: 'No package matched the requested name.',
+      description: 'No package matched the requested name (discover).',
     },
     {
       value: 'ERR_UNKNOWN_AGENT',
-      description: 'An unrecognized `--agent` value was passed to init.',
+      description:
+        'An unrecognized `--agent` value was passed to agent-docs/init.',
     },
     {
       value: 'ERR_UNKNOWN_FEATURE',
@@ -270,7 +272,7 @@ export const doc = {
     {
       value: 'ERR_UNCLASSIFIED_EXIT',
       description:
-        'Recorded in the debug log, never printed: a command exited non-zero without reporting an error code.',
+        'Recorded in the debug log, never printed: a command exited non-zero without going through cliError/jsonError, so no stable code was available.',
     },
     {
       value: 'ERR_SIGNAL_TERMINATED',

package/foundation/response/error-codes.test.mjs

@@ -195,15 +195,8 @@ describe('error codes: end-to-end JSON envelopes', () => {
     // is rejected at the preAction gate with a stable invalid-option code.
     {
       name: 'json not supported',
-      args: ['theme', '--json'],
-      code: 'ERR_INVALID_OPTION',
-    },
-    // A group given a word it does not have names the unknown subcommand,
-    // in JSON as in text.
-    {
-      name: 'unknown subcommand of a group',
       args: ['theme', 'bogus-sub', '--json'],
-      code: 'ERR_UNKNOWN_SUBCOMMAND',
+      code: 'ERR_INVALID_OPTION',
     },
   ];
 
@@ -256,31 +249,13 @@ describe('error codes: human mode stays clean', () => {
     expect(stdout).not.toContain('ERR_UNKNOWN_COMPONENT');
   });
 
-  it('unknown subcommand exits 1, with the code in JSON and not in text', async () => {
-    // A group that is not JSON-capable itself still answers an unknown
-    // subcommand in JSON, so a JSON caller learns the subcommands it has.
+  it('unknown subcommand exits 1 in human mode (code carried internally)', async () => {
+    // `theme` is not JSON-capable, so this path is human-only; we assert the
+    // failure surfaces with exit 1 and a helpful message. The stable
+    // ERR_UNKNOWN_SUBCOMMAND code rides along on the cliError call.
     const {status, stderr} = await runCli(['theme', 'bogus-sub']);
     expect(status).toBe(1);
     expect(stderr).toContain("unknown subcommand 'theme bogus-sub'");
     expect(stderr).not.toContain('ERR_UNKNOWN_SUBCOMMAND');
-    for (const args of [
-      ['--json', 'theme', 'bogus-sub'],
-      ['theme', 'bogus-sub', '--json'],
-      ['--json', 'doctor', 'integration', 'bogus-sub'],
-    ]) {
-      const json = await runCli(args);
-      expect(json.status, args.join(' ')).toBe(1);
-      expect(JSON.parse(json.stdout), args.join(' ')).toMatchObject({
-        code: 'ERR_UNKNOWN_SUBCOMMAND',
-        suggestions: expect.arrayContaining([expect.objectContaining({reason: 'available subcommand'})]),
-      });
-    }
-    // Text and JSON agree for a group that shows help when run bare.
-    const text = await runCli(['doctor', 'integration', 'bogus-sub']);
-    expect(text.status).toBe(1);
-    expect(text.stderr).toContain("unknown subcommand 'doctor integration bogus-sub'");
-    const doctor = await runCli(['doctor', 'integrations']);
-    expect(doctor.status).toBe(1);
-    expect(doctor.stderr).toContain("unknown subcommand 'doctor integrations'");
   });
 });

package/foundation/response/response-types.doc.d.mts

@@ -4,10 +4,9 @@
 /**
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
- * `jsonOut(...)` call sites) plus ROOT_RESPONSE_TYPES (help, version) in
- * `clients/cli/lib/manifest.mjs`; a consumer switches on `type` to narrow the
- * `data` payload. Descriptions follow the currently published response
- * projection, not a future package-version boundary.
+ * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
+ * switches on `type` to narrow the `data` payload. Descriptions follow the
+ * currently published response projection, not a future package-version boundary.
  *
  * @input Public response discriminants and their currently released payloads.
  * @output Generated consumer reference for every typed JSON success response.

package/foundation/response/response-types.doc.mjs

@@ -3,10 +3,9 @@
 /**
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
- * `jsonOut(...)` call sites) plus ROOT_RESPONSE_TYPES (help, version) in
- * `clients/cli/lib/manifest.mjs`; a consumer switches on `type` to narrow the
- * `data` payload. Descriptions follow the currently published response
- * projection, not a future package-version boundary.
+ * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
+ * switches on `type` to narrow the `data` payload. Descriptions follow the
+ * currently published response projection, not a future package-version boundary.
  *
  * @input Public response discriminants and their currently released payloads.
  * @output Generated consumer reference for every typed JSON success response.
@@ -36,12 +35,7 @@ export const doc = {
     {
       value: 'component.list',
       description:
-        "The component catalog grouped by component group (each component's group field): `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.",
-    },
-    {
-      value: 'component.batch',
-      description:
-        'The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found | not_found | ambiguous | error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}).',
+        'The component catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.',
     },
     {
       value: 'component.detail',
@@ -110,27 +104,21 @@ export const doc = {
     {
       value: 'discover.list',
       description:
-        'The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
+        'The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".',
     },
     {
       value: 'discover.detail',
-      description:
-        'One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it.',
+      description: 'A single external package entry, for an @scope/name query.',
     },
     {
       value: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one installed component, for an @scope/name/Component query.',
-    },
-    {
-      value: 'discover.item',
-      description:
-        'One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package.',
+        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.',
     },
     {
       value: 'discover.search',
       description:
-        'The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list.',
+        'The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.',
     },
 
     // search
@@ -161,7 +149,7 @@ export const doc = {
     {
       value: 'swizzle.copy',
       description:
-        'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.',
+        'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.',
     },
 
     // gap reports
@@ -263,11 +251,6 @@ export const doc = {
       description:
         'Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.',
     },
-    {
-      value: 'upgrade.registry',
-      description:
-        'The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.',
-    },
     {
       value: 'upgrade.status',
       description:
@@ -286,24 +269,11 @@ export const doc = {
         'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
     },
 
-    // help and version, which no single command owns
-    {
-      value: 'help',
-      description:
-        'Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). ' +
-        "`--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). " +
-        'data.manifest marks the first shape; data.usage marks the second.',
-    },
-    {
-      value: 'version',
-      description: 'The CLI version, for `astryx --version --json`: {version}.',
-    },
-
     // doctor
     {
       value: 'doctor',
       description:
-        'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.',
+        'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and a fix when not passing) plus a `summary` of counts per status.',
     },
 
     // integration authoring
@@ -337,5 +307,22 @@ export const doc = {
       description:
         'The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`).',
     },
+
+    // layout (XLE/XLO)
+    {
+      value: 'layout.expand',
+      description:
+        'The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).',
+    },
+    {
+      value: 'layout.check',
+      description:
+        'The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).',
+    },
+    {
+      value: 'layout.grammar',
+      description:
+        "The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.",
+    },
   ],
 };

package/foundation/response/response-types.doc.test.mjs

@@ -53,29 +53,6 @@ function expectNamed(type, fields) {
 }
 
 describe('response-types EnumDoc names every field', () => {
-  it('component.batch names every row field and state', async () => {
-    const res = await data(['component', 'Button', 'Badge']);
-    expect(res.type).toBe('component.batch');
-    expect(describedAs('component.batch')).toMatch(/BatchResponse.*BatchRow/);
-    expectNamed('component.batch', [
-      'count',
-      'results',
-      'selector',
-      'status',
-      'result',
-      'code',
-      'error',
-      'candidates',
-      'package',
-      'component',
-      'kind',
-      'installed',
-      'suggestions',
-      'name',
-      'reason',
-    ]);
-  });
-
   it('component.detail: the ownership fields and parentDoc', async () => {
     const res = await data(['component', 'HStack']);
     expect(res.type).toBe('component.detail');