@astryxdesign/cli 0.7.2-canary.ccf1a1c → 0.7.2-canary.d216097

package/README.md

@@ -437,7 +437,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `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, each naming its package) 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 integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                                                                                                                                                                                                                                                                      |
+| `discover.list`                   | What the project has, the integrations it loads and the official packages it declares, official packages first (name, category, components, version, a list per other kind they add, and latest when a source knows it); meta.available lists what the project could add, the official packages first, each with the command that adds it, and meta.sources reports each source, the official list last; when it lists no integration it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                                                                                                      |
 | `discover.detail`                 | One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `discover.detail.doc`             | The validated ComponentDoc for one installed component, for an @scope/name/Component query.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `discover.item`                   | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
@@ -447,8 +447,8 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `build.kit`                       | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, package, command, basis, reason, alternatives, ...} (the start and each alternative name the package that owns the template), pages (search's closest templates), blocks and domain as SearchResultEntry[] (each naming its package), frame and foundation (Core component names), and hint {reason, commands} when thin.                                                                                                                                                                                                                                                                      |
 | `swizzle.list`                    | The names of swizzlable components discoverable from cwd's @astryxdesign/core. The envelope's package is @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, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling. The envelope's package names the same owning package.                                                                                                                                                                                                                                                                                                                                                                                 |
-| `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `gap-report.categories`           | The fixed gap category values and human-readable labels; when a loaded integration names its own issues URL, meta.destinations lists every destination ({to, default, issuesUrl}) and meta.ask tells an agent to ask the person.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `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; without --to, when a loaded integration names its own issues URL, destinations and ask as on gap-report.categories.                                                                                                                                                                                                                                                                                                                                     |
 | `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 source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. The envelope's package names the npm package that owns the template.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
@@ -468,18 +468,19 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `theme.palette.generate`          | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `upgrade.list`                    | Every available codemod, oldest→newest, as {name, package, title, version, optional}; returned for --list without running anything.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `upgrade.registry`                | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `upgrade.status`                  | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `upgrade.status`                  | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. no_codemods and config_fixable carry cliBehindCore ({cliVersion, command}) when the installed Core is newer than the CLI, which then has no codemods for the releases after its own version.                                                                                                                                                                                                                                                                                                                                                                                 |
+| `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run.                                                                                                                                                                                                                                                              |
 | `manifest`                        | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `help`                            | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second.                                                                                                                                                                             |
 | `version`                         | The CLI version, for `astryx --version --json`: {version}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `doctor`                          | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `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: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                                                     |
