@astryxdesign/cli 0.6.3-canary.4fb81b0 → 0.6.3-canary.533ecc7

package/README.md

@@ -15,6 +15,25 @@ npx @astryxdesign/cli template --list
 
 Once it's a project dependency (`npm install -D @astryxdesign/cli`), drop the scope and use the shorter `astryx` — e.g. `npx astryx component Button` or `pnpm exec astryx component Button`. Bare `astryx` resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.
 
+## Reading the CLI's own docs
+
+The CLI documents itself, so these commands print what the installed version does:
+
+- `astryx <command> --help`: one command's arguments and options.
+- `astryx manifest --json`: every command, option, and response type, as JSON.
+- `astryx docs cli`: the CLI's docs tree, one level at a time.
+  `astryx docs cli/commands` lists every command, `astryx docs cli/api` lists
+  the API's functions, schemas, and enums, and a route such as
+  `astryx docs cli/api/functions/search` prints one.
+- `astryx docs authoring --index`: the authoring reference, with one section for
+  each file an author writes: the `astryx.config.*` file, the
+  `astryx.integration.*` manifest, codemods, and every doc type (`ComponentDoc`,
+  `TemplateDoc`, `ThemeDoc`, and the rest). Read one section with
+  `astryx docs authoring <section>`, for example `astryx docs authoring config`.
+- `astryx docs cli/integrations`: the guide to building an integration package.
+- `astryx docs`: every docs topic, including the design-system guides (for
+  example `tokens`, `theme`, and `layout`).
+
 ## Finding things: `astryx search`
 
 When you don't know whether what you need is a component, a hook, a docs topic,
