@astryxdesign/cli 0.7.2-canary.e2909cf → 0.7.2-canary.e4bdd70

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,
     },
     {
@@ -62,19 +62,19 @@ export const doc = {
       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.",
         },
       ],
     },
@@ -187,13 +187,13 @@ export const doc = {
       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.",
     },
   ],
 };

package/authoring/doctypes/namespace/namespace.doc.mjs

@@ -55,7 +55,8 @@ export const doc = {
     {
       name: 'audience',
       type: "'public' | 'internal'",
-      description: "Bundle audience. Defaults to 'public'.",
+      description:
+        "Reserved: bundle audience. Nothing reads it yet: a namespace that sets 'internal' still shows in `astryx docs`.",
       default: "'public'",
     },
     {
@@ -67,7 +68,7 @@ export const doc = {
       name: 'slots',
       type: 'Record<string, NamespaceSlot>',
       description:
-        'Named placement and collection targets. Each slot declares a title and accepted doc kinds; configured providers require an explicit extension slot.',
+        "Named placement and collection targets. Each slot declares a title and the doc kinds it accepts. `accepts.providers` is not read yet: only docs of the namespace's own package can be placed in a slot.",
       required: true,
     },
     {
@@ -80,7 +81,7 @@ export const doc = {
       name: 'blocks',
       type: '(ReferenceContentBlock | GraphContentBlock)[]',
       description:
-        'Ordered layout content for the namespace page. Graph-only workflow, collection, and reference blocks are available here without widening the stable ReferenceContentBlock union used by existing topic renderers. Not rendered yet: `astryx docs <route>` lists every slot and its children in order.',
+        'Ordered layout content for the namespace page. Graph-only workflow, collection, and reference blocks are available here without widening the stable ReferenceContentBlock union used by existing topic renderers. `astryx docs <route>` prints the prose, heading, code, table, and list blocks above the slots, and `--json` returns every block with its links resolved. A collection block is not rendered yet, and `astryx doctor` warns on one.',
     },
   ],
   examples: [
@@ -100,7 +101,7 @@ export const docs = {
     },
   },
   adopts: [{
-    source: {group: 'cli-commands', kinds: ['command']},
+    source: {group: 'cli/commands', kinds: ['command']},
     into: 'reference',
   }],
 };`,
@@ -109,11 +110,11 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: "The docs tree reads namespace docs from the CLI and from every configured integration. An integration's namespace doc is a top-level level of the tree, and its guides name it with `placement`; a doc can be placed only in a namespace of its own package. When two packages claim one route, the CLI's own docs win, then integrations in configured order, and `astryx doctor` names the loser.",
+      text: "The docs tree reads namespace docs from the CLI and from every configured integration. An integration's namespace doc without a `placement` is a top-level level of the tree, and its guides name it with `placement`; a doc can be placed only in a namespace of its own package. When two packages claim one route, the CLI's own docs win, then integrations in configured order, and `astryx doctor` names the loser.",
     },
     {
       type: 'prose',
-      text: 'Child docs request one canonical home with placement. Collections store and render stable references to those docs; they never create a second identity or parent.',
+      text: 'Child docs request one canonical home with placement. A collection block refers to those docs by stable reference and never creates a second identity or parent. It is not rendered yet: `astryx doctor` warns on one.',
     },
     {
       type: 'list',

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

@@ -18,7 +18,8 @@ export const doc = {
     'accessibility, migration guides. Unlike ComponentDoc it is not tied to a component: ' +
     'drop a `.doc.mjs` in the docs directory and it shows up in `astryx docs`. Content is ' +
     'built from ordered sections of mixed content blocks.',
-  appliesTo: 'assets/docs/<topic>.doc.mjs',
+  appliesTo:
+    "<topic>.doc.{ts,mjs,js} in the folder the integration manifest's `docs` names",
   fields: [
     {
       name: 'type',
@@ -69,7 +70,7 @@ export const doc = {
       name: 'extends',
       type: 'string',
       description:
-        "Name of an existing topic this doc merges onto, section by section: a section whose title matches one in the base replaces it, a section the base does not have is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
+        "Name of an existing topic this doc merges onto, section by section. A section replaces the base section with the same `id`, or else the one with exactly its title when either of the two has no `id`. A key derived from a title counts only against an `id`: a section without an `id` also matches a base section whose `id` is the key its title derives, and a section with an `id` also matches a base section without one whose title derives that `id`. Two different `id`s never match, two sections without an `id` whose titles differ only in case or punctuation stay separate, and a section that matches none is appended. The topic keeps the base's title and description. For correcting or adding to a topic rather than owning it. Exclusive with `replaces`.",
       example: "'theme'",
     },
     {
@@ -83,7 +84,7 @@ export const doc = {
           name: 'sections[].id',
           type: 'string',
           description:
-            'Stable section anchor. New docs should set this instead of relying on a mutable title.',
+            'Stable section anchor. New docs should set this instead of relying on a mutable title. Published @astryxdesign/cli 0.6.3 and earlier reject the field and hide every doc topic the package ships, so `astryx integration verify` fails an integration that sets one until it declares an `@astryxdesign/cli` peer of `>=0.6.4`.',
         },
         {
           name: 'sections[].title',
@@ -109,7 +110,7 @@ export const doc = {
           name: 'sections[].previewType',
           type: 'ReferenceTokenPreviewType',
           description:
-            "Preview type for token tables in this section. When set, the docsite renders a visual preview column from the token's computed value. Omit for non-token sections.",
+            'Preview type for token tables in this section. The CLI rejects a value not in the list below and returns the value in `astryx docs --json`, but draws no preview from it. Omit for non-token sections.',
         },
       ],
     },
@@ -117,17 +118,17 @@ export const doc = {
       name: 'tokenCategory',
       type: 'string',
       description:
-        "Token category for foundational docs that map to a token section (e.g. 'color'). Lets the tokens overview link to this doc for detailed guidance.",
+        "Token category for foundational docs that map to a token section (e.g. 'color'). `astryx docs --json` returns it as authored; no tokens page links to the doc through it.",
     },
   ],
   examples: [
     {
       label: 'A reference doc with one section',
       code: `/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
-export const docs = {
+export default {
   type: 'generic',
-  name: 'spacing',
-  title: 'Spacing',
+  name: 'acme-spacing',
+  title: 'Acme Spacing',
   description: 'Spacing tokens for gap, margin, and padding.',
   category: 'foundations',
   tokenCategory: 'spacing',
@@ -194,7 +195,7 @@ type ReferenceDocBlock = {
 
 type GraphContentBlock =
   | { type: 'workflow'; title?: string; steps: WorkflowStep[] }
-  | { type: 'collection'; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
+  | { type: 'collection'; title?: string; source: {slot: string}; presentation?: 'list' | 'cards' | 'compact'; whenEmpty?: 'show' | 'omit' }
   | ReferenceDocBlock;`,
     },
     {
@@ -203,7 +204,7 @@ type GraphContentBlock =
     },
     {
       type: 'prose',
-      text: "A section may set `previewType` to render a visual preview column for token tables: one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
+      text: "A section may set `previewType`, a hint for previewing its token table, to one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'; the CLI rejects any other value.",
     },
   ],
 };

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

@@ -55,7 +55,7 @@ export const doc = {
       name: 'aliases',
       type: 'string[]',
       description:
-        'Alternate slugs that also resolve to this doc (back-compat).',
+        'Reserved: alternate slugs for this doc. Nothing reads it yet: `astryx docs` finds a schema doc by its `name` only.',
     },
     {
       name: 'appliesTo',
@@ -141,7 +141,7 @@ export const doc = {
       name: 'notes',
       type: 'ReferenceContentBlock[]',
       description:
-        'Freeform prose/notes rendered after the field table. Same block union as ReferenceDoc (prose, heading, code, table, list, token-ref).',
+        'Freeform prose/notes rendered after the field table and examples. The stable ReferenceContentBlock union (prose, heading, code, table, list, token-ref), without the reference block a ReferenceDoc section also takes; a token-ref note is accepted but not rendered.',
     },
   ],
   examples: [
@@ -152,17 +152,17 @@ export const doc = {
   type: 'schema',
   name: 'integration',
   displayName: 'Astryx Integration',
-  namespace: 'cli',
-  description: 'The astryx.integration.* manifest that registers the components a package provides.',
+  namespace: 'authoring',
+  description: 'The astryx.integration.* manifest that points the CLI at what a package contributes.',
   appliesTo: 'astryx.integration.{ts,mjs,js}',
   fields: [
-    {name: 'name', type: 'string', description: 'Package name.', required: true},
+    {name: 'docs', type: 'string', description: 'The folder that holds your doc topics, relative to package.json.'},
     {
-      name: 'components',
-      type: '{ dir: string }',
-      description: 'Where component sources live.',
+      name: 'agentDocs',
+      type: '{ append?: readonly string[] }',
+      description: 'Guidance your package adds to the agent instructions the CLI manages.',
       fields: [
-        {name: 'components.dir', type: 'string', description: 'Glob root for Acme*.tsx files.', required: true},
+        {name: 'agentDocs.append', type: 'readonly string[]', description: 'Lines added at the end, at most eight.'},
       ],
     },
   ],

package/authoring/doctypes/template/integration-template.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the `IntegrationTemplateDoc` doc-type — the template
+ * metadata an integration package ships: TemplateDoc, with the package's own
+ * `category`. Colocated with the type it describes (`type.ts`).
+ * @position packages/cli/authoring/doctypes/template — doc-type documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;