@astryxdesign/cli 0.7.2-canary.fdd384f → 0.7.2

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/debug/parse.d.mts

@@ -44,9 +44,9 @@ declare const eventSchema: z.ZodObject<{
     args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     optionSources: z.ZodRecord<z.ZodString, z.ZodEnum<{
-        default: "default";
         cli: "cli";
         env: "env";
+        default: "default";
         config: "config";
         implied: "implied";
     }>>;
@@ -75,16 +75,16 @@ declare const eventSchema: z.ZodObject<{
         resultCount: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
         emptyResult: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
         resultKind: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
-            theme: "theme";
-            component: "component";
             command: "command";
+            none: "none";
+            component: "component";
             hook: "hook";
-            template: "template";
             doc: "doc";
+            template: "template";
+            theme: "theme";
             integration: "integration";
             migration: "migration";
             mixed: "mixed";
-            none: "none";
         }>>>;
         directMatch: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
         stdout: z.ZodString;

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 then reads the official list the CLI carries; another source\'s entry for an official package is kept. A source 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: [
@@ -135,4 +135,10 @@ export const doc = {
         '};',
     },
   ],
+  notes: [
+    {
+      type: 'prose',
+      text: "In global mode: the discover source of an integration installed for the computer is called in folders outside any project; inside a project, only the sources of integrations the project installs are. See {@link namespace:global} and {@link generic:global-integrations}.",
+    },
+  ],
 };

package/authoring/doctypes/_schema.d.mts

@@ -4,12 +4,12 @@
 /** Every authored doc-kind discriminant accepted by parseDoc. */
 export const AuthoredDocKindSchema: z.ZodEnum<{
     function: "function";
+    command: "command";
     component: "component";
     generic: "generic";
     page: "page";
     block: "block";
     schema: "schema";
-    command: "command";
     enum: "enum";
     namespace: "namespace";
 }>;
@@ -497,6 +497,11 @@ export const CommandDocKindSchema: z.ZodObject<{
         code: z.ZodNumber;
         when: z.ZodString;
     }, z.core.$loose>>>;
+    outsideProject: z.ZodOptional<z.ZodEnum<{
+        same: "same";
+        refuse: "refuse";
+        own: "own";
+    }>>;
     related: z.ZodOptional<z.ZodArray<z.ZodString>>;
     notes: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"prose">;
@@ -582,12 +587,12 @@ export const NamespaceDocKindSchema: z.ZodObject<{
         accepts: z.ZodObject<{
             kinds: z.ZodArray<z.ZodEnum<{
                 function: "function";
+                command: "command";
                 component: "component";
                 generic: "generic";
                 page: "page";
                 block: "block";
                 schema: "schema";
-                command: "command";
                 enum: "enum";
                 namespace: "namespace";
             }>>;
@@ -602,12 +607,12 @@ export const NamespaceDocKindSchema: z.ZodObject<{
             group: z.ZodString;
             kinds: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                 function: "function";
+                command: "command";
                 component: "component";
                 generic: "generic";
                 page: "page";
                 block: "block";
                 schema: "schema";
-                command: "command";
                 enum: "enum";
                 namespace: "namespace";
             }>>>;

package/authoring/doctypes/_schema.mjs

@@ -574,6 +574,7 @@ export const CommandDocKindSchema = z
     exitCodes: z
       .array(z.object({code: z.number(), when: z.string()}).passthrough())
       .optional(),
+    outsideProject: z.enum(['same', 'refuse', 'own']).optional(),
     related: z.array(z.string()).optional(),
     notes: z.array(ReferenceContentBlockSchema).optional(),
   })

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.',
         },
       ],
     },
@@ -196,6 +198,12 @@ export const doc = {
         },
       ],
     },
+    {
+      name: 'outsideProject',
+      type: "'same' | 'refuse' | 'own'",
+      description:
+        'What the command does outside a project. `same`: the answer it gives in a new project. `refuse`: it writes nothing and fails, naming the app project or integration package it needs. `own`: something else. Every `refuse` and `own` command also carries an `In global mode:` note in its `notes` that tells readers exactly what it does. Every command and subcommand declares one, and `astryx manifest` publishes it; a command that only groups subcommands declares none. The CLI tests run every command in an empty folder and check what it does against this value; `astryx doctor` does not check it.',
+    },
     {
       name: 'deprecated',
       type: 'string',
@@ -220,13 +228,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 +249,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/command/type.ts

@@ -40,6 +40,18 @@ export interface CommandOptionDoc {
   cliOnly?: boolean;
 }
 
+/**
+ * What a command does in a folder outside any project:
+ * - `same`: it gives the answer it gives in a new project, reading the Core
+ *   the answering release carries.
+ * - `refuse`: it writes nothing and fails before doing any work, naming the app
+ *   project or integration package it needs.
+ * - `own`: it does something else.
+ * Every `refuse` and `own` command also carries an `In global mode:` note
+ * in its `notes`, for readers.
+ */
+export type CommandOutsideProject = 'same' | 'refuse' | 'own';
+
 export interface CommandExampleDoc {
   label?: string;
   /** A full terminal invocation, e.g. 'astryx search button --json'. */
@@ -81,6 +93,8 @@ export interface CommandDoc extends AuthoredDocGraphFields {
   examples?: CommandExampleDoc[];
   /** Documented exit codes. */
   exitCodes?: {code: number; when: string}[];
+  /** What the command does outside a project: `same`, `refuse`, or `own`. Every command and subcommand declares one, and `astryx manifest` publishes it; a command that only groups subcommands declares none. */
+  outsideProject?: CommandOutsideProject;
   /** Deprecation notice — a DEP-* id and the replacement. */
   deprecated?: string;
   /** Related command names; the CLI links each to its doc. */

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'. 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.",
+        "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; with a lower range nothing changes and `doctor integration components` warns ({@link generic:replace-a-core-component}). 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.",
         },
       ],
     },
@@ -193,7 +193,7 @@ export const doc = {
       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

@@ -273,6 +273,14 @@ export interface ComponentRef {
  * Used by both `docsZh` (Chinese translation) and `docsDense` (compressed format).
  */
 export interface ComponentTranslationDoc {
+  /** Optional exact name from the base doc. Allowed so an overlay can say
+   *  which component it translates; the overlay renders through the base
+   *  doc, so this field is ignored at render time. */
+  name?: string;
+  /** Optional translated displayName. Allowed so the displayName backfill
+   *  codemod (which adds `displayName` next to every `name:` field) does not
+   *  break translation overlays. Ignored at render time. */
+  displayName?: string;
   /** Compressed/translated component description. */
   description?: string;
   /** Prop descriptions keyed by prop name. Only include props that have descriptions. */
@@ -338,15 +346,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.'},