@astryxdesign/cli 0.1.2-canary.ac17c7f → 0.1.2-canary.b6820d0

package/README.md

@@ -62,6 +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)                   |
 
 ### Global options
@@ -160,6 +161,7 @@ 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)
 
@@ -356,6 +358,8 @@ Every response has a `type` string that uniquely identifies it:
 | `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`             |
@@ -430,6 +434,8 @@ export default {
   templates: {
     get: async id => fetchTemplateFromAPI(id),
   },
-  issuesUrl: 'https://github.com/your-org/your-repo/issues',
+  gapReport: {
+    url: 'https://your-api.com/gaps',
+  },
 };
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.2-canary.ac17c7f",
+  "version": "0.1.2-canary.b6820d0",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -43,18 +43,6 @@
       "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"
@@ -75,9 +63,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.ac17c7f",
-    "@astryxdesign/lab": "0.1.2-canary.ac17c7f",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.ac17c7f",
+    "@astryxdesign/core": "0.1.2-canary.b6820d0",
+    "@astryxdesign/lab": "0.1.2-canary.b6820d0",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.b6820d0",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,9 +80,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.ac17c7f",
-    "@astryxdesign/lab": "0.1.2-canary.ac17c7f",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.ac17c7f",
+    "@astryxdesign/core": "0.1.2-canary.b6820d0",
+    "@astryxdesign/lab": "0.1.2-canary.b6820d0",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.b6820d0",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/src/api/component.mjs

@@ -11,48 +11,18 @@ 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'
@@ -161,13 +131,8 @@ export async function component(name, options = {}) {
         return {type: 'component.full', data: {[match[0]]: entries}};
       }
 
-      // 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}))},
-      };
+      // Default: brief — names only
+      return {type: 'component.list', data: {[match[0]]: match[1]}};
     }
 
     // All components — merge core + external packages with grouped subcategories
@@ -214,189 +179,43 @@ export async function component(name, options = {}) {
       return {type: 'component.full', data: result};
     }
 
-    // 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.
+    // Default: brief — names only (with externals merged in)
     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)) {
-          listData[`${group} (${ext.name})`] = members.map(n => ({
-            name: n,
-            package: ext.name,
-          }));
+          components[`${group} (${ext.name})`] = members;
         }
       } else {
+        // All ungrouped — single flat list under the package category
         const allComps = Object.values(grouped).flat().sort();
         if (allComps.length > 0) {
-          listData[`${ext.category} (${ext.name})`] = allComps.map(n => ({
-            name: n,
-            package: ext.name,
-          }));
+          components[`${ext.category} (${ext.name})`] = allComps;
         }
       }
     }
-    return {type: 'component.list', data: listData};
+    return {type: 'component.list', data: components};
   }
 
   // ── 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);
@@ -425,49 +244,11 @@ 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: withOwnership(docs, {package: ext.name, sourcePath: null}, dirName),
-      };
+      return {type: 'component.detail', data: docs};
     }
     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) {
@@ -493,10 +274,6 @@ 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);
@@ -504,8 +281,6 @@ export async function component(name, options = {}) {
       const extDocPath = findExternalComponentDoc(ext.docsDir, dirName);
       if (extDocPath) {
         readmePath = extDocPath;
-        resolvedOwnerPackage = ext.name;
-        resolvedSourcePath = null;
         break;
       }
     }
@@ -524,8 +299,6 @@ 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);
@@ -609,14 +382,7 @@ export async function component(name, options = {}) {
     if (props) {
       return {type: 'component.detail.props', data: matchingComponent.props || []};
     }
-    return {
-      type: 'component.detail',
-      data: withOwnership(
-        scoped,
-        {package: resolvedOwnerPackage, sourcePath: resolvedSourcePath},
-        dirName,
-      ),
-    };
+    return {type: 'component.detail', data: scoped};
   }
 
   if (props) {
@@ -624,12 +390,5 @@ export async function component(name, options = {}) {
     return {type: 'component.detail.props', data: p};
   }
 
-  return {
-    type: 'component.detail',
-    data: withOwnership(
-      docs,
-      {package: resolvedOwnerPackage, sourcePath: resolvedSourcePath},
-      resolvedName,
-    ),
-  };
+  return {type: 'component.detail', data: docs};
 }