@@ -170,6 +189,8 @@ if (isError(result)) {
 | `ERR_UNKNOWN_FEATURE`             | An unrecognized `--features` value was passed to init.                                                                                                   |
 | `ERR_UNKNOWN_CODEMOD`             | A `--codemod` value did not match any registered codemod (upgrade).                                                                                      |
 | `ERR_CODEMOD_FAILED`              | One or more codemods failed during an upgrade run.                                                                                                       |
+| `ERR_CODEMOD_PROTECTED`           | A required codemod change remains blocked by a protected consumer file.                                                                                  |
+| `ERR_CODEMOD_PROTECTION_SOURCE`   | A working-tree protection declaration could not be read or parsed.                                                                                       |
 | `ERR_NOT_FOUND`                   | A generic discover/lookup query matched nothing in any package.                                                                                          |
 | `ERR_NO_DOC`                      | A component exists but has no typed `.doc.mjs` file.                                                                                                     |
 | `ERR_NO_SHOWCASE`                 | No showcase exists for the requested component.                                                                                                          |
@@ -179,7 +200,7 @@ if (isError(result)) {
 | `ERR_FILE_EXISTS`                 | Refused to overwrite an existing file.                                                                                                                   |
 | `ERR_PATH_TRAVERSAL`              | A path escaped its allowed root, or a name contained traversal markers.                                                                                  |
 | `ERR_WRITE_FAILED`                | Writing output files failed (and was rolled back).                                                                                                       |
-| `ERR_THEME_INVALID`               | A theme definition or contributed theme catalog is invalid.                                                                                              |
+| `ERR_THEME_INVALID`               | A theme definition or contributed theme descriptor is invalid.                                                                                           |
 | `ERR_THEME_LOAD`                  | A theme file could not be loaded / parsed into a defineTheme result.                                                                                     |
 | `ERR_PALETTE_GENERATION`          | A palette generation request or one of its constraints was invalid.                                                                                      |
 | `ERR_VERSION_DETECT`              | The current `@astryxdesign/core` version could not be detected.                                                                                          |
@@ -407,24 +428,25 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `component.detail.source`         | One component's source file, as {component, source}.                                                                                                                                                                                                                                                                                                                                                                                       |
 | `component.detail.showcase`       | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                                                                                                                                                                                                                     |
 | `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                                                                                                                                                                                                                 |
-| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                                                                                                                                                                                                                                    |
-| `docs.detail`                     | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                                                                                                                                                                                                                              |
-| `docs.index`                      | One topic's section index (--index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary).                                                                                                                                                                                                                                  |
-| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined.                                                                                                                                                                                                                                                                                                                                                     |
+| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load.                                                                                                                                                                                                                |
+| `docs.detail`                     | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                                                                                                                                             |
+| `docs.index`                      | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                  |
+| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it).                                                                                                                                                                                                                                     |
+| `docs.node`                       | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names).                                                                                                                           |
 | `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                                                                                                                                                                   |
 | `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                                                                                                                                                                  |
 | `discover.list`                   | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                                                                                                                                                                         |
 | `discover.detail`                 | A single external package entry, for an @scope/name query.                                                                                                                                                                                                                                                                                                                                                                                 |
 | `discover.detail.doc`             | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                                                                                                                                                                                                                             |
 | `discover.search`                 | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                                                                                                                                                                                                                           |
-| `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title (docs), or displayName and kind (templates).                                                                                                                                                                |
+| `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates).                                        |
 | `build.help`                      | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.                                                                                                                                                              |
 | `build.kit`                       | The composition kit: echoed query, hasResults, matchCount (total matched, never a cap), directMatch, pages (closest templates), blocks (drop-in patterns) and domain (idea components/hooks) as SearchResultEntry[], frame and foundation name arrays, and hint {reason, commands} when thin.                                                                                                                                              |
 | `swizzle.list`                    | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                                                                                                                                                                                                                             |
 | `swizzle.copy`                    | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                                                                                                                                                                                                                             |
 | `gap-report.categories`           | The fixed gap category values and human-readable labels.                                                                                                                                                                                                                                                                                                                                                                                   |
 | `gap-report.file`                 | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.                                                                                                                                                                                      |
-| `template.list`                   | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.                                                                                                                                                                                                                                                                       |
+| `template.list`                   | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list.                                                                                                                                                                                                                                                             |
 | `template.show`                   | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                                                                                                                                                                                                        |
 | `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                                                                                                                                                                                                               |
 | `template.copy`                   | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                                                                                                                                                                                                                      |
@@ -448,9 +470,9 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `integration.add`                 | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun.                                                                                                                                                                                                                                                                            |
 | `integration.pack-check`          | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}]. |
 | `integration.validate`            | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                   |
-| `integration.template-conflicts`  | The integration identity, structural issues, and non-blocking conflicts where an integration template id is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                |
+| `integration.template-conflicts`  | The integration identity, issues, and conflicts as {severity: info \| warning, relationship: replaces \| accidental, replaces?, command}.                                                                                                                                                                                                                                                                                                  |
 | `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                             |
-| `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps classified as intentional replacements, intentional extensions, or accidental same-name conflicts.                                                                                                                                                                                                                                                                      |
+| `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                     |
 | `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).                                                                                                                                                                                                       |
 | `layout.check`                    | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                                                                                                                                                                                                                   |
 | `layout.grammar`                  | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                                                                                                                                                                                                        |
@@ -646,9 +668,10 @@ wrong type fails there; a field this CLI does not know is ignored with a
 warning naming it, so a manifest written against a newer CLI still contributes
 everything this one understands.
 
-Discovery is resilient: a broken or misconfigured integration is skipped with a
-one-line warning on stderr instead of crashing the CLI, and it never corrupts a
-`--json` envelope. To inspect problems, run
+Discovery is resilient. A manifest load failure skips that package with a warning.
+An invalid contribution kind remains reportable without hiding other valid kinds,
+and invalid template or component metadata is omitted without hiding valid siblings.
+Warnings go to stderr and never corrupt a `--json` envelope. To inspect problems, run
 `astryx doctor integration validate <package>` for structure, then use `templates`,
 `components`, or `docs` under the same `astryx doctor integration` group to check
 Core identity overlaps before publishing. Bare `astryx doctor` checks overall
