@astryxdesign/cli 0.7.2-canary.ebcc404 → 0.7.2-canary.f2b60a0

package/assets/docs/tree/troubleshooting.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/troubleshooting`: the messages the CLI
+ * @file `astryx docs cli/integrations/help/troubleshooting`: the messages the CLI
  * prints while you build, verify, and install an integration, and the fix
  * for each.
  */
@@ -67,7 +67,7 @@ export const docs = {
           rows: [
             [
               '`component_export_missing`: `Component "AcmeCarousel" advertises import "@acme/astryx-widgets/components/AcmeCarousel", but that packed module does not export "AcmeCarousel".`',
-              "package.json has no `exports` map, or the module does not export the name. Keep `export function AcmeCarousel`, and add the entry: `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`.",
+              "package.json has no `exports` map, or the module does not export the name. Keep `export function AcmeCarousel`, and add the entry: `npm pkg set 'exports[./components/AcmeCarousel]=./components/AcmeCarousel.tsx'`. When the quoted name is a file name, such as `acme-carousel`, set the doc's `name` to the component the file exports. A type-only export does not count.",
             ],
             [
               '`template_export_missing`: `Template "acme-dashboard" public import "@acme/astryx-widgets/templates/acme-dashboard" does not have a default export.`',
@@ -103,11 +103,11 @@ export const docs = {
             ],
             [
               '`themes_need_cli`: The package ships a theme but declares no @astryxdesign/cli peer.',
-              "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.4'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`. A stable CLI before 0.6.4 cannot read typed theme descriptors, so it drops your themes and can hide your doc topics.",
+              "Run `npm pkg set 'peerDependencies.@astryxdesign/cli=>=0.6.4'` and `npm pkg set 'peerDependenciesMeta.@astryxdesign/cli.optional=true' --json`. A CLI older than published 0.6.4 cannot read typed theme descriptors, so it drops your themes and can hide your doc topics.",
             ],
             [
               '`section_ids_need_cli`: The package has a doc section that sets `id` but declares no @astryxdesign/cli peer.',
-              'The same fix as `themes_need_cli`, or drop the section `id`s: a stable CLI before 0.6.4 rejects them and hides your doc topics.',
+              'The same fix as `themes_need_cli`, or drop the section `id`s: a CLI older than published 0.6.4 rejects them and hides your doc topics.',
             ],
           ],
         },