package/src/api/discover.mjs

@@ -4,7 +4,7 @@
  * @file Programmatic API for the discover command.
  */
 
-import {Project} from '../lib/project.mjs';
+import {loadConfig} from '../lib/config.mjs';
 import {
   scanAllPackages,
   findComponentInPackages,
@@ -40,7 +40,7 @@ function validateDocs(docs) {
  */
 export async function discover(query, options = {}) {
   const {lang = null, zh = false} = options;
-  const project = await Project.load();
+  const config = await loadConfig();
   const toEntry = pkg => ({
     name: pkg.name,
     category: pkg.category,
@@ -50,21 +50,14 @@ export async function discover(query, options = {}) {
     displayName: pkg.displayName,
   });
 
-  // External packages come from configured integrations that declare a
-  // components root. Each becomes a scannable package keyed by its docsDir.
-  const explicitPackages = project.loadedIntegrations
-    .filter(integration => integration.components)
-    .map(integration => ({
-      name: integration.name,
-      version: integration.version,
-      category: integration.name,
-      docsDir: integration.components,
-    }));
-  if (explicitPackages.length === 0) {
+  const explicitPackages = (config.loadedIntegrations ?? [])
+    .map(integration => integration.package)
+    .filter(Boolean);
+  if (config.packages.length === 0 && explicitPackages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: false}};
   }
 
-  const packages = scanAllPackages([], explicitPackages);
+  const packages = scanAllPackages(config.packages, explicitPackages);
 
   if (packages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: true}};

package/src/api/doctor.mjs

@@ -27,7 +27,7 @@ import {createRequire} from 'node:module';
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../lib/node-version.mjs';
 import {CLI_ROOT, findCoreDir} from '../utils/paths.mjs';
 import {detectPackageManager} from '../utils/package-manager.mjs';
-import {findConfigPath, Project} from '../lib/project.mjs';
+import {findConfigPath, loadConfig} from '../lib/config.mjs';
 import {semverCompare} from '../utils/semver.mjs';
 
 const _require = createRequire(import.meta.url);
@@ -279,9 +279,8 @@ export async function checkConfig(ctx) {
     };
   }
 
-  // Project.load swallows nothing — it surfaces a genuine load failure — but
-  // the config check wants to report a bad default export precisely, so we
-  // re-import directly to surface a genuine load failure as a FAIL.
+  // loadConfig swallows errors and returns defaults, so re-import directly to
+  // surface a genuine load failure as a FAIL.
   try {
     const {pathToFileURL} = await import('node:url');
     const mod = await import(pathToFileURL(ctx.configPath).href);
@@ -292,9 +291,25 @@ export async function checkConfig(ctx) {
         label: 'astryx.config.mjs',
         status: 'fail',
         message: `astryx.config.mjs default export is not an object (got ${typeof config}).`,
-        fix: 'Export a default object from astryx.config.mjs, e.g. `export default { integrations: [] };`.',
+        fix: 'Export a default object from astryx.config.mjs, e.g. `export default { theme: "default" };`.',
       };
     }
+    // Validate that `packages`, if present, is a string or array of strings.
+    if (config?.packages !== undefined) {
+      const arr = Array.isArray(config.packages)
+        ? config.packages
+        : [config.packages];
+      const bad = arr.some(p => typeof p !== 'string');
+      if (bad) {
+        return {
+          id: 'config',
+          label: 'astryx.config.mjs',
+          status: 'fail',
+          message: 'astryx.config.mjs `packages` must be a string or array of strings.',
+          fix: 'Set `packages` to a path string or array of path strings.',
+        };
+      }
+    }
     return {
       id: 'config',
       label: 'astryx.config.mjs',
@@ -478,8 +493,8 @@ export async function runChecks(options = {}) {
   // Resolve a possible theme key from config (best-effort; never throws).
   let configTheme = null;
   try {
-    const project = await Project.load(cwd);
-    configTheme = project.config?.theme ?? null;
+    const loaded = await loadConfig(cwd);
+    configTheme = loaded?.theme ?? null;
   } catch {
     // Best-effort: a missing/invalid config leaves configTheme null.
   }

package/src/api/layout.mjs

@@ -25,14 +25,13 @@ import {expand} from '../lib/xle/expand.mjs';
 import {toCompact, toOutline} from '../lib/xle/print.mjs';
 import {buildRegistry, ALIAS_TABLE} from '../lib/xle/registry.mjs';
 import {discoverTemplates, stripTemplateAssetRefs} from './template.mjs';
-import {Project} from '../lib/project.mjs';
+import {loadConfig} from '../lib/config.mjs';
 
 /**
  * The catalog a `{hint}` can resolve to: template blocks (spliced inline) plus
- * any app-registered local components from astryx.config.mjs
- * `experimental.xle.components` (imported by name). App components are how XLE
- * reaches domain pieces — the KpiCard/chart/drawer set that the
- * @astryxdesign/core registry can't see.
+ * any app-registered local components from astryx.config.mjs `layout.components`
+ * (imported by name). App components are how XLE reaches domain pieces — the
+ * KpiCard/chart/drawer set that the @astryxdesign/core registry can't see.
  */
 async function loadBlocks(cwd) {
   const blocks = [];
@@ -43,20 +42,20 @@ async function loadBlocks(cwd) {
     // discovery is best-effort
   }
   try {
-    const project = await Project.load(cwd);
-    const components = project.config.experimental?.xle?.components ?? {};
+    const config = await loadConfig(cwd);
+    const components = config.layout?.components || {};
     for (const [name, spec] of Object.entries(components)) {
-      const importPath = spec.from;
+      const importPath = typeof spec === 'string' ? spec : spec.from;
       if (!importPath) continue;
       blocks.push({
         type: 'block',
         kind: 'component',
         dirName: name,
         name,
-        description: spec.description ?? '',
+        description: typeof spec === 'object' ? spec.description || '' : '',
         category: 'app',
         importPath,
-        isDefault: Boolean(spec.default),
+        isDefault: typeof spec === 'object' ? Boolean(spec.default) : false,
       });
     }
   } catch {
@@ -282,7 +281,7 @@ TEMPLATE REFERENCING  ({hint} pulls in real content — this is how XLE reaches
   {kpi-card}                   standalone reference (no wrapper element) — place a component directly
   {kpi-card}*4                 repeat a reference; the definition/import is emitted once
   app components               register local ones in astryx.config.mjs to import them by name:
-                                 export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}}}}}
+                                 export default {layout: {components: {KpiCard: '@/components/KpiCard'}}}
                                then {kpi-card} → import {KpiCard} + <KpiCard /> (kebab ↔ Pascal)
 
 STRUCTURE THE EXPANDER HANDLES

package/src/api/layout.test.mjs

@@ -196,14 +196,11 @@ describe('template referencing', () => {
 
   it('imports app-registered local components (the local-component bridge)', async () => {
     // Inside the workspace so @astryxdesign/core resolves; cleaned up after.
-    // A package.json beside the config makes Project.load resolve it as the
-    // sibling-of-nearest-package.json (the standard config resolution).
     const cwd = mkdtempSync(join(process.cwd(), '.xle-imp-test-'));
     try {
-      writeFileSync(join(cwd, 'package.json'), '{"name": "xle-imp-fixture"}\n');
       writeFileSync(
         join(cwd, 'astryx.config.mjs'),
-        `export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}, TimeRangePicker: {from: '@/components/TimeRangePicker'}}}}};\n`,
+        `export default {layout: {components: {KpiCard: '@/components/KpiCard', TimeRangePicker: {from: '@/components/TimeRangePicker'}}}};\n`,
       );
       const result = await layoutExpand('S[p6] > (G[c4 g4] > {kpi-card}*4) + {time-range-picker}', {
         name: 'Demo',