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

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/base/type.ts

@@ -383,6 +383,12 @@ export interface ComponentPropDoc {
    *  ```
    */
   slotElements?: ComponentSlotElement[];
+  /** Lifecycle marker for a prop outside the stable compatibility promise
+   *  (spec:AST-017 FR21). Set `'experimental'` on a stable component's
+   *  optional `experimental` prop object, and say in `description` that its
+   *  contents may change or be removed in a patch release. Omit for stable
+   *  props. */
+  stability?: 'experimental';
 }
 
 /**

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.",
     },
   ],
 };

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

@@ -30,7 +30,7 @@ export const doc = {
       name: 'name',
       type: 'string',
       description:
-        "Stable machine identity and directory name without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
+        "Stable machine identity without the Astryx prefix, PascalCase. e.g. 'Button', 'TextInput', 'AppShell'. For an integration component it is the export apps import: the doc sits beside the file that exports it, and when that file exports nothing under its own name, `name` may name the export it does have. Change `displayName`, not `name`, to edit the visible label; registry URLs derive from this identity by default.",
       required: true,
     },
     {
@@ -56,25 +56,25 @@ export const doc = {
       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, component lists, search, `swizzle <Name>`, and issue routing; `swizzle --list` keeps listing Core names. The Core original stays reachable with `--package @astryxdesign/core`. It takes effect only when the package's peer range starts at the release that applies it, `\"@astryxdesign/cli\": \">=0.6.7\"` or later; without such a range the component keeps its own name and `doctor integration components` warns. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.",
+        '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, component lists, search, `swizzle <Name>`, and issue routing; `swizzle --list` keeps listing Core names. The Core original stays reachable with `--package @astryxdesign/core`. It takes effect only when the package\'s peer range starts at the release that applies it, `"@astryxdesign/cli": ">=0.6.7"` or later; without such a range the component keeps its own name and `doctor integration components` warns. Set it only to intentionally own a Core identity; give an alternative or variant its own name instead.',
     },
     {
       name: 'keywords',
       type: 'string[]',
       description:
-        'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, and others). Lowercase. Used by `astryx component <term>` fuzzy matching.',
+        'Search keywords for CLI discovery: synonyms and related UI concepts from other design systems (MUI, Chakra, Radix, and others). Lowercase. `astryx search` matches them; `astryx component <term>` also suggests Core components by keyword.',
     },
     {
       name: 'hiddenComponents',
       type: 'string[]',
       description:
-        'Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable; agents and tooling can still discover them via source.',
+        "Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable; agents and tooling can still discover them via source. In an integration it hides only full entries in this doc's `components`, which the CLI then neither lists nor opens; hide a sub-component that has its own doc with `hidden` in that doc.",
     },
     {
       name: 'hidden',
       type: 'boolean',
       description:
-        'Hide this entire component from human-facing UI. It stays public and importable. Use for shared primitives (NavIcon, NavMenu) that only make sense inside their parent.',
+        'Hide this entire component from human-facing UI. It stays public and importable. Use for a shared primitive that only makes sense inside its parent.',
     },
     {
       name: 'group',
@@ -98,13 +98,13 @@ export const doc = {
       name: 'theming',
       type: '{ container?: boolean; targets: ComponentThemingTarget[]; vars?: ComponentThemingVar[]; derived?: ComponentThemingDerivedVar[] }',
       description:
-        'Theming configuration: the stable selector surface (xds-* classes + data-attribute reflections) that themes target via @scope selectors in defineTheme.',
+        'Theming configuration: the stable selector surface (astryx-* classes + data-attribute reflections) that themes target via @scope selectors in defineTheme.',
       fields: [
         {
           name: 'theming.container',
           type: 'boolean',
           description:
-            'When true, container `padding` props are mapped to container tokens by the theme pipeline instead of emitting raw CSS.',
+            "Marks a container component. Nothing reads it today: the theme pipeline maps `padding` to container tokens from a `theming.derived` entry `{property: 'padding', expand: 'container'}`.",
         },
         {
           name: 'theming.targets',
@@ -122,7 +122,7 @@ export const doc = {
           name: 'theming.derived',
           type: 'ComponentThemingDerivedVar[]',
           description:
-            'Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority: earlier entries emit first.',
+            "Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority: earlier entries emit first. The pipeline reads only Core components' entries, so an integration's have no effect.",
         },
       ],
     },
@@ -181,19 +181,19 @@ export const doc = {
       name: 'props',
       type: 'ComponentPropDoc[]',
       description:
-        'SingleComponentDoc variant (required there): all public props for the one primary component. Each prop is {name, type, description, default?, required?, slotElements?}. Skip styling props like xstyle/className/style. Also present on SubComponentDoc.',
+        'SingleComponentDoc variant (required there): all public props for the one primary component. Each prop is {name, type, description, default?, required?, slotElements?, stability?}. Skip styling props like xstyle/className/style. Also present on SubComponentDoc.',
     },
     {
       name: 'components',
       type: '(ComponentEntry | ComponentRef)[]',
       description:
-        'MultiComponentDoc variant (required there): one entry per public component/hook exported from the directory. Each entry is a full ComponentEntry (inline: name, displayName, description, props | params+returns) or a name-only ComponentRef pointing at a sibling {Name}.doc.mjs.',
+        'MultiComponentDoc variant (required there): one entry per public component/hook exported from the directory. Each entry is a full ComponentEntry (inline: name, displayName, description, props | params+returns) or a name-only ComponentRef pointing at a sibling {Name}.doc.mjs. In an integration, each full entry the module named by `import` exports is a component under its own name.',
     },
     {
       name: 'subComponentOf',
       type: 'string',
       description:
-        "SubComponentDoc variant (required there): the parent component's `name` (e.g. 'Chat'). Marks this file as a sub-component doc that inherits family fields (group, category, keywords, theming, playground) from the parent.",
+        "SubComponentDoc variant (required there): the parent component's `name` (e.g. 'Chat'). Marks this file as a sub-component doc. The CLI does not copy family fields (group, category, keywords, theming, playground) from the parent to an integration's sub-component: its detail, list group and search use only what its own doc sets. Set any the child needs in its own doc.",
     },
     {
       name: 'description',
@@ -206,9 +206,10 @@ export const doc = {
     {
       label: 'SingleComponentDoc (props on the doc)',
       code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export const docs = {
-  name: 'Switch',
-  displayName: 'Switch',
+export default {
+  type: 'component',
+  name: 'AcmeSwitch',
+  displayName: 'Acme Switch',
   category: 'Form Controls',
   keywords: ['toggle', 'switch', 'on off'],
   usage: {
@@ -229,17 +230,18 @@ export const docs = {
     {
       label: 'MultiComponentDoc (a components array)',
       code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export const docs = {
-  name: 'Table',
-  displayName: 'Table',
+export default {
+  type: 'component',
+  name: 'AcmeTable',
+  displayName: 'Acme Table',
   category: 'Table & List',
   usage: {description: 'Displays rows and columns of data. Compose the sub-components to build headers, rows, and cells.'},
   components: [
-    {name: 'Table', displayName: 'Table', description: 'The table container.', props: []},
-    {name: 'TableRow', displayName: 'Table Row', description: 'A row within the table body.', props: [
+    {name: 'AcmeTable', displayName: 'Acme Table', description: 'The table container.', props: []},
+    {name: 'AcmeTableRow', displayName: 'Acme Table Row', description: 'A row within the table body.', props: [
       {name: 'isSelected', type: 'boolean', description: 'Highlights the row as selected.'},
     ]},
-    {name: 'useTableSelection', displayName: 'useTableSelection', description: 'Manages row selection state.',
+    {name: 'useAcmeTableSelection', displayName: 'useAcmeTableSelection', description: 'Manages row selection state.',
       params: [{name: 'rows', type: 'T[]', description: 'The rows to track.', required: true}],
       returns: [{name: 'selectedIds', type: 'Set<string>', description: 'Currently selected row ids.'}]},
   ],
@@ -249,7 +251,7 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: "When it loads, a stamped component doc is checked as loosely as an unstamped one, so adding `type: 'component'` to an existing doc never breaks it: `displayName` may be missing, `category` may be any string, and `usage`, `theming`, `playground` and `examples` are not checked. Each entry in a group doc's `components` must have a `name`. Write to the type anyway; it is the contract.",
+      text: "When it loads, a stamped component doc is checked about as loosely as an unstamped one, so adding `type: 'component'` to a doc that follows the type never breaks it: `displayName` may be missing, `category` may be any string, `usage`, `theming` and `playground` are not checked, and `examples` need only be an array. Unlike an unstamped doc, each entry in a group doc's `components` must have a `name`, and `import` and `replaces`, when set, must be non-empty strings. Write to the type anyway; it is the contract.",
     },
     {
       type: 'prose',
@@ -261,7 +263,7 @@ export const docs = {
       items: [
         'SingleComponentDoc: one primary component; put props directly on the doc via `props`. Use for Switch, Badge, Spinner, TextInput.',
         'MultiComponentDoc: a directory exporting several components/hooks; list them in `components` (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.',
-        'SubComponentDoc: a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It inherits family fields and may omit `usage`.',
+        "SubComponentDoc: a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It does not take the parent's family fields, and it may omit `usage`.",
       ],
     },
     {
@@ -269,11 +271,12 @@ export const docs = {
       lang: 'js',
       label: 'SubComponentDoc',
       code: `/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
-export const docs = {
-  name: 'ChatComposer',
-  displayName: 'Chat Composer',
-  subComponentOf: 'Chat',
-  description: 'The message input row within a Chat, with an editor and send affordance.',
+export default {
+  type: 'component',
+  name: 'AcmeChatComposer',
+  displayName: 'Acme Chat Composer',
+  subComponentOf: 'AcmeChat',
+  description: 'The message input row within an Acme Chat, with an editor and send affordance.',
   props: [
     {name: 'onSend', type: '(text: string) => void', description: 'Called when the user submits a message.', required: true},
   ],
@@ -281,7 +284,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      text: "The stamped format is `export default { type: 'component', ... }`; legacy docs use `export const docs = {...}` and omit `type` (the parser shape-sniffs). A hook that is part of a component API is documented as a ComponentEntry in a MultiComponentDoc `components` array (with `params`/`returns`), not as a standalone HookDoc.",
+      text: "The stamped format is `export default { type: 'component', ... }`, which `astryx integration add component` writes; legacy docs use `export const docs = {...}` and omit `type` (the parser shape-sniffs). A hook that is part of a component API is listed in a MultiComponentDoc `components` array: inline as a ComponentEntry (with `params`/`returns`), or by name with its own SubComponentDoc file, as Core's useTableSelection is.",
     },
   ],
 };

package/authoring/doctypes/component/type.ts

@@ -33,9 +33,12 @@ export interface ComponentBaseDoc extends AuthoredDocGraphFields {
   type?: 'component';
   /**
    * Stable machine identity and directory name without the Astryx prefix,
-   * PascalCase (for example `Button`, `Table`, or `AppShell`). Do not change
-   * this to edit the visible label; use `displayName` for that. Registry URLs
-   * derive from this value by default.
+   * PascalCase (for example `Button`, `Table`, or `AppShell`). For an
+   * integration component it is the export apps import: the doc sits beside
+   * the file that exports it, and when that file exports nothing under its own
+   * name, `name` may name the export it does have. Do not change this to edit
+   * the visible label; use `displayName` for that. Registry URLs derive from
+   * this value by default.
    */
   name: string;
   /** Human-readable display name with spaces between words, used by the
@@ -335,15 +338,17 @@ export interface SingleComponentDoc extends ComponentBaseDoc {
  * `subComponentOf` field, which names the parent component.
  *
  * A sub-component owns its `description`, `props`, and (optionally) its own
- * `usage`. Family-level fields (`group`, `category`, `keywords`, `theming`,
- * `playground`) are inherited from the directory's primary doc unless
- * overridden here. The generated registry entry is identical to the legacy
- * inline `components[]` expansion — this is purely a file-structure change.
+ * `usage`. The CLI does not copy family-level fields (`group`, `category`,
+ * `keywords`, `theming`, `playground`) from the parent to an integration's
+ * sub-component: its detail, list group and search use only what its own doc
+ * sets. Set any the child needs in its own doc. The generated registry entry
+ * is identical to the legacy inline `components[]` expansion — this is purely
+ * a file-structure change.
  */
 export interface SubComponentDoc extends Omit<ComponentBaseDoc, 'usage'> {
   /** Name of the parent component this sub-component belongs to, matching the
    *  parent doc's `name` (e.g. `"Chat"`). Marks this file as a sub-component
-   *  doc so the pipeline parents and inherits family fields correctly. */
+   *  doc. The CLI does not copy the parent's family fields to it. */
   subComponentOf: string;
   /** One-sentence description of what this sub-component does and its role
    *  within the parent composition. */

package/authoring/doctypes/enum/enum.doc.mjs

@@ -16,13 +16,15 @@ export const doc = {
   description:
     'The doc-type for a closed vocabulary: a fixed set of literal values such as ' +
     'error codes or response-type discriminants. Colocated as a `.doc.mjs` next to ' +
-    'the source of truth it documents.',
+    'the source of truth it documents. Only the CLI reads enum docs, from its own ' +
+    "source: one in an integration's docs directory fails to load, and so do that package's other docs.",
   appliesTo: '<enum>.doc.mjs',
   fields: [
     {
       name: 'type',
       type: "'enum'",
-      description: 'Doc-kind discriminant. Marks the file as an enum doc.',
+      description:
+        'Doc-kind discriminant. Optional in the type, but the CLI reads a doc as an enum doc only when it is set; without it the doc drops out of the docs tree.',
     },
     {
       name: 'name',
@@ -54,7 +56,8 @@ export const doc = {
     {
       name: 'aliases',
       type: 'string[]',
-      description: 'Alternate slugs that also resolve to this doc.',
+      description:
+        'Reserved: alternate slugs for this doc. Nothing reads it today, so `astryx docs <alias>` does not open it.',
     },
     {
       name: 'members',
@@ -91,7 +94,7 @@ export const doc = {
   type: 'enum',
   name: 'error-codes',
   displayName: 'Error Codes',
-  namespace: 'cli',
+  namespace: 'cli/api',
   description: 'Stable error codes thrown by the CLI/API and surfaced in the JSON envelope.',
   members: [
     {value: 'ERR_UNKNOWN_TOPIC', description: 'The requested docs topic does not exist.'},

package/authoring/doctypes/function/function.doc.mjs

@@ -18,7 +18,7 @@ export const doc = {
     'functions. A hook (HookDoc) is the hook-flavored view of this same kind; FunctionDoc ' +
     'adds the fields an API function needs (a {type, data} return envelope, thrown error ' +
     'codes, the wrapping CLI command). The CLI binding itself lives in a separate CommandDoc.',
-  appliesTo: 'api/<name>/<name>.doc.mjs',
+  appliesTo: 'api/<dir>/<name>.doc.mjs',
   fields: [
     {
       name: 'type',
@@ -41,7 +41,7 @@ export const doc = {
       name: 'kind',
       type: "'hook' | 'api'",
       description:
-        'Which flavor; drives docsite sectioning; inferred from importPath if omitted.',
+        "Which flavor. Nothing reads it today: no reader sections docs by it or infers it from `importPath`. The CLI's API function docs set 'api'.",
     },
     {
       name: 'summary',
@@ -57,12 +57,13 @@ export const doc = {
       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 API functions use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/functions/<name>`. Every function 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 API functions use 'cli/api', which the docs tree adopts by kind: each is the leaf `cli/api/functions/<name>`, the name in kebab case (`themeUse` is `theme-use`). Every function 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: 'keywords',
@@ -231,11 +232,11 @@ export const doc = {
   displayName: 'search()',
   namespace: 'cli/api',
   importPath: '@astryxdesign/cli/api',
-  summary: 'Find components, hooks, docs, and templates by term.',
+  summary: 'Find components, hooks, docs, templates, and themes by term.',
   signature: 'search(query, options?): Promise<SearchResponse>',
   params: [
     {name: 'query', type: 'string', description: 'The search term.', required: true},
-    {name: 'options.type', type: "'component' | 'hook' | 'doc' | 'template'", description: 'Restrict results to one domain.'},
+    {name: 'options.type', type: "'component' | 'hook' | 'doc' | 'template' | 'theme'", description: 'Restrict results to one domain.'},
   ],
   returns: [
     {type: 'search', description: 'Envelope with the query and ranked results[].'},
@@ -253,11 +254,11 @@ export const doc = {
   notes: [
     {
       type: 'prose',
-      text: 'When it loads, a stamped function doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+      text: '`parseDoc` accepts a stamped function doc without `displayName` and does not check its `usage`, and the CLI reads its own function docs without checking them. Write to the type anyway; it is the contract.',
     },
     {
       type: 'prose',
-      text: "The `type` discriminant is 'function' for both flavors. Set `kind: 'hook'` or `kind: 'api'` to drive docsite sectioning; it is inferred from `importPath` when omitted.",
+      text: "The `type` discriminant is 'function' for both flavors. `kind: 'hook'` or `kind: 'api'` names the flavor; nothing reads it today.",
     },
     {
       type: 'prose',

package/authoring/doctypes/hook/hook.doc.mjs

@@ -16,7 +16,8 @@ export const doc = {
     'The doc-type for a standalone React hook (e.g. useMediaQuery, useFocusTrap, ' +
     'useOverflow) that gets its own `.doc.mjs`. Hooks that are part of a component API ' +
     "(e.g. useImperativeDialog) belong in that component's MultiComponentDoc `components` " +
-    "array instead. `HookDoc` is the hook-flavored view of the shared `type: 'function'` kind.",
+    "array instead. `HookDoc` is the hook-flavored view of the shared `type: 'function'` kind. " +
+    "`astryx hook` reads Core's hook docs only; an integration lists its hooks in a component doc's `components` array.",
   appliesTo: '{useX}.doc.mjs',
   fields: [
     {
@@ -195,14 +196,14 @@ export const docs = {
     description:
       'Subscribes to a CSS media query and re-renders when it changes. Use for responsive behavior that CSS alone cannot express, such as swapping components by breakpoint.',
   },
-  relatedHooks: ['useIsMobile'],
+  relatedHooks: ['useImageMode'],
 };`,
     },
   ],
   notes: [
     {
       type: 'prose',
-      text: 'When it loads, a hook doc may leave out `displayName`, and its `usage` is not checked. Write to the type anyway; it is the contract.',
+      text: '`parseDoc` accepts a stamped hook doc without `displayName` and does not check its `usage`, and `astryx hook` prints a hook doc without checking it at all. Write to the type anyway; it is the contract.',
     },
     {
       type: 'prose',
@@ -210,7 +211,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      text: "Only standalone hooks get their own file. A hook that is part of a component API is documented as an entry in that component's MultiComponentDoc `components` array (with `params`/`returns`), so it renders under the component.",
+      text: "A hook that is part of a component API is listed in that component's MultiComponentDoc `components` array: inline with `params`/`returns`, or by name with its own SubComponentDoc file, as Core's useTableSelection is.",
     },
   ],
 };