@@ -125,6 +125,14 @@ export const docs = {
           type: 'table',
           headers: ['Symptom', 'Fix'],
           rows: [
+            [
+              '`Error: No component named "AcmeCarousel"` for a component your package documents.',
+              "Its doc still names its file. Set `name` to the export, such as `name: 'AcmeCarousel'` in `acme-carousel.doc.mjs`. A family member is listed only when the module its family doc imports exports it ({@link generic:component-family}).",
+            ],
+            [
+              '`npx astryx component Dialog` opens Core\'s `Dialog`, not yours.',
+              "A name that Core, a legacy docs package, or another package's file already has stays theirs. Run `npx astryx component Dialog --package @acme/astryx-widgets`, or give your component a name of its own.",
+            ],
             [
               '`Error: Template "dashboard" is ambiguous — narrow it with --type and/or --package.`',
               "Your template id matches a Core id. Rename it, such as `acme-dashboard`, or set `replaces: 'dashboard'` to take its place. `npx astryx doctor integration templates` warns about this before you publish.",
@@ -143,7 +151,7 @@ export const docs = {
             ],
             [
               'Your docs section, templates, or themes are missing only in some apps',
-              'Those apps run a CLI too old to read them: a stable CLI before 0.6.6 for a template that sets `keywords`, or before 0.6.4 for a template that sets `replaces`, a docs section, or a theme. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm warns about an old CLI.',
+              "Those apps run a CLI too old to read them: a stable CLI before 0.6.6 for a template that sets `keywords`, or before 0.6.4 for a template that sets `replaces`, a docs section, or a theme. Update `@astryxdesign/cli` there, and keep your optional `@astryxdesign/cli` peer so npm checks the app's CLI against it when the app installs your package.",
             ],
           ],
         },

package/assets/docs/tree/type-scale.doc.mjs

@@ -76,7 +76,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Heading for document structure',
-          code: `import {Heading} from '@astryxdesign/core';
+          code: `import {Heading} from '@astryxdesign/core/Heading';
 
 // Heading levels map to semantic tokens: level 1 → --text-heading-1-*
 <Heading level={1}>Page Title</Heading>
@@ -96,7 +96,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Text for body, label, and display text',
-          code: `import {Text} from '@astryxdesign/core';
+          code: `import {Text} from '@astryxdesign/core/Text';
 
 <Text type="body">Body text at the base scale.</Text>
 <Text type="large">Emphasized body text.</Text>
@@ -121,7 +121,7 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Customizing the type scale via defineTheme',
-          code: `import {defineTheme} from '@astryxdesign/core';
+          code: `import {defineTheme} from '@astryxdesign/core/theme';
 
 // Adjust the entire ramp holistically with base and ratio
 const editorialTheme = defineTheme({

package/assets/docs/tree/upgrading.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/upgrading`: update an integration
+ * @file `astryx docs cli/integrations/ship/upgrading`: update an integration
  * package for each Astryx release, and the command apps run to upgrade with
  * it.
  */
@@ -57,7 +57,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          code: 'Integrations: @acme/astryx-widgets\n1 codemod to run\nApplying integration codemods...\n  Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)\n[ok]     [ok] src/Hero.tsx',
+          code: 'Integrations: @acme/astryx-widgets\n<n> codemods to run\nApplying integration codemods...\n  Rename AcmeCarousel delay to interval (v0.7.0, @acme/astryx-widgets)\n[ok]     [ok] src/Hero.tsx',
         },
         {
           type: 'list',
@@ -65,7 +65,7 @@ export const docs = {
           items: [
             '`--from` is the `@astryxdesign/core` version the app had before, and the target is the installed Core.',
             '`--integration` names your package. Without it, or an `integrations` entry in `astryx.config`, the upgrade skips your codemods, even when the app has your package installed.',
-            "The count includes Core's codemods for the same versions, which run first.",
+            "`<n>` includes Core's codemods for the same versions, which run first.",
             'Put this command in your release notes.',
           ],
         },

package/assets/docs/tree/use-a-theme-in-an-app.doc.mjs

@@ -34,7 +34,9 @@ export const docs = {
           code: `import {Theme} from '@astryxdesign/core/theme';
 import {themes, defaultThemeSlug} from './astryx-themes';
 
-<Theme theme={themes[defaultThemeSlug]}>{/* app */}</Theme>`,
+<Theme theme={themes[defaultThemeSlug]}>
+  <App />
+</Theme>`,
         },
         {
           type: 'prose',

package/assets/docs/tree/verify-packed-template.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/package-and-test/verify-packed-template`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/package-and-test/verify-packed-template`:
  * what `integration verify` checks for templates, and what it leaves to the
  * app test.
  */

package/assets/docs/tree/versioning.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/versioning`: version an integration
+ * @file `astryx docs cli/integrations/ship/versioning`: version an integration
  * package, know which changes break apps, declare peer ranges, keep apps on
  * older CLIs working, and match codemod folders to versions.
  */
@@ -106,8 +106,8 @@ export const docs = {
             ],
             [
               '`@astryxdesign/cli`',
-              'You ship a docs section, a placed guide, a template that sets `replaces` or `keywords`, a doc section with an `id`, or a theme',
-              '`>=0.6.6` when you ship a template that sets `keywords`, otherwise `>=0.6.4`. Optional in `peerDependenciesMeta`',
+              'You ship a docs section, a placed guide, a template that sets `replaces` or `keywords`, a component that sets `replaces`, a doc section with an `id`, or a theme',
+              '`>=0.6.6` when you ship a template that sets `keywords`, `>=0.6.7` when a component sets `replaces`, otherwise `>=0.6.4`. Optional in `peerDependenciesMeta`',
             ],
           ],
         },
@@ -136,10 +136,11 @@ export const docs = {
           items: [
             'An unknown field in `astryx.integration.mjs` is ignored with an `unknown_manifest_key` warning, and the rest of the manifest still loads.',
             'A named export that the CLI does not know is ignored with no warning, so `debug` and `gapReport` are safe to add.',
-            'A stable CLI before 0.7.0 prints each `{@link ...}` as written.',
+            'Published 0.6.3 and earlier print each `{@link ...}` as written.',
             'Published 0.6.3 and earlier reject a template that sets `replaces` or `keywords`, drop that template, and hide every doc topic your package ships. Published 0.6.4 and 0.6.5 still drop a template that sets `keywords`.',
-            'A stable CLI before 0.6.4 cannot read a docs section, a section `id`, or a theme folder that `integration add theme` writes. It can then hide every doc topic your package ships.',
-            'Stable 0.6.3 still loads your components, but 0.6.0 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',
+            'Published 0.6.3 and earlier cannot read a docs section, a section `id`, or a theme folder that `integration add theme` writes. They can then hide every doc topic your package ships.',
+            'Published 0.6.2 and 0.6.3 still load your components, but published 0.6.0 and 0.6.1 cannot read the component docs that `integration add component` writes: `component AcmeCarousel` fails there.',
+            'An app on an older CLI lists a component whose doc names another export of its file under the file name, and lists no family members, so `component AcmeCarousel` fails there.',
           ],
         },
         {

package/assets/docs/tree/write-the-template-file.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx docs cli/integrations/templates/build-the-template/write-the-template-file`:
+ * @file `astryx docs cli/integrations/building-blocks/templates/build-the-template/write-the-template-file`:
  * what gets copied, where the copied file lands, and the imports and
  * export a copied template needs.
  */
@@ -91,8 +91,9 @@ npx astryx template acme-stat-card src/features/account/StatusCard.tsx`,
           lang: 'tsx',
           code: `import {Button} from '@astryxdesign/core/Button';
 import {Card} from '@astryxdesign/core/Card';
-import {HStack, VStack} from '@astryxdesign/core/Stack';
+import {HStack} from '@astryxdesign/core/HStack';
 import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/VStack';
 import {AcmeStatusCard} from '@acme/astryx-widgets/components/AcmeStatusCard';
 
 const metrics = [
@@ -144,7 +145,7 @@ export default function AcmeAccountSummary() {
           type: 'list',
           style: 'unordered',
           items: [
-            'Add `use client` as the first statement only when hooks, event handlers, or browser APIs need a client boundary.',
+            'Add `use client` as the first statement only when hooks, event handlers, browser APIs, or a component passed as a prop, such as `icon={BellIcon}`, need a client boundary.',
             'Keep a static template server-compatible when it needs no client behavior.',
           ],
         },

package/assets/docs/use-a-theme.doc.mjs

@@ -25,13 +25,13 @@ export const docs = {
           type: 'code',
           lang: 'tsx',
           label: 'Wire the generated module once',
-          code: "import {Theme} from '@astryxdesign/core';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n  return (\n    <Theme theme={themes[defaultThemeSlug]}>\n      <YourApp />\n    </Theme>\n  );\n}",
+          code: "import {Theme} from '@astryxdesign/core/theme';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n  return (\n    <Theme theme={themes[defaultThemeSlug]}>\n      <YourApp />\n    </Theme>\n  );\n}",
         },
         {
           type: 'code',
           lang: 'tsx',
           label: 'Switch among added themes',
-          code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
+          code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core/theme';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",
         },
         {
           type: 'prose',

package/assets/theme.template.ts

@@ -18,7 +18,7 @@
  *
  * 1. WRAP THE APP. A theme does nothing until it is provided.
  *
- *      import {Theme} from '@astryxdesign/core';
+ *      import {Theme} from '@astryxdesign/core/theme';
  *      import {myTheme} from './theme';
  *
  *      <Theme theme={myTheme} mode="system">   // 'system' | 'light' | 'dark'

package/authoring/codemod/codemod.doc.mjs

@@ -17,7 +17,8 @@ export const doc = {
     'A codemod module the CLI runs during `astryx upgrade`. Default-export a ' +
     "plain object with a `type` discriminant: 'code' rewrites source files, " +
     "'config' rewrites the astryx.config.* file. There is no factory to call.",
-  appliesTo: 'the codemods/ dir of an integration',
+  appliesTo:
+    '`<codemods>/<version>/<id>.{ts,mjs,js}` in an integration package: `<codemods>` is the codemods root of astryx.integration.*, and `<version>` is the exact @astryxdesign/core version (such as 0.7.0) whose upgrade runs the codemod. A file directly in the root never runs.',
   fields: [
     {
       name: 'title',
@@ -44,6 +45,7 @@ export const doc = {
       description:
         'File extensions this codemod applies to. Code codemods only; a ' +
         'config codemod always targets astryx.config.*.',
+      default: "['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs']",
       example: "['.tsx', '.ts']",
     },
     {
@@ -58,6 +60,7 @@ export const doc = {
           name: 'file',
           type: 'AstryxCodemodFile',
           description: 'The source file presented to the transform.',
+          required: true,
           fields: [
             {
               name: 'file.path',
@@ -77,6 +80,7 @@ export const doc = {
           name: 'api',
           type: 'AstryxCodemodApi',
           description: 'Helpers and context passed as the second argument.',
+          required: true,
           fields: [
             {
               name: 'api.jscodeshift',
@@ -89,14 +93,14 @@ export const doc = {
               name: 'api.stats',
               type: '(...args: unknown[]) => void',
               description:
-                'Report a statistic (no-op-friendly; provided for jscodeshift parity).',
+                'Accepted for jscodeshift parity. A call does nothing, and upgrade shows nothing for it.',
               required: true,
             },
             {
               name: 'api.report',
               type: '(...args: unknown[]) => void',
               description:
-                'Report progress (no-op-friendly; provided for jscodeshift parity).',
+                'Accepted for jscodeshift parity. A call does nothing, and upgrade shows nothing for it.',
               required: true,
             },
           ],

package/authoring/config/config.doc.mjs

@@ -15,8 +15,8 @@ export const doc = {
   description:
     'The optional astryx.config.* file at your project root. Declares which ' +
     'integrations to load, where to route issue links, post-codemod hooks, local ' +
-    'debug-log and gap-report handlers, and experimental layout components. All ' +
-    'optional; {} is valid.',
+    'debug-log and gap-report handlers, a discover source, and experimental ' +
+    'layout components. All optional; {} is valid.',
   appliesTo: 'astryx.config.{ts,mjs,js}',
   fields: [
     {
@@ -29,7 +29,9 @@ export const doc = {
     {
       name: 'issuesUrl',
       type: 'string',
-      description: 'URL that "report an issue" affordances link to.',
+      description:
+        "Where reports about Core go: `astryx gap-report` routes a Core report here when no handler is loaded, gapReport handlers receive it as `report.target.issuesUrl`, and `astryx swizzle` prints it as the feedback link for a Core component. A report or swizzle for an integration's component uses that integration's own issuesUrl, never this one. An absolute URL; a value that is not a URL makes the config invalid.",
+      default: "'https://github.com/facebook/astryx/issues/new'",
     },
     {
       name: 'hooks',
@@ -40,7 +42,7 @@ export const doc = {
           name: 'hooks.postCodemod',
           type: 'PostCodemodHook[]',
           description:
-            'Commands run after an upgrade applies codemods (e.g. re-run your formatter). Each hook returns a command to execute, or null to skip.',
+            'Commands to run after `astryx upgrade` changes files (e.g. re-run your formatter). Each hook is an object `{name?, buildCommand}`: buildCommand gets `{packageDir, files}` and returns `{command, args?, options?}` to run, or null to skip. A dry run prints each command instead of running it.',
         },
       ],
     },
@@ -77,7 +79,7 @@ export const doc = {
           name: 'experimental.xle.components',
           type: 'Record<string, XleComponent>',
           description:
-            'Custom components the layout expander (XLE) may emit, keyed by tag.',
+            'Custom components for the removed layout expander, keyed by component name. The CLI still validates the field, so an entry without a string `from` makes `astryx.config` invalid, but nothing reads it.',
         },
       ],
     },
@@ -90,6 +92,7 @@ export const doc = {
     {
       label: 'Send every command run somewhere of your own',
       code:
+        "import {appendFileSync} from 'node:fs';\n\n" +
         'export default {\n' +
         '  debug: event => appendFileSync("runs.ndjson", JSON.stringify(event) + "\\n"),\n' +
         '};',
@@ -98,7 +101,7 @@ export const doc = {
   notes: [
     {
       type: 'prose',
-      text: 'The config is validated at load with a strict schema: unknown keys are errors, so a typo fails fast rather than being silently ignored.',
+      text: 'The config is validated at load with a strict schema: an unknown key, a misspelled one included, or a value of the wrong type makes the whole file invalid. `astryx gap-report`, `astryx discover`, and `astryx upgrade` stop with the error, and `astryx doctor` fails its `config` check (exit 1). Reads such as `component`, `docs`, `search`, `template`, and `theme` carry on silently as if there were no config and no integrations, and no debug handler runs, so run `astryx doctor` after editing the file.',
     },
   ],
 };

package/authoring/config/type.ts

@@ -115,8 +115,10 @@ export interface AstryxConfig {
     /** Experimental XLE (layout expression) configuration. */
     xle?: {
       /**
-       * Register app-local components so XLE layout expressions can
-       * reference them by name via {hint}. Keyed by component name.
+       * Custom components for the removed layout expander, keyed by
+       * component name. The CLI still validates the field, so an entry
+       * without a string `from` makes `astryx.config` invalid, but nothing
+       * reads it.
        */
       components?: Record<string, XleComponent>;
     };

package/authoring/discover/discover.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   displayName: 'DiscoverSource',
   namespace: 'authoring',
   description:
-    'A source for `astryx discover`: an async function that returns a catalog of packages a project could add, their versions, and what each version adds. Set it as `discover` in astryx.config, or export it as `discover` from an integration manifest. Discover calls every source, the project one first, and one that throws, runs past 30 seconds, or returns an invalid catalog never hides the others; discover then uses the last good answer it saved for that source. Discover only reads: it prints the command that adds a package and never runs it.',
+    'A source for `astryx discover`: an async function that returns a catalog of packages a project could add, their versions, and what each version adds. Set it as `discover` in astryx.config, or export it as `discover` from an integration manifest. Discover calls every source, the project one first, and one that throws, runs past 30 seconds, or returns an invalid catalog never hides the others; discover then uses the last good answer that source gave for the same request, or reports the source as failed when it saved none. Discover only reads: it prints the command that adds a package and never runs it.',
   appliesTo:
     '`discover` in astryx.config.*, or the `discover` named export of astryx.integration.*',
   fields: [

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

@@ -12,14 +12,15 @@ export const doc = {
   displayName: 'Authored doc graph fields',
   namespace: 'authoring',
   description:
-    "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 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 and namespace doc, the CLI's and each integration's. Nothing reads `aliases` or `audience` today: a reference topic that sets one fails to load, placed in the docs tree or not, and other doc kinds accept them and ignore them.",
+  appliesTo:
+    "Every authored doc kind's .doc.mjs object. Theme descriptors take none of these fields.",
   fields: [
     {
       name: 'placement',
       type: 'DocPlacement',
       description:
-        "Names the doc's one parent in the docs tree: a namespace of the same package, one of its slots, and an order. Read for every guide, the CLI's and each integration's: a guide with `placement` gets a route in the tree instead of a flat topic name, and cannot also `replaces` or `extends` a topic. In the CLI's own topic directory a topic that sets it fails to load: the CLI keeps its guides in its docs tree directory. Commands, API functions, schemas, and enums do not set it: the tree adopts each by its `namespace`.",
+        "Names the doc's one parent in the docs tree: a namespace of the same package, one of its slots, and an order. Read for every guide, the CLI's and each integration's, and for every namespace doc: a guide with `placement` gets a route in the tree instead of a flat topic name, and cannot also set `replaces` or `extends`; a namespace doc with `placement` nests under that parent. In the CLI's own topic directory a topic that sets it fails to load: the CLI keeps its guides in its docs tree directory. Commands, API functions, schemas, and enums do not set it: the tree adopts each by its `namespace`.",
       fields: [
         {
           name: 'placement.parent',
@@ -37,7 +38,8 @@ export const doc = {
         {
           name: 'placement.order',
           type: 'number',
-          description: 'Integer sibling order within the slot.',
+          description:
+            "Integer sibling order within the slot. Docs without an order come after the ordered ones, sorted by title. The same order sets each doc's Previous and Next links.",
         },
       ],
     },

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

@@ -48,18 +48,20 @@ export const doc = {
     {
       name: 'description',
       type: 'string',
-      description: 'Longer help body / when-to-use.',
+      description:
+        'Longer body / when-to-use. `astryx docs` prints it after the summary; `--help` shows only the summary.',
     },
     {
       name: 'namespace',
       type: 'string',
       description:
-        "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's commands use 'cli/commands', which the docs tree adopts: each is the leaf `cli/commands/<name>`. Every command doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
+        "Optional in the type, but every doc the CLI ships declares it. The group that reads this doc. The CLI's commands use 'cli/commands', which the docs tree adopts: each is the leaf `cli/commands/<name>`, spaces as hyphens (`theme build` is `cli/commands/theme-build`). Every command doc the CLI ships declares one, and `astryx doctor` fails on one that is missing or that nothing reads.",
     },
     {
       name: 'aliases',
       type: 'string[]',
-      description: 'Alternate slugs that also resolve to this doc.',
+      description:
+        'Reserved: other names for this doc. Nothing reads it today, so they do not resolve to it.',
     },
     {
       name: 'fn',
@@ -83,13 +85,13 @@ export const doc = {
           name: 'args[].param',
           type: 'string',
           description:
-            'FunctionDoc param this arg binds to (inherits its description).',
+            "FunctionDoc param this arg binds to; `astryx docs` shows that param's description when the arg has none.",
         },
         {
           name: 'args[].description',
           type: 'string',
           description:
-            'Override description (else inherited from the referenced param).',
+            "Override description. `--help` shows an argument's description only when it sets this.",
         },
         {
           name: 'args[].required',
@@ -126,7 +128,7 @@ export const doc = {
           name: 'options[].description',
           type: 'string',
           description:
-            'Override/explicit description (required when `cliOnly`).',
+            'Override/explicit description. Nothing requires it: a flag with neither this nor `param` shows no description.',
         },
         {
           name: 'options[].choices',
@@ -143,7 +145,7 @@ export const doc = {
           name: 'options[].cliOnly',
           type: 'boolean',
           description:
-            'True for CLI-only flags with no function param (e.g. --json).',
+            'True for CLI-only flags with no function param (e.g. --verbose). Nothing reads it.',
         },
       ],
     },
@@ -220,13 +222,13 @@ export const doc = {
   type: 'command',
   name: 'search',
   displayName: 'astryx search',
-  summary: 'Find components, hooks, docs, and templates.',
-  namespace: 'cli',
+  summary: 'Find components, hooks, docs, templates, and themes.',
+  namespace: 'cli/commands',
   fn: 'search',
   args: [{name: 'query', param: 'query', required: true}],
   options: [
-    {flag: '--type <domain>', param: 'options.type', choices: ['component', 'hook', 'doc', 'template']},
-    {flag: '--json', cliOnly: true, description: 'Emit the typed JSON envelope.'},
+    {flag: '--type <domain>', param: 'options.type', choices: ['component', 'hook', 'doc', 'template', 'theme']},
+    {flag: '--verbose', cliOnly: true, description: "Also print each result's score and match reason."},
   ],
   examples: [{label: 'Terminal', cli: 'astryx search button --json'}],
   exitCodes: [{code: 1, when: 'The --type value is not a known domain.'}],
@@ -241,7 +243,7 @@ export const doc = {
     },
     {
       type: 'prose',
-      text: "Bind an arg/option to a function param via `param` so it inherits that param's description. Use `cliOnly: true` for flags with no function param (e.g. `--json`); those must supply their own `description`.",
+      text: "Bind an arg/option to a function param via `param` so it inherits that param's description: an option's in `--help` and `astryx docs`, an arg's in `astryx docs` only. Mark a flag with no function param (e.g. `--verbose`) `cliOnly: true` and give it its own `description`; nothing checks either. `--json` is a global flag, so a command doc does not declare it.",
     },
   ],
 };