@astryxdesign/cli 0.1.2-canary.b712653 → 0.1.2-canary.bbf77ea

package/CHANGELOG.md

@@ -110,7 +110,6 @@ Thanks to everyone who contributed to this release:
 Thanks to everyone who contributed to this release:
 
 - @ejhammond
-- @joeyfarina
 - @josephfarina
 - @nynexman4464
 

package/README.md

@@ -62,8 +62,7 @@ Options:
 | `upgrade`     | Run codemods to migrate between versions                                                             |
 | `theme build` | Compile a defineTheme file to production CSS and JS                                                  |
 | `discover`    | Discover external packages and components                                                            |
-| `gap-report`  | Report a gap when a component doesn't meet your needs                                                |
-| `doctor`      | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code)                   |
+| `doctor`      | Diagnose your Astryx setup and report problems with fixes (CI-friendly via exit code)                |
 
 ### Global options
 
@@ -161,7 +160,6 @@ if (isError(result)) {
 | `ERR_INVALID_VERSION`    | A `--from`/`--to` value was not a valid semver string.                                 |
 | `ERR_DEP_MISSING`        | A required external dependency (e.g. jscodeshift) is missing.                          |
 | `ERR_GH_CLI`             | GitHub CLI (`gh`) is not installed or not authenticated.                               |
-| `ERR_GAP_REPORT_FAILED`  | Filing a gap report failed (disabled, or the integration errored).                     |
 
 ## Capability manifest (agent discovery)
 
@@ -172,7 +170,7 @@ discriminators each command can emit. Think of it as an OpenAPI spec for the CLI
 
 ```bash
 astryx manifest --json        # dedicated surface — type: "manifest"
-xds --json                 # bare invocation — embeds the same payload under data.manifest
+astryx --json                 # bare invocation — embeds the same payload under data.manifest
 ```
 
 Shape:
@@ -182,7 +180,7 @@ Shape:
   "apiVersion": 1,
   "type": "manifest",
   "data": {
-    "name": "xds",
+    "name": "astryx",
     "version": "0.0.14",
     "description": "Design system CLI — components, themes, and tooling",
     "globalOptions": [
@@ -249,14 +247,14 @@ the `JSON_SUPPORTED` allowlist and a small declarative `RESPONSE_TYPES` map in
 `src/lib/manifest.mjs`, guarded by a drift test (`manifest.test.mjs`) so adding a
 command without describing it fails CI.
 
-**Backwards-compat:** the bare `xds --json` envelope keeps `type: "help"` and its
+**Backwards-compat:** the bare `astryx --json` envelope keeps `type: "help"` and its
 original shallow fields (`name`, `version`, `commands` as a `string[]` of names,
 `jsonSupported`); the full structured manifest is additive under `data.manifest`.
 For the standalone manifest envelope (`type: "manifest"`), use `astryx manifest --json`.
 
 ## Programmatic API
 
-The same logic that powers `xds --json` is available as importable, type-safe functions:
+The same logic that powers `astryx --json` is available as importable, type-safe functions:
 
 ```typescript
 import {
@@ -269,20 +267,20 @@ import {
   AstryxError,
 } from '@astryxdesign/cli/api';
 
-// Same result as: xds --json component Button
+// Same result as: astryx --json component Button
 const btn = await component('Button');
 btn.type; // 'component.detail'
 btn.data.name; // 'Button' (typed as ComponentDoc)
 
-// Same result as: xds --json component --list
+// Same result as: astryx --json component --list
 const list = await component(undefined, {list: true});
 list.data; // Record<string, string[]>
 
-// Same result as: xds --json docs principles
+// Same result as: astryx --json docs principles
 const principles = await docs('principles');
-principles.data.title; // 'XDS Principles'
+principles.data.title; // 'Principles'
 
-// Same result as: xds --json hook useMediaQuery
+// Same result as: astryx --json hook useMediaQuery
 const useMediaQuery = await hook('useMediaQuery');
 useMediaQuery.data.params; // typed as HookParamDoc[]
 
@@ -296,7 +294,7 @@ try {
 }
 ```
 
-The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `xds --json` always return identical data.
+The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `astryx --json` always return identical data.
 
 ### Consumer utilities
 
@@ -326,43 +324,41 @@ detail.data.name; // already narrowed
 
 Every response has a `type` string that uniquely identifies it:
 
-| Command                                        | Type                        | Response                          |
-| ---------------------------------------------- | --------------------------- | --------------------------------- |
-| `xds --json component [--list]`                | `component.list`            | `ComponentListResponse`           |
-| `xds --json component --list --detail compact` | `component.brief`           | `ComponentBriefResponse`          |
-| `xds --json component --list --detail full`    | `component.full`            | `ComponentFullResponse`           |
-| `xds --json component <name>`                  | `component.detail`          | `ComponentDetailResponse`         |
-| `xds --json component <name> --props`          | `component.detail.props`    | `ComponentDetailPropsResponse`    |
-| `xds --json component <name> --source`         | `component.detail.source`   | `ComponentDetailSourceResponse`   |
-| `xds --json component <name> --showcase`       | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |
-| `xds --json component <name> --blocks`         | `component.detail.blocks`   | `ComponentDetailBlocksResponse`   |
-| `xds --json discover`                          | `discover.list`             | `DiscoverListResponse`            |
-| `xds --json discover @scope/name`              | `discover.detail`           | `DiscoverDetailResponse`          |
-| `xds --json discover @scope/name/Comp`         | `discover.detail.doc`       | `DiscoverDetailDocResponse`       |
-| `xds --json discover <search>`                 | `discover.search`           | `DiscoverSearchResponse`          |
-| `xds --json docs`                              | `docs.list`                 | `DocsListResponse`                |
-| `xds --json docs <topic>`                      | `docs.detail`               | `DocsDetailResponse`              |
-| `xds --json docs <topic> <section>`            | `docs.detail.section`       | `DocsDetailSectionResponse`       |
-| `xds --json template [--list]`                 | `template.list`             | `TemplateListResponse`            |
-| `xds --json template <name>`                   | `template.show`             | `TemplateShowResponse`            |
-| `xds --json template <name> --skeleton`        | `template.skeleton`         | `TemplateSkeletonResponse`        |
-| `xds --json template <name> [path]`            | `template.copy`             | `TemplateCopyResponse`            |
-| `xds --json hook [--list]`                     | `hook.list`                 | `HookListResponse`                |
-| `xds --json hook --list --detail compact`      | `hook.brief`                | `HookBriefResponse`               |
-| `xds --json hook --list --detail full`         | `hook.full`                 | `HookFullResponse`                |
-| `xds --json hook <name>`                       | `hook.detail`               | `HookDetailResponse`              |
-| `xds --json hook <name> --params`              | `hook.detail.params`        | `HookDetailParamsResponse`        |
-| `xds --json search <query>`                    | `search`                    | `SearchResponse`                  |
-| `xds --json swizzle [--list]`                  | `swizzle.list`              | `SwizzleListResponse`             |
-| `xds --json swizzle <component>`               | `swizzle.copy`              | `SwizzleCopyResponse`             |
-| `xds --json theme build <file>`                | `theme.build`               | `ThemeBuildResponse`              |
-| `xds --json upgrade --list`                    | `upgrade.list`              | `UpgradeListResponse`             |
-| `xds --json upgrade [--apply]`                 | `upgrade.run`               | `UpgradeRunResponse`              |
-| `xds --json gap-report --list-categories`      | `gap-report.categories`     | `GapReportCategoriesResponse`     |
-| `xds --json gap-report --component X ...`      | `gap-report.file`           | `GapReportFileResponse`           |
-| `xds --json doctor`                            | `doctor`                    | `DoctorResponse`                  |
-| any error                                      | —                           | `CLIError`                        |
-| unsupported command                            | —                           | `CLIUnsupportedError`             |
+| Command                                           | Type                        | Response                          |
+| ------------------------------------------------- | --------------------------- | --------------------------------- |
+| `astryx --json component [--list]`                | `component.list`            | `ComponentListResponse`           |
+| `astryx --json component --list --detail compact` | `component.brief`           | `ComponentBriefResponse`          |
+| `astryx --json component --list --detail full`    | `component.full`            | `ComponentFullResponse`           |
+| `astryx --json component <name>`                  | `component.detail`          | `ComponentDetailResponse`         |
+| `astryx --json component <name> --props`          | `component.detail.props`    | `ComponentDetailPropsResponse`    |
+| `astryx --json component <name> --source`         | `component.detail.source`   | `ComponentDetailSourceResponse`   |
+| `astryx --json component <name> --showcase`       | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |
+| `astryx --json component <name> --blocks`         | `component.detail.blocks`   | `ComponentDetailBlocksResponse`   |
+| `astryx --json discover`                          | `discover.list`             | `DiscoverListResponse`            |
+| `astryx --json discover @scope/name`              | `discover.detail`           | `DiscoverDetailResponse`          |
+| `astryx --json discover @scope/name/Comp`         | `discover.detail.doc`       | `DiscoverDetailDocResponse`       |
+| `astryx --json discover <search>`                 | `discover.search`           | `DiscoverSearchResponse`          |
+| `astryx --json docs`                              | `docs.list`                 | `DocsListResponse`                |
+| `astryx --json docs <topic>`                      | `docs.detail`               | `DocsDetailResponse`              |
+| `astryx --json docs <topic> <section>`            | `docs.detail.section`       | `DocsDetailSectionResponse`       |
+| `astryx --json template [--list]`                 | `template.list`             | `TemplateListResponse`            |
+| `astryx --json template <name>`                   | `template.show`             | `TemplateShowResponse`            |
+| `astryx --json template <name> --skeleton`        | `template.skeleton`         | `TemplateSkeletonResponse`        |
+| `astryx --json template <name> [path]`            | `template.copy`             | `TemplateCopyResponse`            |
+| `astryx --json hook [--list]`                     | `hook.list`                 | `HookListResponse`                |
+| `astryx --json hook --list --detail compact`      | `hook.brief`                | `HookBriefResponse`               |
+| `astryx --json hook --list --detail full`         | `hook.full`                 | `HookFullResponse`                |
+| `astryx --json hook <name>`                       | `hook.detail`               | `HookDetailResponse`              |
+| `astryx --json hook <name> --params`              | `hook.detail.params`        | `HookDetailParamsResponse`        |
+| `astryx --json search <query>`                    | `search`                    | `SearchResponse`                  |
+| `astryx --json swizzle [--list]`                  | `swizzle.list`              | `SwizzleListResponse`             |
+| `astryx --json swizzle <component>`               | `swizzle.copy`              | `SwizzleCopyResponse`             |
+| `astryx --json theme build <file>`                | `theme.build`               | `ThemeBuildResponse`              |
+| `astryx --json upgrade --list`                    | `upgrade.list`              | `UpgradeListResponse`             |
+| `astryx --json upgrade [--apply]`                 | `upgrade.run`               | `UpgradeRunResponse`              |
+| `astryx --json doctor`                            | `doctor`                    | `DoctorResponse`                  |
+| any error                                         | —                           | `CLIError`                        |
+| unsupported command                               | —                           | `CLIUnsupportedError`             |
 
 ## Doctor
 
@@ -383,7 +379,7 @@ astryx doctor — diagnosing your setup
       @astryxdesign/core v0.0.14 is in step with @astryxdesign/cli v0.0.14.
   ⚠ Theme packages
       No @astryxdesign/theme-* packages are installed.
-      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.
+      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.
   ℹ astryx.config.mjs
       No astryx.config.mjs found — using defaults.
   ℹ AI agent docs
@@ -408,7 +404,7 @@ No failures — but review the ⚠ warnings above when you can.
 | Version alignment            | pass / warn / info   | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli`   |
 | Theme packages               | pass / warn          | An `@astryxdesign/theme-*` package is installed and a theme is wired |
 | astryx.config.mjs            | pass / fail / info   | Config (if present) loads cleanly with a valid shape                 |
-| AI agent docs                | pass / warn / info   | Agent docs exist and contain the XDS section markers                 |
+| AI agent docs                | pass / warn / info   | Agent docs exist and contain the Astryx section markers              |
 | Peer dependencies            | pass / warn / info   | `@astryxdesign/core`'s peer deps (react, …) are installed            |
 | Package manager              | info                 | Reports the detected package manager                                 |
 
@@ -434,8 +430,6 @@ export default {
   templates: {
     get: async id => fetchTemplateFromAPI(id),
   },
-  gapReport: {
-    url: 'https://your-api.com/gaps',
-  },
+  issuesUrl: 'https://github.com/your-org/your-repo/issues',
 };
 ```

package/docs/theme.doc.mjs

@@ -53,7 +53,7 @@ function App() {
         },
         {
           type: 'prose',
-          text: 'Each theme ships as its own npm package. Install the one you want, then wrap your app in `<Theme>` — the same pattern works for every theme; just swap the package and import name.',
+          text: 'Each theme ships as its own npm package. Install the one you want, then wrap your app in `<Theme>`. The same pattern works for every theme; just swap the package and import name.',
         },
         {
           type: 'prose',
@@ -261,7 +261,7 @@ const brandTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'The `components` field in defineTheme uses semantic component keys and style keys — not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in `astryx docs styling`.',
+          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in `astryx docs styling`.',
         },
         {
           type: 'code',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.2-canary.b712653",
+  "version": "0.1.2-canary.bbf77ea",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -43,6 +43,18 @@
       "types": "./src/types/config.d.ts",
       "import": "./src/config.mjs"
     },
+    "./integration": {
+      "types": "./src/types/integration.d.ts",
+      "import": "./src/integration.mjs"
+    },
+    "./template": {
+      "types": "./src/types/template-api.d.ts",
+      "import": "./src/template.mjs"
+    },
+    "./codemod": {
+      "types": "./src/types/codemod.d.ts",
+      "import": "./src/codemod.mjs"
+    },
     "./xle": {
       "types": "./src/lib/xle/browser.d.ts",
       "import": "./src/lib/xle/browser.mjs"
@@ -63,9 +75,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.b712653",
-    "@astryxdesign/lab": "0.1.2-canary.b712653",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.b712653",
+    "@astryxdesign/core": "0.1.2-canary.bbf77ea",
+    "@astryxdesign/lab": "0.1.2-canary.bbf77ea",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.bbf77ea",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -80,9 +92,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.b712653",
-    "@astryxdesign/lab": "0.1.2-canary.b712653",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.b712653",
+    "@astryxdesign/core": "0.1.2-canary.bbf77ea",
+    "@astryxdesign/lab": "0.1.2-canary.bbf77ea",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.bbf77ea",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/src/api/component.mjs

@@ -11,18 +11,48 @@ import * as fs from 'node:fs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
 import {findCoreDir, discoverExternalPackages} from '../utils/paths.mjs';
 import {
+  CORE_PACKAGE,
   discoverComponents,
   discoverExternalComponentsGrouped,
+  discoverIntegrationComponents,
   findComponentReadme,
   findComponentSource,
   findExternalComponentDoc,
+  findIntegrationComponentDoc,
+  findIntegrationComponentSource,
   resolveImportPath,
 } from '../lib/component-discovery.mjs';
+import {Project} from '../lib/project.mjs';
 import {loadDocs} from '../lib/component-loader.mjs';
 import {searchComponents} from '../lib/string-utils.mjs';
 import {AstryxError} from './error.mjs';
 import {findShowcase, findRelatedBlocks} from './template.mjs';
 
+/**
+ * Load the configured integrations for `cwd`, swallowing any config errors so
+ * component discovery never hard-fails on a malformed/absent integration. An
+ * empty list means "core only".
+ * @param {string} cwd
+ * @returns {Promise<Array<{name: string, components?: string, issuesUrl?: string}>>}
+ */
+async function loadIntegrationsSafely(cwd) {
+  try {
+    const project = await Project.load(cwd);
+    return project.loadedIntegrations;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve a loaded integration by package name.
+ * @param {Array<{name: string}>} loadedIntegrations
+ * @param {string} packageName
+ */
+function findLoadedIntegration(loadedIntegrations, packageName) {
+  return loadedIntegrations.find(i => i.name === packageName) ?? null;
+}
+
 /**
  * Resolve an external package by name from the discovered externals list.
  * @param {string} packageName - e.g. '@acme/xds-widgets'
@@ -131,8 +161,13 @@ export async function component(name, options = {}) {
         return {type: 'component.full', data: {[match[0]]: entries}};
       }
 
-      // Default: brief — names only
-      return {type: 'component.list', data: {[match[0]]: match[1]}};
+      // Default: brief — package-qualified object list for the category.
+      // Pre-1.0 JSON contract: members are {name, package} objects, not bare
+      // strings, so consumers can disambiguate ownership.
+      return {
+        type: 'component.list',
+        data: {[match[0]]: match[1].map(n => ({name: n, package: CORE_PACKAGE}))},
+      };
     }
 
     // All components — merge core + external packages with grouped subcategories
@@ -179,43 +214,189 @@ export async function component(name, options = {}) {
       return {type: 'component.full', data: result};
     }
 
-    // Default: brief — names only (with externals merged in)
+    // Default: brief — package-qualified object list (core + integrations).
+    // Pre-1.0 JSON contract: each group's members are {name, package} objects.
+    /** @type {Record<string, Array<{name: string, package: string}>>} */
+    const listData = {};
+    for (const [cat, comps] of Object.entries(components)) {
+      listData[cat] = comps.map(n => ({name: n, package: CORE_PACKAGE}));
+    }
+
+    // Integration components (authoritative source: loadedIntegrations).
+    const loadedIntegrations = await loadIntegrationsSafely(cwd);
+    const seenIntegration = new Set();
+    for (const integration of loadedIntegrations) {
+      seenIntegration.add(integration.name);
+      const owned = discoverIntegrationComponents(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.
+      /** @type {Map<string, Array<{name: string, package: string}>>} */
+      const byGroup = new Map();
+      for (const rec of owned) {
+        const groupLabel = rec.group ?? integration.name;
+        const key = `${groupLabel} (${integration.name})`;
+        if (!byGroup.has(key)) byGroup.set(key, []);
+        byGroup.get(key).push({name: rec.name, package: integration.name});
+      }
+      for (const [key, members] of byGroup) {
+        members.sort((a, b) => a.name.localeCompare(b.name));
+        listData[key] = members;
+      }
+    }
+
+    // Back-compat: node_modules-scanned external packages (pkg.astryx.docs)
+    // that are NOT configured integrations. Preserves existing discovery for
+    // consumers that haven't adopted the config-integration flow.
     const externals = discoverExternalPackages(cwd);
     for (const ext of externals) {
+      if (seenIntegration.has(ext.name)) continue;
       const grouped = discoverExternalComponentsGrouped(ext.docsDir);
       const groupKeys = Object.keys(grouped);
       if (groupKeys.length === 0) continue;
 
-      // If the package has subcategories (groups), emit each as a separate key.
-      // If no groups exist, fall back to the flat list under one key.
       const hasGroups = groupKeys.some(
         k => grouped[k].length > 1 || grouped[k][0] !== k,
       );
 
       if (hasGroups) {
         for (const [group, members] of Object.entries(grouped)) {
-          components[`${group} (${ext.name})`] = members;
+          listData[`${group} (${ext.name})`] = members.map(n => ({
+            name: n,
+            package: ext.name,
+          }));
         }
       } else {
-        // All ungrouped — single flat list under the package category
         const allComps = Object.values(grouped).flat().sort();
         if (allComps.length > 0) {
-          components[`${ext.category} (${ext.name})`] = allComps;
+          listData[`${ext.category} (${ext.name})`] = allComps.map(n => ({
+            name: n,
+            package: ext.name,
+          }));
         }
       }
     }
-    return {type: 'component.list', data: components};
+    return {type: 'component.list', data: listData};
   }
 
   // ── Single component ───────────────────────────────────────────
 
+  if (typeof name !== 'string') {
+    throw new AstryxError(
+      `No component named "${String(name)}"`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
   const dirName = name.replace(/^XDS/, '');
 
+  // Ownership-aware resolution. Build the set of OWNER packages that provide a
+  // component with this name across core + every loaded integration. This is
+  // what lets the CLI disambiguate by package and expose the owner's source +
+  // issuesUrl (the inputs the future integration-component swizzle needs).
+  const loadedIntegrations = await loadIntegrationsSafely(cwd);
+  const coreDocPath = findComponentReadme(coreDir, dirName);
+  /**
+   * @type {Array<{
+   *   package: string,
+   *   docPath: string,
+   *   sourcePath: string|null,
+   *   issuesUrl: string|undefined,
+   *   integration: object|null,
+   * }>}
+   */
+  const owners = [];
+  if (coreDocPath) {
+    owners.push({
+      package: CORE_PACKAGE,
+      docPath: coreDocPath,
+      sourcePath: findComponentSource(coreDir, dirName),
+      issuesUrl: undefined,
+      integration: null,
+    });
+  }
+  for (const integration of loadedIntegrations) {
+    const docPath = findIntegrationComponentDoc(integration, dirName);
+    if (!docPath) continue;
+    owners.push({
+      package: integration.name,
+      docPath,
+      sourcePath: findIntegrationComponentSource(integration, dirName),
+      issuesUrl: integration.issuesUrl,
+      integration,
+    });
+  }
+
+  /**
+   * Augment a loaded `component.detail` doc with ownership metadata. Adds
+   * `package`, the resolved `import` specifier, and `sourceAvailable` (whether
+   * a swizzleable source file exists for the owner). Existing doc fields
+   * (name, usage, props, …) are preserved.
+   * @param {object} docs
+   * @param {{package: string, sourcePath: string|null}} owner
+   * @param {string} componentName
+   */
+  function withOwnership(docs, owner, componentName) {
+    const importSpec =
+      owner.package === CORE_PACKAGE
+        ? resolveImportPath(coreDir, componentName)
+        : `${owner.package}/${componentName}`;
+    return {
+      ...docs,
+      package: owner.package,
+      import: importSpec,
+      sourceAvailable: owner.sourcePath != null,
+    };
+  }
+
   // When scoped to a specific package, search that package first.
   // This is critical for components that exist in both core and an external
   // package (e.g. AppShell, Button, SideNav) — the package scope ensures
   // the external package's docs are returned, not core's.
   if (packageScope) {
+    // Core scope: resolve from core directly.
+    if (packageScope === CORE_PACKAGE) {
+      const owner = owners.find(o => o.package === CORE_PACKAGE);
+      if (!owner) {
+        throw new AstryxError(`No component "${name}" in package "${packageScope}"`, undefined, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
+      }
+      if (source) {
+        if (!owner.sourcePath) {
+          throw new AstryxError(`Source for "${name}" not found`, undefined, ERROR_CODES.ERR_NO_SOURCE);
+        }
+        return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
+      }
+      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      if (props) {
+        const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
+        return {type: 'component.detail.props', data: p};
+      }
+      return {type: 'component.detail', data: withOwnership(docs, owner, dirName)};
+    }
+
+    // Integration scope (authoritative): resolve from the loaded integration.
+    const integration = findLoadedIntegration(loadedIntegrations, packageScope);
+    if (integration) {
+      const owner = owners.find(o => o.package === packageScope);
+      if (!owner) {
+        throw new AstryxError(`No component "${name}" in package "${packageScope}"`, undefined, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
+      }
+      if (source) {
+        if (!owner.sourcePath) {
+          throw new AstryxError(`Source for "${name}" not found in package "${packageScope}"`, undefined, ERROR_CODES.ERR_NO_SOURCE);
+        }
+        return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
+      }
+      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      if (props) {
+        const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
+        return {type: 'component.detail.props', data: p};
+      }
+      return {type: 'component.detail', data: withOwnership(docs, owner, dirName)};
+    }
+
+    // Legacy fallback: node_modules `pkg.astryx.docs` external package.
     const ext = resolveExternalPackage(packageScope, cwd);
     if (!ext) {
       throw new AstryxError(`External package "${packageScope}" not found`, undefined, ERROR_CODES.ERR_UNKNOWN_PACKAGE);
@@ -244,11 +425,49 @@ export async function component(name, options = {}) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
         return {type: 'component.detail.props', data: p};
       }
-      return {type: 'component.detail', data: docs};
+      return {
+        type: 'component.detail',
+        data: withOwnership(docs, {package: ext.name, sourcePath: null}, dirName),
+      };
     }
     throw new AstryxError(`No component "${name}" in package "${packageScope}"`, undefined, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
   }
 
+  // Ambiguity: when the name is owned by MORE THAN ONE package (core and/or
+  // integrations) and the caller did not scope with --package, refuse to guess.
+  // NOTE: legacy `pkg.astryx.docs` externals are intentionally NOT part of this
+  // ambiguity set — they retain their historical core-first fallback below so
+  // existing consumers (and tests) keep working. Only config-driven integration
+  // ownership participates here.
+  if (owners.length > 1) {
+    throw new AstryxError(
+      `Component "${dirName}" is provided by multiple packages. Re-run with --package <pkg> to choose one.`,
+      owners.map(o => ({name: o.package, reason: 'provides this component'})),
+      ERROR_CODES.ERR_UNKNOWN_COMPONENT,
+    );
+  }
+
+  // Single non-core owner (an integration provides it, core does not) — resolve
+  // from that integration so the integration component is authoritative.
+  if (owners.length === 1 && owners[0].package !== CORE_PACKAGE) {
+    const owner = owners[0];
+    if (source) {
+      if (!owner.sourcePath) {
+        throw new AstryxError(`Source for "${name}" not found`, undefined, ERROR_CODES.ERR_NO_SOURCE);
+      }
+      return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
+    }
+    if (showcase) {
+      throw new AstryxError(`No showcase found for "${name}"`, undefined, ERROR_CODES.ERR_NO_SHOWCASE);
+    }
+    const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+    if (props) {
+      const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
+      return {type: 'component.detail.props', data: p};
+    }
+    return {type: 'component.detail', data: withOwnership(docs, owner, dirName)};
+  }
+
   if (source) {
     const sourcePath = findComponentSource(coreDir, dirName);
     if (!sourcePath) {
@@ -274,6 +493,10 @@ export async function component(name, options = {}) {
 
   let readmePath = findComponentReadme(coreDir, dirName);
   let resolvedName = dirName;
+  // Track the resolving owner so the detail payload can carry ownership info.
+  // Defaults to core; the legacy-external fallback below may reassign it.
+  let resolvedOwnerPackage = CORE_PACKAGE;
+  let resolvedSourcePath = readmePath ? findComponentSource(coreDir, dirName) : null;
 
   if (!readmePath) {
     const externals = discoverExternalPackages(cwd);
@@ -281,6 +504,8 @@ export async function component(name, options = {}) {
       const extDocPath = findExternalComponentDoc(ext.docsDir, dirName);
       if (extDocPath) {
         readmePath = extDocPath;
+        resolvedOwnerPackage = ext.name;
+        resolvedSourcePath = null;
         break;
       }
     }
@@ -299,6 +524,8 @@ export async function component(name, options = {}) {
       if (topScore >= 90 && topTied.length === 1 && gap >= 20) {
         resolvedName = topTied[0].name;
         readmePath = findComponentReadme(coreDir, resolvedName);
+        resolvedOwnerPackage = CORE_PACKAGE;
+        resolvedSourcePath = findComponentSource(coreDir, resolvedName);
       } else {
         const threshold = Math.max(topScore - 20, 1);
         const candidates = results.filter(r => r.score >= threshold).slice(0, 5);
@@ -382,7 +609,14 @@ export async function component(name, options = {}) {
     if (props) {
       return {type: 'component.detail.props', data: matchingComponent.props || []};
     }
-    return {type: 'component.detail', data: scoped};
+    return {
+      type: 'component.detail',
+      data: withOwnership(
+        scoped,
+        {package: resolvedOwnerPackage, sourcePath: resolvedSourcePath},
+        dirName,
+      ),
+    };
   }
 
   if (props) {
@@ -390,5 +624,12 @@ export async function component(name, options = {}) {
     return {type: 'component.detail.props', data: p};
   }
 
-  return {type: 'component.detail', data: docs};
+  return {
+    type: 'component.detail',
+    data: withOwnership(
+      docs,
+      {package: resolvedOwnerPackage, sourcePath: resolvedSourcePath},
+      resolvedName,
+    ),
+  };
 }