@@ -658,5 +681,5 @@ For the full authoring walkthrough (component doc format, template packaging
 and `exports` requirements, and codemod authoring), see the guide:
 
 ```bash
-astryx docs cli-integrations
+astryx docs cli/integrations
 ```

package/api/blog/blog.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'blog',
+  namespace: 'cli/api',
   displayName: 'blog()',
   summary: 'List blog posts, or read one, from the published RSS feed.',
   description:

package/api/build/build.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'build',
+  namespace: 'cli/api',
   displayName: 'build()',
   summary:
     'Page-building assistant: the how-to-build playbook, or a composition kit for an idea.',

package/api/component/_adapter.d.mts

@@ -2,9 +2,8 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
- * which is either a single-component or multi-component doc; this loose view
- * captures the fields the API reads across both forms.
+ * A loaded component doc. The shared validated loader accepts stamped and legacy
+ * component docs; this loose view captures the fields the API reads across both.
  * @typedef {object} LoadedComponentDoc
  * @property {string} [name]
  * @property {string} [description]
@@ -15,9 +14,7 @@
  * @property {string} [import] set when the doc states its own import specifier
  */
 /**
- * Options object for `loadDocs`, matching its declared parameter shape (used
- * as a cast target so `lang` (which the API may hold as `string|null`) type
- * checks against `loadDocs`'s `lang?: string`).
+ * Options object for the shared component-doc loader.
  * @typedef {{zh?: boolean, dense?: boolean, lang?: string}} LoadDocsOpts
  */
 /**
@@ -184,9 +181,8 @@ export function scopeSubComponent(docs: LoadedComponentDoc, dirName: string, cor
 } | null;
 export { CORE_PACKAGE };
 /**
- * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
- * which is either a single-component or multi-component doc; this loose view
- * captures the fields the API reads across both forms.
+ * A loaded component doc. The shared validated loader accepts stamped and legacy
+ * component docs; this loose view captures the fields the API reads across both.
  */
 export type LoadedComponentDoc = {
     name?: string | undefined;
@@ -203,9 +199,7 @@ export type LoadedComponentDoc = {
     import?: string | undefined;
 };
 /**
- * Options object for `loadDocs`, matching its declared parameter shape (used
- * as a cast target so `lang` (which the API may hold as `string|null`) type
- * checks against `loadDocs`'s `lang?: string`).
+ * Options object for the shared component-doc loader.
  */
 export type LoadDocsOpts = {
     zh?: boolean;

package/api/component/_adapter.mjs

@@ -35,16 +35,15 @@ import {
   resolveIntegrationImportPath as resolveIntegrationImport,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {Project} from '../../foundation/config/project.mjs';
-import {loadDocs} from '../../foundation/discovery/component-loader.mjs';
+import {loadComponentDoc as loadValidatedComponentDoc} from '../../foundation/discovery/component-loader.mjs';
 import {searchComponents} from '../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../error.mjs';
 
 export {CORE_PACKAGE};
 
 /**
- * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
- * which is either a single-component or multi-component doc; this loose view
- * captures the fields the API reads across both forms.
+ * A loaded component doc. The shared validated loader accepts stamped and legacy
+ * component docs; this loose view captures the fields the API reads across both.
  * @typedef {object} LoadedComponentDoc
  * @property {string} [name]
  * @property {string} [description]
@@ -56,9 +55,7 @@ export {CORE_PACKAGE};
  */
 
 /**
- * Options object for `loadDocs`, matching its declared parameter shape (used
- * as a cast target so `lang` (which the API may hold as `string|null`) type
- * checks against `loadDocs`'s `lang?: string`).
+ * Options object for the shared component-doc loader.
  * @typedef {{zh?: boolean, dense?: boolean, lang?: string}} LoadDocsOpts
  */
 
@@ -381,9 +378,22 @@ export async function resolveUnscopedDoc(dirName, {coreDir, cwd, name}) {
  */
 export async function loadComponentDoc(docPath, opts = {}) {
   const {zh = false, dense = false, lang = null} = opts;
-  return /** @type {LoadedComponentDoc} */ (
-    await loadDocs(docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang}))
-  );
+  try {
+    return /** @type {LoadedComponentDoc} */ (
+      await loadValidatedComponentDoc(
+        docPath,
+        /** @type {LoadDocsOpts} */ ({zh, dense, lang}),
+      )
+    );
+  } catch (err) {
+    throw new AstryxError(
+      `Cannot load component metadata: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_DOC,
+    );
+  }
 }
 
 /**

package/api/component/component.doc.mjs

@@ -12,6 +12,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'component',
+  namespace: 'cli/api',
   displayName: 'component()',
   summary:
     'Resolve a component by name, or list the catalog, with optional focused slices (props, source, showcase, blocks).',
@@ -109,7 +110,7 @@ export const doc = {
     {
       type: 'component.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integrations; brief entries; or full ComponentDoc entries.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
     },
     {
       type: 'component.detail',

package/api/component/component.mjs

@@ -143,14 +143,20 @@ export async function component(name, options = {}) {
   // Searches that package first — critical for names that exist in both core
   // and an external package (AppShell, Button, SideNav).
   if (packageScope) {
-    const scoped = classifyScope(packageScope, {owners, loadedIntegrations, cwd, name});
+    const scoped = classifyScope(packageScope, {
+      owners,
+      loadedIntegrations,
+      cwd,
+      name,
+    });
 
     if (scoped.kind === 'core' || scoped.kind === 'integration') {
       const owner = scoped.owner;
       if (source) {
         return componentDetailSource(dirName, owner.sourcePath, {
           name,
-          notFoundInPackage: scoped.kind === 'integration' ? packageScope : null,
+          notFoundInPackage:
+            scoped.kind === 'integration' ? packageScope : null,
         });
       }
       // showcase/blocks were previously dropped on the scoped path — a
@@ -187,17 +193,48 @@ export async function component(name, options = {}) {
       }
       const docs = await loadComponentDoc(extDocPath, docOpts);
       if (props) return componentDetailProps(docs);
-      return componentDetail(docs, {package: scoped.ext.name, sourcePath: null}, dirName, coreDir);
+      return componentDetail(
+        docs,
+        {package: scoped.ext.name, sourcePath: null},
+        dirName,
+        coreDir,
+      );
+    }
+    throw new AstryxError(
+      `No component "${name}" in package "${packageScope}"`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
+  // Invalid integration metadata does not create ambiguity against a valid
+  // owner. Keep raw owners only when no doc owner is valid, so an integration-
+  // only component still exposes its source and returns ERR_INVALID_DOC for
+  // detail instead of degrading to an unrelated unknown-component error.
+  const validOwners = [];
+  for (const owner of owners) {
+    if (owner.package === CORE_PACKAGE) {
+      validOwners.push(owner);
+      continue;
+    }
+    try {
+      await loadComponentDoc(owner.docPath);
+      validOwners.push(owner);
+    } catch {
+      // Project/Doctor report invalid metadata; it is not an effective owner.
     }
-    throw new AstryxError(`No component "${name}" in package "${packageScope}"`, undefined, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
   }
+  const effectiveOwners = validOwners.length > 0 ? validOwners : owners;
 
-  // ── Ambiguity: owned by MORE THAN ONE package, no --package ─────
-  assertUnambiguousOwners(owners, dirName);
+  // ── Ambiguity: owned by MORE THAN ONE valid package, no --package ──
+  assertUnambiguousOwners(effectiveOwners, dirName);
 
   // ── Single non-core owner (an integration provides it, core does not) ──
-  if (owners.length === 1 && owners[0].package !== CORE_PACKAGE) {
-    const owner = owners[0];
+  if (
+    effectiveOwners.length === 1 &&
+    effectiveOwners[0].package !== CORE_PACKAGE
+  ) {
+    const owner = effectiveOwners[0];
     if (source) {
       return componentDetailSource(dirName, owner.sourcePath, {name});
     }
@@ -213,7 +250,11 @@ export async function component(name, options = {}) {
   // ── No-scope core path ─────────────────────────────────────────
   // `--source` reads core directly (no external/fuzzy fallback).
   if (source) {
-    return componentDetailSource(dirName, resolveCoreSourcePath(coreDir, dirName), {name});
+    return componentDetailSource(
+      dirName,
+      resolveCoreSourcePath(coreDir, dirName),
+      {name},
+    );
   }
   if (showcase) {
     return componentDetailShowcase(dirName, {cwd, name});
@@ -232,10 +273,14 @@ export async function component(name, options = {}) {
   // scope the response to just the matching sub-component.
   const sub = scopeSubComponent(docs, dirName, coreDir);
   if (sub) {
-    if (props) return componentDetailProps({props: sub.matchingComponent.props});
+    if (props)
+      return componentDetailProps({props: sub.matchingComponent.props});
     return componentDetail(
       sub.scoped,
-      {package: resolved.resolvedOwnerPackage, sourcePath: resolved.resolvedSourcePath},
+      {
+        package: resolved.resolvedOwnerPackage,
+        sourcePath: resolved.resolvedSourcePath,
+      },
       dirName,
       coreDir,
     );
@@ -244,7 +289,10 @@ export async function component(name, options = {}) {
   if (props) return componentDetailProps(docs);
   return componentDetail(
     docs,
-    {package: resolved.resolvedOwnerPackage, sourcePath: resolved.resolvedSourcePath},
+    {
+      package: resolved.resolvedOwnerPackage,
+      sourcePath: resolved.resolvedSourcePath,
+    },
     resolved.resolvedName,
     coreDir,
   );

package/api/component/component.type.d.mts

@@ -31,9 +31,10 @@ export type ComponentListData = ({
 /**
  * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the
  * list moved from bare strings to package-qualified objects so consumers can
- * disambiguate ownership (core vs. an integration package). Integration entries
- * carry `import` — the package-authored specifier; core entries omit it (the
- * specifier is derived from the component name by the renderer).
+ * disambiguate ownership (core vs. an integration package). Integration and
+ * legacy `astryx.docs` package entries carry `import` — the same specifier their
+ * `component.detail` reports; core entries omit it (the specifier is derived
+ * from the component name by the renderer).
  */
 export type ComponentListEntry = {
     name: string;
@@ -42,7 +43,7 @@ export type ComponentListEntry = {
      */
     package: string;
     /**
-     * - Import specifier; present for integration components, absent for core.
+     * - Import specifier; present for integration and legacy package components, absent for core.
      */
     import?: string | undefined;
 };

package/api/component/component.type.mjs

@@ -52,13 +52,14 @@
 /**
  * A single entry in a `component.list` group at `detail: 'names'`. Pre-1.0 the
  * list moved from bare strings to package-qualified objects so consumers can
- * disambiguate ownership (core vs. an integration package). Integration entries
- * carry `import` — the package-authored specifier; core entries omit it (the
- * specifier is derived from the component name by the renderer).
+ * disambiguate ownership (core vs. an integration package). Integration and
+ * legacy `astryx.docs` package entries carry `import` — the same specifier their
+ * `component.detail` reports; core entries omit it (the specifier is derived
+ * from the component name by the renderer).
  * @typedef {object} ComponentListEntry
  * @property {string} name
  * @property {string} package - Owner package, e.g. '@astryxdesign/core' or '@acme/astryx-meta'.
- * @property {string} [import] - Import specifier; present for integration components, absent for core.
+ * @property {string} [import] - Import specifier; present for integration and legacy package components, absent for core.
  */
 
 /**

package/api/component/list/list.d.mts

@@ -1,11 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
- * @typedef {import('../component.type.mjs').ComponentListEntry} ComponentListEntry
- * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
- */
 /**
  * Build the `component.list` envelope. The list taxonomy is collapsed: all
  * three detail levels emit ONE `component.list` type; the depth rides in

package/api/component/list/list.mjs

@@ -15,15 +15,16 @@ import {
   CORE_PACKAGE,
   discoverComponents,
   discoverExternalComponentsGrouped,
-  discoverIntegrationComponents,
+  discoverValidIntegrationComponents,
   findComponentReadme,
+  findExternalComponentDoc,
   resolveImportPath,
   resolveIntegrationImportPath,
 } from '../../../foundation/discovery/component-discovery.mjs';
 import {discoverExternalPackages} from '../../../foundation/fs/paths.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError} from '../../error.mjs';
-import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
+import {loadComponentDoc, loadIntegrationsSafely, withOwnership} from '../_adapter.mjs';
 
 /**
  * @typedef {import('../component.type.mjs').ComponentListResponse} ComponentListResponse
@@ -31,6 +32,29 @@ import {loadComponentDoc, loadIntegrationsSafely} from '../_adapter.mjs';
  * @typedef {import('../component.type.mjs').ComponentBriefEntry} ComponentBriefEntry
  */
 
+/**
+ * The import a legacy `pkg.astryx.docs` component's detail reports, derived the
+ * same way (`withOwnership`) so list and detail agree.
+ * @param {{name: string, docsDir: string}} ext
+ * @param {string} name
+ * @param {string} coreDir
+ * @param {{zh: boolean, lang: string|null}} docOpts
+ * @returns {Promise<string>}
+ */
+async function legacyImport(ext, name, coreDir, docOpts) {
+  const docPath = findExternalComponentDoc(ext.docsDir, name);
+  /** @type {import('../_adapter.mjs').LoadedComponentDoc} */
+  let docs = {};
+  if (docPath && docPath.endsWith('.doc.mjs')) {
+    try {
+      docs = await loadComponentDoc(docPath, docOpts);
+    } catch {
+      // Keep list resilient; validation owns malformed docs.
+    }
+  }
+  return withOwnership(docs, {package: ext.name, sourcePath: null}, name, coreDir).import;
+}
+
 /**
  * Build the `component.list` envelope. The list taxonomy is collapsed: all
  * three detail levels emit ONE `component.list` type; the depth rides in
@@ -204,7 +228,8 @@ export async function componentList(
   const seenIntegration = new Set();
   for (const integration of loadedIntegrations) {
     seenIntegration.add(integration.name);
-    const owned = discoverIntegrationComponents(integration);
+    const {components: owned} =
+      await discoverValidIntegrationComponents(integration);
     // Group integration components by their doc `group`, falling back to the
     // package name. Keys are package-qualified so they never collide with
     // core groups or each other.
@@ -267,20 +292,24 @@ export async function componentList(
       k => grouped[k].length > 1 || grouped[k][0] !== k,
     );
 
-    if (hasGroups) {
-      for (const [group, members] of Object.entries(grouped)) {
-        listData[`${group} (${ext.name})`] = members.map(n => ({
+    /** @param {string[]} names */
+    const entriesFor = names =>
+      Promise.all(
+        names.map(async n => ({
           name: n,
           package: ext.name,
-        }));
+          import: await legacyImport(ext, n, coreDir, {zh, lang}),
+        })),
+      );
+
+    if (hasGroups) {
+      for (const [group, members] of Object.entries(grouped)) {
+        listData[`${group} (${ext.name})`] = await entriesFor(members);
       }
     } else {
       const allComps = Object.values(grouped).flat().sort();
       if (allComps.length > 0) {
-        listData[`${ext.category} (${ext.name})`] = allComps.map(n => ({
-          name: n,
-          package: ext.name,
-        }));
+        listData[`${ext.category} (${ext.name})`] = await entriesFor(allComps);
       }
     }
   }

package/api/discover/discover.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'discover',
+  namespace: 'cli/api',
   displayName: 'discover()',
   summary: 'Browse and search components from configured external packages.',
   description: