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

package/assets/docs/working-with-ai.doc.mjs

@@ -8,6 +8,7 @@ export const docs = {
   category: 'guide',
   description:
     'How to set up AI coding tools to generate correct component code.',
+  keywords: ['claude', 'cursor', 'codex', 'copilot', 'agents', 'mcp'],
 
   sections: [
     {
@@ -24,7 +25,8 @@ export const docs = {
       ],
     },
     {
-      title: 'Quick Start',
+      id: 'quick-start',
+      title: 'Set up agent docs',
       content: [
         {
           type: 'prose',
@@ -38,7 +40,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade` reports a stale block and `astryx upgrade --apply` refreshes it.",
+          text: "That's it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference, and package guidance from configured integrations) from the installed project. After a dependency bump, `astryx upgrade --from <old version>` reports a stale block and adding `--apply` refreshes it.",
         },
         {
           type: 'prose',
@@ -48,10 +50,12 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Manual options',
-          code: `npx @astryxdesign/cli init --features agents --agent claude    # .claude/CLAUDE.md
-npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules
+          code: `npx @astryxdesign/cli init --features agents --agent claude    # CLAUDE.md if present, else .claude/CLAUDE.md
+npx @astryxdesign/cli init --features agents --agent cursor    # .cursorrules if present, else AGENTS.md
 npx @astryxdesign/cli init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)
-npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)`,
+npx @astryxdesign/cli init --features agents --agent hermes    # .hermes.md or HERMES.md if present, else AGENTS.md
+npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse)
+npx @astryxdesign/cli init --features agents --agent all       # every agent file present, else AGENTS.md and .claude/CLAUDE.md`,
         },
       ],
     },
@@ -82,14 +86,17 @@ npx @astryxdesign/cli init --features agents --agent muse      # AGENTS.md (Muse
       content: [
         {
           type: 'prose',
-          text: 'Cursor project rules aren\'t always picked up; it selects which rules to apply based on relevance. For reliable inclusion, install the design system context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects.',
+          text: 'Cursor reads project rules from `.cursor/rules/`. To keep the Astryx context in a rule of its own, write it there. Give a path relative to the project root, such as `.cursor/rules/astryx.mdc`; an absolute path is refused.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Install as a Cursor user rule',
-          code: `mkdir -p ~/.cursor/rules
-npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
+          label: 'Install as a Cursor project rule',
+          code: `npx @astryxdesign/cli init --features agents --agent-docs-path .cursor/rules/astryx.mdc`,
+        },
+        {
+          type: 'prose',
+          text: 'Rerunning the same command rewrites only the Astryx block, so frontmatter you add above it (such as `alwaysApply: true`) stays.',
         },
       ],
     },
@@ -98,7 +105,7 @@ npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/x
       content: [
         {
           type: 'prose',
-          text: 'Paste this into your AI before writing any component code. These three questions have a 0% pass rate without docs; models confidently guess wrong on all of them. If your AI can\'t answer them, it\'ll know to install the agent docs first.',
+          text: 'Paste this into your AI before writing any component code. If your AI can\'t answer these questions, it\'ll know to install the agent docs first.',
         },
         {
           type: 'code',
@@ -107,7 +114,7 @@ npx @astryxdesign/cli init --features agents --agent-docs-path ~/.cursor/rules/x
           code: `Before writing any Astryx code, check your knowledge:
 
 1. What is the correct import path for Button?
-2. How do you make an Dialog non-dismissible?
+2. How do you make a Dialog non-dismissible?
 3. What prop does Selector use for its items?
 
 If you don't know all three, run \`npx @astryxdesign/cli init --features agents\` to generate agent docs, then read the generated file.`,
@@ -131,33 +138,34 @@ If you don't know all three, run \`npx @astryxdesign/cli init --features agents\
         },
         {
           type: 'prose',
-          text: 'With this alias, agents use `astryx component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
+          text: 'With this alias, agents run `npm run astryx -- component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Reliable CLI invocation',
-          code: `astryx component --list
-astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+          code: `npm run astryx -- component --list
+npm run astryx -- component Dialog --dense
+npm run astryx -- docs styling --full --detail brief
+npm run astryx -- docs tokens --dense`,
         },
       ],
     },
     {
-      title: 'The --dense Flag',
+      id: 'the-dense-flag',
+      title: 'Shorter output: --detail and --dense',
       content: [
         {
           type: 'prose',
-          text: 'Every CLI command supports --dense, which outputs a token-efficient format designed for AI context windows. Use it when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
+          text: 'For a shorter read, add `--detail brief` (one line per section) or `--detail compact`. `--dense` swaps in a shorter text where a doc ships one. Use them when pasting CLI output into a web-based AI tool like ChatGPT or Claude.',
         },
         {
           type: 'code',
           lang: 'bash',
-          label: 'Dense output for pasting into AI conversations',
-          code: `astryx component Dialog --dense
-astryx docs styling --dense
-astryx docs tokens --dense`,
+          label: 'Short output for pasting into AI conversations',
+          code: `astryx docs styling --full --detail brief
+astryx component Dialog --detail compact
+astryx docs principles --dense`,
         },
       ],
     },

package/authoring/config/config.doc.mjs

@@ -10,7 +10,7 @@
 export const doc = {
   type: 'schema',
   name: 'config',
-  displayName: 'Astryx Config',
+  displayName: 'astryx.config',
   namespace: 'authoring',
   description:
     'The optional astryx.config.* file at your project root. Declares which ' +
@@ -77,7 +77,7 @@ export const doc = {
           name: 'experimental.xle.components',
           type: 'Record<string, XleComponent>',
           description:
-            'No effect. Its only reader was the removed `layout` command. The key is still accepted so existing configs keep loading; delete it.',
+            'Custom components the layout expander (XLE) may emit, keyed by tag.',
         },
       ],
     },

package/authoring/config/type.ts

@@ -115,8 +115,8 @@ export interface AstryxConfig {
     /** Experimental XLE (layout expression) configuration. */
     xle?: {
       /**
-       * No effect. Its only reader was the removed `layout` command. Still
-       * accepted so existing configs keep loading; delete it.
+       * Register app-local components so XLE layout expressions can
+       * reference them by name via {hint}. Keyed by component name.
        */
       components?: Record<string, XleComponent>;
     };

package/authoring/doctypes/_schema.d.mts

@@ -216,6 +216,7 @@ export const ComponentDocKindSchema: z.ZodObject<{
     theming: z.ZodOptional<z.ZodUnknown>;
     playground: z.ZodOptional<z.ZodUnknown>;
     examples: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    replaces: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     displayName: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
@@ -316,6 +317,7 @@ export const FunctionDocKindSchema: z.ZodObject<{
 export const GenericDocKindSchema: z.ZodObject<{
     type: z.ZodLiteral<"generic">;
     title: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodString;
@@ -384,7 +386,6 @@ export const GenericDocKindSchema: z.ZodObject<{
     import: z.ZodOptional<z.ZodString>;
     group: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
-    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     parent: z.ZodOptional<z.ZodString>;
     relatedDocs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     hidden: z.ZodOptional<z.ZodBoolean>;
@@ -840,7 +841,6 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     displayName: z.ZodOptional<z.ZodString>;
     group: z.ZodOptional<z.ZodString>;
     category: z.ZodOptional<z.ZodString>;
-    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     isHiddenFromOverview: z.ZodOptional<z.ZodBoolean>;
     hidden: z.ZodOptional<z.ZodBoolean>;
     hiddenComponents: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -865,6 +865,7 @@ export const LegacyDocSchema: z.ZodUnion<readonly [z.ZodObject<{
     }>>;
     title: z.ZodString;
     description: z.ZodString;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
     sections: z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodString;

package/authoring/doctypes/_schema.mjs

@@ -307,6 +307,7 @@ const ComponentBaseSchema = z
     theming: z.unknown().optional(),
     playground: z.unknown().optional(),
     examples: z.array(z.unknown()).optional(),
+    replaces: z.string().min(1).optional(),
   })
   .passthrough();
 
@@ -414,6 +415,9 @@ export const GenericDocKindSchema = z
     ...BaseDocFields,
     type: z.literal('generic'),
     title: nonEmptyString.optional(),
+    // Search terms the title and sections do not use; `astryx search` matches
+    // them as keywords of the whole topic (ReferenceDoc `keywords`).
+    keywords: z.array(z.string()).optional(),
     sections: z.array(ReferenceSectionSchema).min(1).optional(),
     replaces: nonEmptyString.optional(),
     extends: nonEmptyString.optional(),
@@ -730,6 +734,8 @@ const LegacyBaseDocSchema = z.object({
 const LegacyReferenceDocSchema = LegacyBaseDocSchema.extend({
   title: nonEmptyString,
   description: z.string(),
+  // As on the stamped schema: search terms for the whole topic.
+  keywords: z.array(z.string()).optional(),
   sections: z.array(ReferenceSectionSchema).min(1),
   replaces: nonEmptyString.optional(),
   extends: nonEmptyString.optional(),

package/authoring/doctypes/base/graph-fields.doc.mjs

@@ -12,7 +12,7 @@ export const doc = {
   displayName: 'Authored doc graph fields',
   namespace: 'authoring',
   description:
-    "Placement, compatibility aliases, and audience: fields every authored doc kind declares for the docs tree. The docs tree reads `placement` for every guide, the CLI's and each integration's; aliases and audience are not built yet. A reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
+    "Fields every authored doc kind can declare for the docs tree: `placement`, plus two reserved fields, `aliases` and `audience`. The docs tree reads `placement` for every guide, the CLI's and each integration's. Nothing reads `aliases` or `audience` today: a reference topic outside the docs tree that sets one fails to load, and other doc kinds accept them and ignore them.",
   appliesTo: 'Every supported .doc.mjs object',
   fields: [
     {
@@ -45,13 +45,13 @@ export const doc = {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Not read yet: a topic that sets it fails to load.',
+        'Reserved: prior names or routes the docs tree will keep resolving to this doc, without creating another identity. Nothing reads it today, and a topic that sets it fails to load.',
     },
     {
       name: 'audience',
       type: "'public' | 'internal'",
       description:
-        "Which docs bundle includes this doc ('public' when omitted). Not read yet: a topic that sets it fails to load.",
+        "Reserved: which docs bundle includes this doc ('public' when omitted). Nothing reads it today, and a topic that sets it fails to load.",
       default: "'public'",
     },
   ],

package/authoring/doctypes/base/type.ts

@@ -39,9 +39,11 @@ export interface DocPlacement {
 export interface AuthoredDocGraphFields {
   /** The doc's one parent in the docs tree: a namespace of its own package. */
   placement?: DocPlacement;
-  /** Prior routes or names the docs tree will keep resolving. Not read yet. */
+  /** Reserved: prior routes or names the docs tree will keep resolving.
+   *  Nothing reads it yet. */
   aliases?: string[];
-  /** Docs bundle audience; omit for public docs. Not read yet. */
+  /** Reserved: docs bundle audience; omit for public docs. Nothing reads it
+   *  yet. */
   audience?: DocAudience;
 }
 

package/authoring/doctypes/command/command.doc.mjs

@@ -151,7 +151,7 @@ export const doc = {
       name: 'subcommands',
       type: 'string[]',
       description:
-        'Subcommand names (for command groups like `theme`).',
+        'Subcommand names (for command groups like `theme` / `layout`).',
     },
     {
       name: 'examples',

package/authoring/doctypes/command/type.ts

@@ -75,7 +75,7 @@ export interface CommandDoc extends AuthoredDocGraphFields {
   args?: CommandArgDoc[];
   /** Flags/options. */
   options?: CommandOptionDoc[];
-  /** Subcommand names (for command groups like `theme`). */
+  /** Subcommand names (for command groups like `theme` / `layout`). */
   subcommands?: string[];
   /** Terminal examples. */
   examples?: CommandExampleDoc[];

package/authoring/doctypes/component/component.doc.mjs

@@ -52,6 +52,12 @@ export const doc = {
       description:
         'Exact public package specifier consumers use to import an integration-owned component. The packed-package gate resolves this specifier and verifies it exports the component name.',
     },
+    {
+      name: 'replaces',
+      type: 'string',
+      description:
+        "Integration components only: the exact `name` of the Core ComponentDoc this component takes over for unqualified lookup, so every app that loads the integration gets it from component detail, lists, search, swizzle, and issue routing. The Core original stays reachable with `--package @astryxdesign/core`. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
+    },
     {
       name: 'keywords',
       type: 'string[]',

package/authoring/doctypes/component/type.ts

@@ -48,6 +48,14 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
   displayName: string;
   /** Exact consumer import specifier for integration-owned components. */
   import?: string;
+  /** Integration components only: the exact `name` of the Core ComponentDoc
+   *  this component takes over for unqualified lookup, so every app that loads
+   *  the integration gets this component from component detail, lists, search,
+   *  swizzle, and issue routing. The Core original stays reachable with
+   *  `--package @astryxdesign/core`. Set it only to intentionally own a Core
+   *  identity; give an alternative or variant its own name instead. Older CLIs
+   *  that do not read `replaces` keep the component under its own name. */
+  replaces?: string;
   /** Search keywords for CLI discovery. Terms a developer might type when
    *  looking for this component: synonyms, related UI concepts, and common
    *  names from other design systems (MUI, Chakra, Radix, and others).

package/authoring/doctypes/reference/reference.doc.mjs

@@ -51,6 +51,13 @@ export const doc = {
       type: 'string',
       description: "Navigation category: 'guide' or 'foundations'.",
     },
+    {
+      name: 'keywords',
+      type: 'string[]',
+      description:
+        "Words a reader may search for that the title and sections do not use: a synonym, a task, or another library's name for the same thing. `astryx search` matches each as a keyword of the whole topic, so an exact one ranks the topic like its own title does.",
+      example: "['dark mode', 'color scheme']",
+    },
     {
       name: 'replaces',
       type: 'string',

package/authoring/doctypes/reference/type.ts

@@ -127,6 +127,11 @@ export interface ReferenceDoc extends AuthoredDocGraphFields {
   description: string;
   /** Navigation category: 'guide' or 'foundations'. */
   category?: string;
+  /** Words a reader may search for that the title and sections do not use:
+   *  a synonym, a task ("dark mode"), or another library's name for the same
+   *  thing. `astryx search` matches each as a keyword of the whole topic, so
+   *  an exact one ranks the topic like its own title does. */
+  keywords?: string[];
   /** Name of an existing topic this doc takes the place of. Authored by an
    *  integration whose guide should be served instead of the built-in one —
    *  `replaces: 'getting-started'` on a doc named `getting-started` swaps the

package/authoring/doctypes/schema/schema.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
       name: 'namespace',
       type: 'string',
       description:
-        "The group that reads this doc: 'authoring' for a file an author writes (a section of `astryx docs authoring`), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+        "The group that reads this doc: 'authoring' for a file an author writes (a section of {@link generic:authoring}), or 'cli/api' for a shape the CLI returns (the docs tree adopts it by kind, as the leaf `cli/api/schemas/<name>`). Every schema doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',
@@ -162,7 +162,7 @@ export const doc = {
       type: '{ dir: string }',
       description: 'Where component sources live.',
       fields: [
-        {name: 'components.dir', type: 'string', description: 'Glob root for XDS*.tsx files.', required: true},
+        {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
       ],
     },
   ],

package/authoring/doctypes/template/template.doc.mjs

@@ -56,7 +56,7 @@ export const doc = {
       name: 'replaces',
       type: 'string',
       description:
-        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field and withhold the package's templates and doc topics.",
+        "Integration templates only: the exact id of the Core template this one replaces for unqualified lookup. Find it with `astryx --json template --list --package @astryxdesign/core`; the Core original stays selectable with `--package @astryxdesign/core`. A page replaces only a Core page and a block only a Core block. Needs @astryxdesign/cli 0.7.0 or later: earlier CLIs reject the field, drop that template, and hide the package's doc topics.",
     },
     {
       name: 'isReady',

package/authoring/doctypes/template/type.ts

@@ -33,8 +33,8 @@ export interface BaseTemplateDoc extends AuthoredDocGraphFields {
    *  replaces for unqualified lookup (find it with
    *  `astryx --json template --list --package @astryxdesign/core`). The Core
    *  original stays selectable with `--package @astryxdesign/core`. Needs
-   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field and
-   *  withhold the package's templates and doc topics. */
+   *  `@astryxdesign/cli` 0.7.0 or later: earlier CLIs reject the field,
+   *  drop that template, and hide the package's doc topics. */
   replaces?: string;
   /** Whether this template is ready for use. Templates with
    *  isReady: false show as "(WIP)" in the gallery and CLI. */

package/authoring/integration/integration.doc.mjs

@@ -23,48 +23,49 @@ export const doc = {
       name: 'providerId',
       type: 'string',
       description:
-        'Stable logical provider ID. Omit to use package.json#name; set it to the prior package name only when an explicit rename must preserve artifact IDs. If two packages claim the same ID, the package being authored is used, otherwise the first-loaded one, and the CLI warns about the other.',
+        'The name that marks this package as the source of everything it contributes. Leave it out to use the package name from package.json. Set it to the old name only during a rename, so the IDs of what the package already contributed stay the same. If two packages use the same name here, the one you are working on wins; otherwise the one the CLI reads first wins, and the CLI warns about the other.',
       example: "'@acme/widgets'",
     },
     {
       name: 'components',
       type: 'string',
       description:
-        'Relative path to the components/docs root (resolved to absolute).',
+        'The folder that holds your components and their docs, relative to package.json.',
       example: "'./src/components'",
     },
     {
       name: 'templates',
       type: 'string',
       description:
-        'Relative path to the templates root (resolved to absolute).',
+        'The folder that holds your templates, relative to package.json.',
       example: "'./src/templates'",
     },
     {
       name: 'codemods',
       type: 'string',
-      description: 'Relative path to the codemods root (resolved to absolute).',
+      description:
+        'The folder that holds your codemods, relative to package.json.',
       example: "'./codemods'",
     },
     {
       name: 'docs',
       type: 'string',
       description:
-        'Relative path to the reference-docs (topics) root (resolved to absolute). Every {topic}.doc.{ts,mjs,js} under it is served by `astryx docs` beside the built-in topics; a topic may also declare `replaces` or `extends` to take the place of a built-in one or merge onto it.',
+        'The folder that holds your doc topics, relative to package.json. Every {topic}.doc.{ts,mjs,js} in it shows up in `astryx docs` next to the built-in topics; a topic can also set `replaces` or `extends` to take over a built-in topic or add to it.',
       example: "'./docs'",
     },
     {
       name: 'themes',
       type: 'string',
       description:
-        'Relative path to a source-theme root with one directory per theme slug. Each directory contains a source module and mandatory same-stem, strongly typed .doc.mjs descriptor. Installed themes appear in `astryx theme list` and can be copied with `astryx theme add`.',
+        'The folder that holds your themes, relative to package.json, with one folder per theme. Each theme folder has the theme source and a matching .doc.mjs file with the same name. Installed themes show up in `astryx theme list` and can be copied with `astryx theme add`.',
       example: "'./themes'",
     },
     {
       name: 'agentDocs',
       type: '{ append?: readonly string[] }',
       description:
-        'Static package guidance appended to the end of the managed agent block. The CLI owns the section heading, package labels, bullets, target files, and writes.',
+        'Lines of guidance your package adds to the end of the agent instructions the CLI manages. The CLI owns the heading, labels, bullets, and which files it writes.',
       example: "{ append: ['Run acme verify.'] }",
     },
     {
@@ -94,9 +95,10 @@ export const doc = {
     {
       type: 'prose',
       text:
-        'Provider identity defaults to package.json#name. During an explicit ' +
-        'package rename, set `providerId` to the prior canonical package name so ' +
-        'existing artifact IDs remain stable. Package version always comes from package.json.',
+        'The provider name defaults to the package name in package.json. ' +
+        'During a rename, set `providerId` to the old package name so the IDs ' +
+        'of what the package already contributed stay the same. The package ' +
+        'version always comes from package.json.',
     },
     {
       type: 'prose',

package/clients/cli/command-result-coverage.test.mjs

@@ -29,17 +29,17 @@ import {program} from './index.mjs';
 import {reportsResult, reportsResultVia} from './lib/define-command.mjs';
 
 /**
- * Commands with no action of their own: a group that prints its subcommand
- * list and does nothing else has no run to report on.
+ * Commands with no action of their own: bare `astryx layout` prints its
+ * subcommand list and does nothing else, so there is no run to report on.
  *
  * Pinned as a SET rather than skipped silently — if a command joins this list,
  * that is a real change to what the CLI does and it should be read, not
- * absorbed. Every group ships an action today: `theme`, for instance, HAS one
- * — the one that rejects an unknown subcommand — so it goes through the
- * converter like any other. Its bare form prints help and never returns from
- * that action, which the recorder covers where help is recorded, not here.
+ * absorbed. (`theme` is deliberately NOT here: it HAS an action — the one that
+ * rejects an unknown subcommand — so it goes through the converter like any
+ * other. Its bare form prints help and never returns from that action, which
+ * the recorder covers where help is recorded, not here.)
  */
-const NO_ACTION_OF_THEIR_OWN = [];
+const NO_ACTION_OF_THEIR_OWN = ['layout'];
 
 /**
  * Commands that record for themselves instead of returning a descriptor.

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

@@ -37,12 +37,13 @@ export const doc = {
     {
       flag: '--list',
       param: 'options.list',
-      description: 'List all components grouped by category',
+      description: 'List every component (the same as giving no name)',
     },
     {
       flag: '--category <category>',
       param: 'options.category',
-      description: 'List components in a specific category',
+      description:
+        'List one component group, e.g. --category Layout or --category Avatar (an unknown group lists the valid ones)',
     },
     {
       flag: '--props',
@@ -79,7 +80,7 @@ export const doc = {
     },
     {
       label: 'Props table as JSON',
-      cli: 'astryx component XDSButton --props --json',
+      cli: 'astryx component Button --props --json',
     },
   ],
   exitCodes: [

package/clients/cli/commands/debug-result-summary.test.mjs

@@ -179,9 +179,9 @@ describe('DebugEvent result summary', () => {
   it(
     'says so explicitly when a command has no result set',
     async () => {
-      // Bare `integration` prints its subcommand list: nothing was looked
+      // `layout check` returns a verdict on one expression: nothing was looked
       // up, and the run says that rather than leaving four ambiguous nulls.
-      const {event} = await runWithDebug(['integration']);
+      const {event} = await runWithDebug(['layout', 'check', 'VStack>Text']);
       expect(event.output).toMatchObject({
         resultKind: 'none',
         resultCount: null,

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

@@ -47,7 +47,7 @@ export const doc = {
     {label: 'One section', cli: 'astryx docs theme quick-start'},
     {label: 'The CLI docs tree', cli: 'astryx docs cli'},
     {label: 'One API function', cli: 'astryx docs cli/api/functions/search'},
-    {label: 'A whole guide', cli: 'astryx docs cli/integrations --full'},
+    {label: 'A whole guide', cli: 'astryx docs cli/integrations/quick-start --full'},
   ],
   exitCodes: [
     {code: 0, when: 'success'},