+| `integration.validate`            | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked \| skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).                   |
 | `integration.template-conflicts`  | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), 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`       | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), 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. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked \| skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings), unchecked, typesNotCompared, and propsNotChecked.                                                                                                                                |
+| `integration.doc-conflicts`       | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`). copiedPassages lists each pair of topics that repeat 10 or more words of prose word for word: topic, section, otherTopic, otherOwner (package \| core), words, passages, owner (the topic that should keep the text), text (the passage as the topic writes it), line (where the copy starts in the topic to change, or null), and message (the exact replacement); each is also a copied_passage warning in issues.               |
+| `integration.check`               | Every source check of an integration package in one result: validated (false when no integration manifest was found, so nothing was checked), the package name and version, strict, and checks, one entry per check (validate, components, templates, docs), each with check, errors, warnings, skipped, failed, and response, the envelope that check returns on its own. The totals are errors, warnings, and skipped; unchecked counts what the checks could not compare. With --strict, failures lists each warning and each piece of skipped work again as an error, in the issue format the checks use; it is empty without --strict. failed decides the exit code.                                     |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -551,12 +552,12 @@ data: { checks, summary } }`) that AI agents and scripts can parse.
 Omit `[package]` to inspect the package at the current directory, or pass an
 installed package name:
 
-| Command                                   | What it checks                                               | Exit `1` when                                           |
-| ----------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
-| `doctor integration validate [package]`   | Manifest shape and every declared contribution               | A structural issue has error severity                   |
-| `doctor integration templates [package]`  | Template IDs shared with Core                                | The integration is invalid; ID conflicts are warnings   |
-| `doctor integration components [package]` | Component names shared with Core                             | The integration is invalid; name conflicts are warnings |
-| `doctor integration docs [package]`       | Core topic replacements, extensions, and same-name conflicts | A Core overlap is accidental or the docs are invalid    |
+| Command                                   | What it checks                                                                      | Exit `1` when                                                                |
+| ----------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `doctor integration validate [package]`   | Manifest shape and every declared contribution                                      | A structural issue has error severity                                        |
+| `doctor integration templates [package]`  | Template IDs shared with Core                                                       | The integration is invalid; ID conflicts are warnings                        |
+| `doctor integration components [package]` | Component names shared with Core, and each props table against the TypeScript props | The integration is invalid; name conflicts and prop differences are warnings |
+| `doctor integration docs [package]`       | Core topic replacements, extensions, and same-name conflicts                        | A Core overlap is accidental or the docs are invalid                         |
 
 Template and component conflicts include the exact `--package` command needed
 to select the integration contribution. Doc replacements and extensions are
@@ -580,12 +581,12 @@ There is no factory: write a plain object. For editor autocomplete and
 type-checking, annotate it with the `AstryxConfig` type exported from
 `@astryxdesign/cli/authoring`.
 
-| Field                         | Type                           | Purpose                                                                                         |
-| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                          |
-| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.       |
-| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).    |
-| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
+| Field                         | Type                           | Purpose                                                                                                                                                                                                 |
+| ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                                                                                                                                  |
+| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.                                                                                                               |
+| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).                                                                                                            |
+| `experimental.xle.components` | `Record<string, XleComponent>` | 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. |
 
 The config is validated against a strict schema when the CLI loads it, so an
 unknown field is a hard error rather than a silent no-op. `astryx doctor`

package/api/build/help/help.mjs

@@ -63,7 +63,7 @@ export function buildHelp() {
         "Keep the template's page frame, gap, and padding values. Replace its data, copy, and sections.",
         'No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
         'No style={{}} — use component props, and design tokens for values.',
-        "Wrap the app in <Theme theme={...}> (import {Theme} from '@astryxdesign/core') and import core reset.css + astryx.css.",
+        "Wrap the app in <Theme theme={...}> (import {Theme} from '@astryxdesign/core/theme') and import core reset.css + astryx.css.",
       ],
       related: [
         {

package/api/component/_adapter.d.mts

@@ -26,6 +26,8 @@
  * @property {string|null} sourcePath
  * @property {string|undefined} issuesUrl
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
+ * @property {import('../../foundation/discovery/component-discovery.mjs').NameHold} hold
+ *   how the owner holds the name, for the owner rule
  */
 /**
  * What ownership shaping needs from an owner. The core and legacy-external
@@ -138,6 +140,25 @@ export function assertUnambiguousOwners(owners: ComponentOwner[], dirName: strin
  * @returns {string | null}
  */
 export function resolveLegacyExternalDoc(ext: ExternalPackageRef, dirName: string): string | null;
+/**
+ * Whether a legacy external package documents `dirName`.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @returns {boolean}
+ */
+export function legacyExternalDocuments(cwd: string, dirName: string): boolean;
+/**
+ * Whether a legacy docs package keeps `dirName` over these owners, each of which
+ * holds it only as an export a doc records.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @param {Array<{hold?: string, docPath?: string | null}>} owners
+ * @returns {boolean}
+ */
+export function legacyExternalKeeps(cwd: string, dirName: string, owners: Array<{
+    hold?: string;
+    docPath?: string | null;
+}>): boolean;
 /**
  * The core source file for `dirName` (the no-scope `--source` path reads core
  * directly — it does NOT fall back to externals or fuzzy search).
@@ -210,7 +231,20 @@ export function scopeSubComponent(docs: LoadedComponentDoc, dirName: string, cor
     };
     matchingComponent: any;
 } | null;
-export { CORE_PACKAGE };
+/**
+ * The doc an integration owner shows for `dirName`: when `dirName` is a member
+ * its family doc lists under its own name (`AcmeSlide` in an `AcmeCarousel`
+ * doc), the doc scoped to that member as {@link scopeSubComponent} scopes
+ * Core's, keeping the import the family doc states; otherwise `docs` itself.
+ * @param {LoadedComponentDoc} docs
+ * @param {OwnershipSubject} owner
+ * @param {string} dirName
+ * @returns {LoadedComponentDoc & {parentDoc?: string, import?: string}}
+ */
+export function scopeIntegrationMember(docs: LoadedComponentDoc, owner: OwnershipSubject, dirName: string): LoadedComponentDoc & {
+    parentDoc?: string;
+    import?: string;
+};
 /**
  * Internal ambiguity marker. Single-component callers still receive the same
  * AstryxError code, message, and suggestions; batch callers can additionally
@@ -261,6 +295,10 @@ export type ComponentOwner = {
     sourcePath: string | null;
     issuesUrl: string | undefined;
     integration: import("../../foundation/integrations/integrations.mjs").LoadedIntegration | null;
+    /**
+     *   how the owner holds the name, for the owner rule
+     */
+    hold: import("../../foundation/discovery/component-discovery.mjs").NameHold;
 };
 /**
  * What ownership shaping needs from an owner. The core and legacy-external
@@ -303,4 +341,6 @@ export type ResolvedUnscopedDoc = {
     resolvedSourcePath: string | null;
 };
 import { CORE_PACKAGE } from '../../foundation/discovery/component-discovery.mjs';
+import { unscopedComponentOwners } from '../../foundation/discovery/component-discovery.mjs';
 import { AstryxError } from '../error.mjs';
+export { CORE_PACKAGE, unscopedComponentOwners };

package/api/component/_adapter.mjs

@@ -28,13 +28,17 @@ import {
 import {
   CORE_PACKAGE,
   discoverComponents,
+  docStem,
   findComponentReadme,
   findComponentSource,
   findExternalComponentDoc,
-  findIntegrationComponentDoc,
-  findIntegrationComponentSource,
+  findIntegrationComponent,
+  integrationMemberEntry,
+  isIntegrationMember,
+  recordedDocName,
   resolveImportPath,
   resolveIntegrationImportPath as resolveIntegrationImport,
+  unscopedComponentOwners,
 } from '../../foundation/discovery/component-discovery.mjs';
 import {Project} from '../../foundation/config/project.mjs';
 import {loadComponentDoc as loadValidatedComponentDoc} from '../../foundation/discovery/component-loader.mjs';
@@ -42,7 +46,7 @@ import {resolveComponentReplacements} from '../../foundation/discovery/component
 import {searchComponents} from '../../foundation/text/string-utils.mjs';
 import {AstryxError} from '../error.mjs';
 
-export {CORE_PACKAGE};
+export {CORE_PACKAGE, unscopedComponentOwners};
 
 /**
  * A loaded component doc. The shared validated loader accepts stamped and legacy
@@ -71,6 +75,8 @@ export {CORE_PACKAGE};
  * @property {string|null} sourcePath
  * @property {string|undefined} issuesUrl
  * @property {import('../../foundation/integrations/integrations.mjs').LoadedIntegration|null} integration
+ * @property {import('../../foundation/discovery/component-discovery.mjs').NameHold} hold
+ *   how the owner holds the name, for the owner rule
  */
 
 /**
@@ -240,17 +246,19 @@ export function resolveOwners(coreDir, dirName, loadedIntegrations) {
       sourcePath: findComponentSource(coreDir, dirName),
       issuesUrl: undefined,
       integration: null,
+      hold: 'core',
     });
   }
   for (const integration of loadedIntegrations) {
-    const docPath = findIntegrationComponentDoc(integration, dirName);
-    if (!docPath) continue;
+    const found = findIntegrationComponent(integration, dirName);
+    if (!found) continue;
     owners.push({
       package: integration.name,
-      docPath,
-      sourcePath: findIntegrationComponentSource(integration, dirName),
+      docPath: found.docPath,
+      sourcePath: found.sourcePath,
       issuesUrl: integration.issuesUrl,
       integration,
+      hold: found.hold,
     });
   }
   return owners;
@@ -361,6 +369,39 @@ export function resolveLegacyExternalDoc(ext, dirName) {
   return extDocPath && extDocPath.endsWith('.doc.mjs') ? extDocPath : null;
 }
 
+/**
+ * Whether a legacy external package documents `dirName`.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @returns {boolean}
+ */
+export function legacyExternalDocuments(cwd, dirName) {
+  return discoverExternalPackages(cwd).some(
+    ext => resolveLegacyExternalDoc(ext, dirName) != null,
+  );
+}
+
+/**
+ * Whether a legacy docs package keeps `dirName` over these owners, each of which
+ * holds it only as an export a doc records.
+ * @param {string} cwd
+ * @param {string} dirName
+ * @param {Array<{hold?: string, docPath?: string | null}>} owners
+ * @returns {boolean}
+ */
+export function legacyExternalKeeps(cwd, dirName, owners) {
+  return (
+    owners.length > 0 &&
+    owners.every(
+      owner =>
+        owner.hold === 'doc' &&
+        owner.docPath != null &&
+        docStem(owner.docPath).toLowerCase() !== dirName.toLowerCase(),
+    ) &&
+    legacyExternalDocuments(cwd, dirName)
+  );
+}
+
 /**
  * The core source file for `dirName` (the no-scope `--source` path reads core
  * directly — it does NOT fall back to externals or fuzzy search).
@@ -583,3 +624,48 @@ export function scopeSubComponent(docs, dirName, coreDir) {
 
   return {scoped, matchingComponent};
 }
+
+/**
+ * The doc an integration owner shows for `dirName`: when `dirName` is a member
+ * its family doc lists under its own name (`AcmeSlide` in an `AcmeCarousel`
+ * doc), the doc scoped to that member as {@link scopeSubComponent} scopes
+ * Core's, keeping the import the family doc states; otherwise `docs` itself.
+ * @param {LoadedComponentDoc} docs
+ * @param {OwnershipSubject} owner
+ * @param {string} dirName
+ * @returns {LoadedComponentDoc & {parentDoc?: string, import?: string}}
+ */
+export function scopeIntegrationMember(docs, owner, dirName) {
+  const record = {name: dirName, docPath: owner.docPath ?? null};
+  if (!isIntegrationMember(record)) return docs;
+  const entry = integrationMemberEntry(docs, record);
+  // The files list the member but the doc this process loaded has no entry
+  // for it (the doc changed after it loaded): never answer with the family.
+  if (entry == null) {
+    throw new AstryxError(
+      `No component named "${dirName}": its family doc changed after this process loaded it.`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+  // Built from the entry, as scopeSubComponent scopes Core's, so a member that
+  // shares the doc's own `name` is scoped too.
+  /** @type {LoadedComponentDoc & {parentDoc?: string, import?: string}} */
+  const scoped = {
+    name: dirName,
+    description: entry.description,
+    props: entry.props,
+    components: [entry],
+    // The name the family doc opens under, for every member.
+    parentDoc:
+      owner.integration && record.docPath
+        ? recordedDocName(owner.integration, record.docPath)
+        : docs.name === dirName && record.docPath
+          ? docStem(record.docPath)
+          : docs.name,
+  };
+  if (docs.usage) scoped.usage = docs.usage;
+  if (docs.theming) scoped.theming = docs.theming;
+  if (docs.import) scoped.import = docs.import;
+  return scoped;
+}

package/api/component/component.mjs

@@ -19,9 +19,11 @@ import {
   requireCoreDir,
   loadIntegrationsSafely,
   resolveOwners,
+  scopeIntegrationMember,
   classifyScope,
   assertUnambiguousOwners,
   resolveLegacyExternalDoc,
+  legacyExternalKeeps,
   resolveCoreSourcePath,
   resolveUnscopedDoc,
   loadComponentDoc,
@@ -29,6 +31,7 @@ import {
   ComponentAmbiguityError,
   installedComponentPackageVersion,
   resolveComponentReplacement,
+  unscopedComponentOwners,
 } from './_adapter.mjs';
 import {componentList} from './list/list.mjs';
 import {componentDetail} from './detail/detail.mjs';
@@ -427,7 +430,13 @@ export async function component(name, options = {}) {
       if (blocks) {
         return componentDetailBlocks(dirName, cwd, owner.package);
       }
-      const docs = await loadComponentDoc(owner.docPath, docOpts);
+      const loaded = await loadComponentDoc(owner.docPath, docOpts);
+      // A family member an integration lists under its own name reads as that
+      // member, the way a Core sub-component does below.
+      const docs =
+        scoped.kind === 'integration'
+          ? scopeIntegrationMember(loaded, owner, dirName)
+          : loaded;
       if (props) return componentDetailProps(docs, owner.package);
       return componentDetail(docs, owner, dirName, coreDir);
     }
@@ -481,12 +490,14 @@ export async function component(name, options = {}) {
     });
   }
 
+  // The owner rule runs first, over valid and invalid owners alike.
+  const ruled = unscopedComponentOwners(owners);
   // Invalid integration metadata does not create ambiguity against a valid
-  // owner. Keep raw owners only when no doc owner is valid, so an integration-
+  // owner. Keep ruled 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) {
+  for (const owner of ruled) {
     if (owner.package === CORE_PACKAGE) {
       validOwners.push(owner);
       continue;
@@ -498,7 +509,12 @@ export async function component(name, options = {}) {
       // Project/Doctor report invalid metadata; it is not an effective owner.
     }
   }
-  const effectiveOwners = validOwners.length > 0 ? validOwners : owners;
+  const loadable = validOwners.length > 0 ? validOwners : ruled;
+  // A legacy docs package's exact doc keeps its name over an export name a doc
+  // records, as Core and file-named owners do.
+  const effectiveOwners = legacyExternalKeeps(cwd, dirName, loadable)
+    ? []
+    : loadable;
 
   // ── Ambiguity: owned by MORE THAN ONE valid package, no --package ──
   assertUnambiguousOwners(effectiveOwners, dirName);
@@ -516,7 +532,8 @@ export async function component(name, options = {}) {
       // Integration components don't carry showcases — fail without scanning.
       return componentDetailShowcase(dirName, {cwd, name, resolve: false, ownerPackage: owner.package});
     }
-    const docs = await loadComponentDoc(owner.docPath, docOpts);
+    const loaded = await loadComponentDoc(owner.docPath, docOpts);
+    const docs = scopeIntegrationMember(loaded, owner, dirName);
     if (props) return componentDetailProps(docs, owner.package);
     return componentDetail(docs, owner, dirName, coreDir);
   }

package/api/component/component.test.mjs

@@ -13,6 +13,7 @@ import {describe, it, expect} from 'vitest';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {component} from './component.mjs';
+import {search} from '../search/search.mjs';
 import {AstryxError} from '../error.mjs';
 import {runCli} from '../../test-utils/run-cli.mjs';
 
@@ -92,6 +93,85 @@ describe('component dispatcher — detail levels on list', () => {
   );
 });
 
+describe('component list — components whose docs live in a family folder', () => {
+  it('lists HStack, VStack and Heading at every detail level, each with its own import', async () => {
+    const {docs: stackDoc} = await import(
+      path.join(REPO, 'packages', 'core', 'src', 'Stack', 'Stack.doc.mjs')
+    );
+    const vstackMember = stackDoc.components.find(c => c.name === 'VStack');
+
+    const names = await component(undefined, {cwd, list: true});
+    const listed = Object.values(names.data.components).flat();
+    for (const name of ['HStack', 'VStack', 'Heading']) {
+      expect(listed).toContainEqual({name, package: '@astryxdesign/core'});
+    }
+
+    const compact = await component(undefined, {cwd, list: true, detail: 'compact'});
+    const brief = Object.values(compact.data.components).flat();
+    expect(brief.find(e => e.name === 'VStack')).toEqual({
+      name: 'VStack',
+      package: '@astryxdesign/core',
+      description: vstackMember.description,
+      import: '@astryxdesign/core/VStack',
+    });
+
+    const full = await component(undefined, {cwd, list: true, detail: 'full'});
+    const entry = Object.values(full.data.components)
+      .flat()
+      .find(e => e.name === 'VStack');
+    // Shaped like every other full entry (a component doc plus its package):
+    // the member's own name, display name and summary, and no scoping field
+    // the full-entry type does not describe.
+    expect(entry).toEqual({
+      name: 'VStack',
+      package: '@astryxdesign/core',
+      displayName: vstackMember.displayName,
+      group: stackDoc.group,
+      category: stackDoc.category,
+      usage: {description: vstackMember.description},
+      props: vstackMember.props,
+      theming: stackDoc.theming,
+      import: '@astryxdesign/core/VStack',
+    });
+  }, SLOW);
+
+  it('prints each one\'s own import path in the list, the detail, and search', async () => {
+    // The path `component <Name>` prints is the one docs and examples teach:
+    // the component's own entry point, never its family's (/Stack, /Text) or
+    // a re-export (/Layout).
+    const compact = Object.values(
+      (await component(undefined, {cwd, list: true, detail: 'compact'})).data.components,
+    ).flat();
+    const full = Object.values(
+      (await component(undefined, {cwd, list: true, detail: 'full'})).data.components,
+    ).flat();
+    const textList = (await runCli(['component', '--list'], cwd)).stdout;
+    const textCompact = (
+      await runCli(['component', '--list', '--detail', 'compact'], cwd)
+    ).stdout;
+    /** The `import:` line of a text record, found by its `name:` line. */
+    const textImport = (text, name) =>
+      new RegExp(`^name:\\s+${name}\\n(?:(?!name:).*\\n)*?import:\\s+(\\S+)`, 'm').exec(
+        text,
+      )?.[1];
+    for (const name of ['VStack', 'HStack', 'Heading']) {
+      const expected = `@astryxdesign/core/${name}`;
+      expect(compact.find(e => e.name === name)?.import).toBe(expected);
+      expect((await component(name, {cwd})).data.import).toBe(expected);
+      const hits = (await search(name, {cwd, type: 'component'})).data.results;
+      expect(hits.find(r => r.name === name)?.import).toBe(expected);
+      expect(textImport(textList, name)).toBe(expected);
+      expect(textImport(textCompact, name)).toBe(expected);
+    }
+    // The full level spreads a component's own doc, which states no import
+    // (Button's entry has none either); a member's entry is scoped to the
+    // member and states its own.
+    for (const name of ['VStack', 'HStack']) {
+      expect(full.find(e => e.name === name)?.import).toBe(`@astryxdesign/core/${name}`);
+    }
+  }, SLOW);
+});
+
 describe('component dispatcher — projection precedence (locked)', () => {
   it(
     '--props routes to component.detail.props',