@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

package/api/doctor/doctor.type.d.mts

@@ -23,7 +23,7 @@ export type DoctorCheck = {
      */
     message: string;
     /**
-     * - Actionable remediation, present when status is not 'pass'.
+     * - Actionable remediation: always present on 'warn' and 'fail'; some 'info' checks carry one too.
      */
     fix?: string | undefined;
 };

package/api/doctor/doctor.type.mjs

@@ -19,7 +19,7 @@
  * @property {string} label - Human-readable check name.
  * @property {DoctorStatus} status
  * @property {string} message - One-line result summary.
- * @property {string} [fix] - Actionable remediation, present when status is not 'pass'.
+ * @property {string} [fix] - Actionable remediation: always present on 'warn' and 'fail'; some 'info' checks carry one too.
  */
 
 /**

package/api/gap-report/gap-report.doc.mjs

@@ -12,12 +12,16 @@ export const doc = {
   name: 'gapReport',
   namespace: 'cli/api',
   displayName: 'gapReport()',
-  summary: 'Route a design-system gap through the fan-out handler composition.',
+  summary:
+    'Report a missing or hard-to-use design-system capability to the package that owns it.',
   description:
-    'Creates a normalized gap report and fans it out to every effective handler: the project config handler first, then each loaded integration handler in config order, deduplicated by handle function identity. Each handler receives a structuredClone of the report and an AbortSignal, then runs in its own worker with a 30 s timeout and stdout redirected to stderr. A timed-out worker is terminated before the next handler starts, so process.exit, process.exitCode, and late continuations cannot affect the CLI process. A public handler requires confirmPublic per handler; internal handlers always run. When no handlers exist, a built-in GitHub/routed-only fallback runs. The aggregate response carries ordered deliveries with per-handler outcomes.',
+    'Sends a gap report to every configured handler: the project config handler first, then each integration handler in config order. ' +
+    'Each handler has 30 s to finish, and its output goes to stderr. Public handlers run only with confirmPublic; internal handlers always run. ' +
+    "With no handler, it files a GitHub issue for the owning package only with confirmPublic (without it nothing is sent), or returns the package's issues URL when that is not on GitHub. " +
+    'The report records whether an agent or a person ran it, and the response lists each handler outcome in order.',
   importPath: '@astryxdesign/cli/api',
   signature:
-    'gapReport(component?: string, options?: GapReportOptions): Promise<GapReportCategoriesResponse | GapReportReceiptResponse>',
+    'gapReport(component: string | undefined, options?: GapReportOptions): Promise<GapReportCategoriesResponse | GapReportReceiptResponse>',
   keywords: [
     'gap',
     'report',
@@ -56,13 +60,13 @@ export const doc = {
       name: 'options.package',
       type: 'string',
       description:
-        'Explicit owning package when automatic routing is ambiguous.',
+        'Package that owns the gap: @astryxdesign/core, or a loaded integration by package name or config entry. Overrides automatic owner routing; required when more than one package provides the component.',
     },
     {
       name: 'options.confirmPublic',
       type: 'boolean',
       description:
-        'Explicitly consent to invoking public handlers or creating a GitHub issue.',
+        'Allow public delivery: public handlers run, and with no handler a GitHub issue is filed through the gh CLI.',
       default: 'false',
     },
     {
@@ -77,6 +81,7 @@ export const doc = {
       type: 'string',
       description:
         'Directory used to load project config and component ownership.',
+      default: 'process.cwd()',
     },
   ],
   returns: [
@@ -87,17 +92,21 @@ export const doc = {
     {
       type: 'gap-report.file',
       description:
-        'An aggregate receipt with per-handler deliveries, filedCount/routedOnlyCount totals, and overall status.',
+        'Receipt: status (filed, partial, failed, routed_only, consent_required, skipped), package, issuesUrl, ordered deliveries (handlerType, handler, audience, status, url, message), filedCount, and routedOnlyCount.',
     },
   ],
   throws: [
+    {
+      code: 'ERR_MISSING_ARGUMENT',
+      when: 'component, category, or reason is missing, blank, or not a string (unless listCategories is true)',
+    },
     {
       code: 'ERR_UNKNOWN_CATEGORY',
       when: 'category is not one of the fixed gap-report values',
     },
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: 'a field value is invalid',
+      when: 'component is over 120 characters, category is over 80, reason is over 2000, or detail is not a string or is over 8000 characters',
     },
     {
       code: 'ERR_AMBIGUOUS_COMPONENT',
@@ -109,7 +118,7 @@ export const doc = {
     },
     {
       code: 'ERR_NOT_FOUND',
-      when: 'no handler and no issues URL available',
+      when: 'no report handler is configured and the owning package has no issues URL',
     },
   ],
   examples: [
@@ -122,8 +131,8 @@ export const doc = {
       code: "const receipt = await gapReport('Button', {category: 'missing_variant', reason: 'Need a compact size'});",
     },
     {
-      label: 'Confirm public filing',
-      code: "await gapReport('Button', {category: 'docs_gap', reason: 'Missing keyboard example', confirmPublic: true});",
+      label: 'Name the owning package',
+      code: "const receipt = await gapReport('Button', {category: 'docs_gap', reason: 'Missing keyboard example', package: '@astryxdesign/core'});",
     },
   ],
   command: 'gap-report',

package/api/hook/hook.doc.mjs

@@ -34,6 +34,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory to resolve @astryxdesign/core from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.list',
@@ -43,7 +44,8 @@ export const doc = {
     {
       name: 'options.category',
       type: 'string',
-      description: 'List only hooks in this category.',
+      description:
+        "List only the hooks in this category, a key of the unfiltered list such as 'Media' or 'Focus'.",
     },
     {
       name: 'options.params',
@@ -54,7 +56,8 @@ export const doc = {
       name: 'options.detail',
       type: "'full' | 'compact' | 'brief'",
       description: 'Detail level for list views.',
-      default: "'full' for a named hook, 'brief' for list views",
+      default:
+        "'full' for a named hook; 'brief' for lists (returned as data.detail: 'names')",
     },
     {
       name: 'options.lang',
@@ -104,7 +107,7 @@ export const doc = {
     },
     {
       label: 'Browse a category',
-      code: "await hook(undefined, {category: 'State', detail: 'compact'});",
+      code: "await hook(undefined, {category: 'Media', detail: 'compact'});",
     },
   ],
   command: 'hook',

package/api/index.d.mts

@@ -33,12 +33,14 @@ export * from "./gap-report/gap-report.type.mjs";
 export * from "./upgrade/upgrade.type.mjs";
 export * from "./init/init.type.mjs";
 export * from "./doctor/doctor.type.mjs";
+export * from "./layout/layout.type.mjs";
 export * from "./integration/integration-authoring.type.mjs";
 export * from "./integration/pack-check.type.mjs";
 export * from "./integration/validate-integration.type.mjs";
 export * from "./integration/authoring-checks.type.mjs";
 export type Logger = import("./logger.mjs").Logger;
 export { themeBuild, themeAdd, themeTemplate, themeList, themeListAvailable, themeTargets, themePaletteGenerate, generateTonalPalette, listThemes } from "./theme/theme.mjs";
+export { layoutExpand, layoutCheck, layoutGrammar } from "./layout/layout.mjs";
 export { integrationAdd, integrationAddAgentDoc, integrationAddCodemod, integrationAddComponent, integrationAddDoc, integrationAddTemplate } from "./integration/add-contribution.mjs";
 export { validateIntegration, summarizeIssues } from "./integration/validate-integration.mjs";
 export { integrationTemplateConflicts, integrationComponentConflicts, integrationDocConflicts } from "./integration/authoring-checks.mjs";

package/api/index.mjs

@@ -3,7 +3,7 @@
 /**
  * @file Programmatic API for the Astryx CLI.
  *
- * Every function returns the same { type, data } envelope that `xds --json` outputs.
+ * Every function returns the same { type, data } envelope that `astryx --json` outputs.
  * Errors throw AstryxError (with optional .suggestions).
  *
  * @example
@@ -44,6 +44,7 @@ export {gapReport} from './gap-report/gap-report.mjs';
 export {upgrade} from './upgrade/upgrade.mjs';
 export {init} from './init/init.mjs';
 export {doctor} from './doctor/doctor.mjs';
+export {layoutExpand, layoutCheck, layoutGrammar} from './layout/layout.mjs';
 export {
   integrationAdd,
   integrationAddAgentDoc,
@@ -92,6 +93,7 @@ export * from './gap-report/gap-report.type.mjs';
 export * from './upgrade/upgrade.type.mjs';
 export * from './init/init.type.mjs';
 export * from './doctor/doctor.type.mjs';
+export * from './layout/layout.type.mjs';
 export * from './integration/integration-authoring.type.mjs';
 export * from './integration/pack-check.type.mjs';
 export * from './integration/validate-integration.type.mjs';

package/api/init/init.doc.mjs

@@ -19,10 +19,9 @@ export const doc = {
     'Sets a project up with NO prompts, so it behaves identically for humans, ' +
     'agents, CI, and piped I/O. By default it installs the AGENTS.md/CLAUDE.md ' +
     'agent-docs cheat sheet, including guidance from configured integrations, and ' +
-    'prints getting-started guidance; `features` / ' +
-    '`all` add theme and page-building guidance and can scaffold a starter ' +
-    'template. With `removeAgents` it removes the managed agent-docs block ' +
-    'instead of installing.',
+    "prints getting-started guidance; `features` / `all` print only the chosen features' " +
+    'guidance instead (the theme feature also writes the annotated theme template). ' +
+    'With `removeAgents` it removes the managed agent-docs block instead of installing.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'init(options?: InitOptions, ctx?: {cwd?: string}): Promise<InitRunResponse | InitRemoveResponse>',
@@ -32,7 +31,7 @@ export const doc = {
       name: 'options.features',
       type: 'string',
       description:
-        'Comma-separated features to install: agents (agent docs), theme (writes the annotated theme.template.ts), template (page-template guidance).',
+        'Comma-separated features to install: agents (agent docs), theme (writes the annotated theme.template.ts), template (the page-building commands; writes a page only with templateName).',
     },
     {
       name: 'options.all',
@@ -47,7 +46,8 @@ export const doc = {
     {
       name: 'options.agent',
       type: 'string',
-      description: 'Agent preset: claude, cursor, codex, hermes, muse, all.',
+      description:
+        'Agent preset: claude, cursor, codex, hermes, muse, all. Used only when the agents feature runs.',
     },
     {
       name: 'options.agentDocsPath',
@@ -58,9 +58,14 @@ export const doc = {
       name: 'options.templateName',
       type: 'string',
       description:
-        'Scaffold a named page template (programmatic only; the CLI never sets it).',
+        'Scaffold this page template to src/pages/<name>/page.tsx. Used only when the template feature runs (features includes template, or all); otherwise ignored. Programmatic only; the CLI never sets it.',
+    },
+    {
+      name: 'ctx.cwd',
+      type: 'string',
+      description: 'Directory to set up.',
+      default: 'process.cwd()',
     },
-    {name: 'ctx.cwd', type: 'string', description: 'Directory to set up.'},
   ],
   returns: [
     {
@@ -71,13 +76,13 @@ export const doc = {
     {
       type: 'init.remove',
       description:
-        'Confirmation that the managed agent-docs block was removed (`data.removed: true`), returned when `removeAgents` is set.',
+        'Returned when `removeAgents` is set. `data.removed` is always true, even when no managed block was found.',
     },
   ],
   throws: [
     {
       code: 'ERR_UNKNOWN_AGENT',
-      when: '`agent` is not one of claude, cursor, codex, hermes, muse, all',
+      when: 'the agents feature runs (default mode, features includes agents, or all) and `agent` is not one of claude, cursor, codex, hermes, muse, all',
     },
     {
       code: 'ERR_UNKNOWN_FEATURE',
@@ -85,7 +90,7 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_TEMPLATE',
-      when: '`templateName` matches no bundled template',
+      when: 'the template feature runs and `templateName` matches no bundled template',
     },
     {
       code: 'ERR_FILE_EXISTS',
@@ -93,7 +98,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the template output path resolves outside cwd, for example through a symlinked src directory',
+      when: 'the template output path resolves outside cwd (for example through a symlinked src directory), or, with removeAgents, a managed agent-docs file resolves outside cwd through a symlink',
     },
   ],
   examples: [

package/api/integration/add-theme.mjs

@@ -24,6 +24,10 @@ import {
 import {loadManifestObject} from '../../foundation/integrations/integrations.mjs';
 import {themeDescriptorSource} from '../../foundation/integrations/theme-descriptor.mjs';
 import {assertContributionVisible} from '../../foundation/integrations/contribution-inventory.mjs';
+import {
+  themesCliProblem,
+  withDocsTreeCli,
+} from '../../foundation/integrations/cli-requirement.mjs';
 import {
   applyWrites,
   findPackageDir,
@@ -233,11 +237,28 @@ export async function integrationAddTheme(name, options = {}) {
       createOnly: true,
     },
   ];
-  const packageUpdate = packageJsonUpdate(
+  let packageUpdate = packageJsonUpdate(
     packageFile,
     rootPath,
     path.basename(manifestFile),
   );
+  // A CLI older than the one that reads typed theme descriptors rejects the
+  // themes root and withholds the package's themes and docs. Declare the CLI
+  // that reads them as a peer, so an older one is flagged at install instead.
+  {
+    const expectedOriginal =
+      packageUpdate?.expectedOriginal ?? fs.readFileSync(packageFile);
+    const text = packageUpdate?.contents ?? expectedOriginal.toString('utf-8');
+    const current = JSON.parse(text);
+    if (themesCliProblem(current) != null) {
+      packageUpdate = {
+        contents:
+          JSON.stringify(withDocsTreeCli(current), null, 2) +
+          (text.endsWith('\n') ? '\n' : ''),
+        expectedOriginal,
+      };
+    }
+  }
   if (packageUpdate != null) {
     plans.push({
       path: packageFile,

package/api/integration/add-theme.test.mjs

@@ -77,6 +77,40 @@ describe('integrationAddTheme', () => {
     expect((await validateLocalIntegration(tmpDir)).issues).toEqual([]);
   });
 
+  it('declares the optional CLI peer that reads typed theme descriptors', async () => {
+    setup({includeFiles: false});
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.files).toContain('package.json');
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8'),
+    );
+    expect(pkg.peerDependencies).toEqual({'@astryxdesign/cli': '>=0.7.0'});
+    expect(pkg.peerDependenciesMeta).toEqual({
+      '@astryxdesign/cli': {optional: true},
+    });
+  });
+
+  it('keeps a CLI peer that already reads typed theme descriptors', async () => {
+    const pkg = {
+      name: '@acme/themes',
+      version: '1.0.0',
+      peerDependencies: {'@astryxdesign/cli': '^0.7.2'},
+    };
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify(pkg, null, 2)}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'astryx.integration.mjs'),
+      'export default {};\n',
+    );
+    const result = await integrationAddTheme('ocean', {cwd: tmpDir});
+    expect(result.data.files).not.toContain('package.json');
+    expect(
+      JSON.parse(fs.readFileSync(path.join(tmpDir, 'package.json'), 'utf-8')),
+    ).toEqual(pkg);
+  });
+
   it('dry-runs the identical receipt without writing anything', async () => {
     setup();
     const beforeManifest = fs.readFileSync(

package/api/integration/authoring-checks.mjs

@@ -368,11 +368,11 @@ export async function integrationDocConflicts(pkg, options = {}) {
   // and placed guides this package adds to the docs tree, and every link in
   // its docs (spec:AST-046, spec:AST-047).
   if (errors.length === 0) {
-    for (const message of await packageDocsProblems(
+    for (const {severity, message} of await packageDocsProblems(
       /** @type {{name: string}} */ (resolved.integration),
       discovered,
     )) {
-      issues.push({code: 'invalid_doc_graph', severity: 'warning', message});
+      issues.push({code: 'invalid_doc_graph', severity, message});
     }
 
     // A reference block includes content rather than linking to it, so one

package/api/integration/integrationPackCheck.doc.mjs

@@ -7,13 +7,13 @@ export const doc = {
   name: 'integrationPackCheck',
   namespace: 'cli/api',
   displayName: 'integrationPackCheck()',
-  summary: 'Prove an integration package survives npm packing.',
+  summary: 'Check an integration package the way npm will publish it.',
   description:
     "Validates the local integration, runs the package lifecycle, packs with npm, checks required files against npm's authoritative tarball list, extracts the real tarball into a scratch consumer, compares local and packed contribution inventories, and resolves every packed component through its documented public import to verify that module exports the component. A package that ships a namespace doc or a placed guide, or has a template that sets `replaces`, fails unless its `@astryxdesign/cli` peer range admits only CLIs that read them.",
   importPath: '@astryxdesign/cli/api',
   signature:
     'integrationPackCheck(options?: IntegrationPackCheckOptions): Promise<IntegrationPackCheckResponse>',
-  keywords: ['integration', 'pack', 'check', 'publish', 'tarball', 'consumer'],
+  keywords: ['verify', 'pack', 'publish', 'tarball', 'consumer'],
   params: [
     {
       name: 'options.cwd',
@@ -31,6 +31,6 @@ export const doc = {
   examples: [
     {label: 'Check the local package', code: 'await integrationPackCheck();'},
   ],
-  command: 'integration pack',
+  command: 'integration verify',
   related: ['integrationAdd', 'validateIntegration'],
 };

package/api/integration/pack-check.lifecycle-output.test.mjs

@@ -24,6 +24,8 @@ function writeThemePackage(scripts) {
         name: '@acme/widgets',
         version: '1.0.0',
         files: ['astryx.integration.mjs', 'themes'],
+        peerDependencies: {'@astryxdesign/cli': '>=0.7.0'},
+        peerDependenciesMeta: {'@astryxdesign/cli': {optional: true}},
         scripts,
       },
       null,

package/api/integration/pack-check.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file `astryx integration pack --check` — verify an integration package is
+ * @file `astryx integration verify` — verify an integration package is
  * ready to publish by cross-referencing its declared contributions against the
  * real npm tarball.
  *
@@ -30,8 +30,13 @@ import {resolvePackageDir} from '../../foundation/integrations/integrations.mjs'
 import {
   docsTreeCliProblem,
   replacesCliProblem,
+  sectionIdsCliProblem,
+  themesCliProblem,
 } from '../../foundation/integrations/cli-requirement.mjs';
-import {discoverIntegrationDocs} from '../../foundation/discovery/docs-discovery.mjs';
+import {
+  discoverIntegrationDocs,
+  loadTopicModule,
+} from '../../foundation/discovery/docs-discovery.mjs';
 import {
   discoverIntegrationComponents,
   resolveIntegrationImportPath,
@@ -333,6 +338,23 @@ function moduleExportsName(file, exportName, seen = new Set()) {
   return found;
 }
 
+/**
+ * Whether any of these doc files has a section that sets `id`.
+ * @param {string[]} files
+ * @returns {Promise<boolean>}
+ */
+async function setsSectionIds(files) {
+  for (const file of files) {
+    if (typeof file !== 'string') continue;
+    const doc = /** @type {any} */ (await loadTopicModule(file).catch(() => null));
+    const sections = Array.isArray(doc?.sections) ? doc.sections : [];
+    if (sections.some((/** @type {any} */ section) => section?.id != null)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Resolve package specifiers through Node's real ESM resolver from the scratch
  * consumer. Resolution does not execute the target module, so source `.tsx`
@@ -625,19 +647,31 @@ export async function integrationPackCheck(options = {}) {
   // (spec:AST-046 FR11): an older CLI can hide every doc topic the package
   // ships, so the declared CLI range must admit only CLIs that read it.
   if (loaded.docs) {
-    const {namespaces, guides} = await discoverIntegrationDocs(loaded).catch(
-      () => ({namespaces: [], guides: []}),
-    );
+    const {records, namespaces, guides} = await discoverIntegrationDocs(
+      loaded,
+    ).catch(() => ({records: [], namespaces: [], guides: []}));
     const problem =
       namespaces.length > 0 || guides.length > 0
         ? docsTreeCliProblem(pkg)
         : null;
     if (problem != null) {
       issues.push(error('docs_tree_needs_cli', problem));
+    } else if (
+      await setsSectionIds([
+        ...records.map(record => record.path),
+        ...guides.map(guide => /** @type {any} */ (guide.ref).topicFile),
+      ])
+    ) {
+      // A section `id` is also a field an older CLI rejects, hiding the
+      // package's doc topics; the same peer range fixes both.
+      const idProblem = sectionIdsCliProblem(pkg);
+      if (idProblem != null) {
+        issues.push(error('section_ids_need_cli', idProblem));
+      }
     }
   }
   // A template that sets `replaces` needs a CLI that reads the field
-  // (spec:AST-035): an older CLI withholds the package's templates and docs.
+  // (spec:AST-035): an older CLI drops that template and hides the package's docs.
   if (loaded.templates) {
     const found = await discoverIntegrationTemplatesForOne(loaded).catch(
       () => ({templates: [], errors: []}),
@@ -650,6 +684,12 @@ export async function integrationPackCheck(options = {}) {
     const problem = setsReplaces ? replacesCliProblem(pkg) : null;
     if (problem != null) issues.push(error('replaces_needs_cli', problem));
   }
+  // A theme needs a CLI that reads typed theme descriptors: an older CLI
+  // rejects the themes root and withholds the package's themes and docs.
+  if (localIdentities.themes.length > 0) {
+    const problem = themesCliProblem(pkg);
+    if (problem != null) issues.push(error('themes_need_cli', problem));
+  }
 
   // Temp resources — always cleaned up
   const tgzTmpDir = fs.mkdtempSync(
@@ -682,6 +722,14 @@ export async function integrationPackCheck(options = {}) {
     // package's already-installed dependencies. The unique suffix makes
     // concurrent checks independent.
     scratchBase = fs.mkdtempSync(path.join(packageDir, '.astryx-pack-check-'));
+    // The consumer's own package.json makes it the package scope for its
+    // imports. Without one, Node resolves the package's name through the
+    // SOURCE package.json (self-reference), so an export target left out of
+    // the tarball would still resolve.
+    fs.writeFileSync(
+      path.join(scratchBase, 'package.json'),
+      `${JSON.stringify({name: 'astryx-verify-consumer', private: true})}\n`,
+    );
 
     // Cross-reference file inventory vs pack list
     if (!packResult.packedPaths.has(fileInv.manifest)) {

package/api/integration/pack-check.test.mjs

@@ -36,6 +36,8 @@ function writePackage({
   scripts,
 } = {}) {
   const pkg = {name, version};
+  // A theme needs a CLI that reads typed theme descriptors.
+  if (themes) pkg.peerDependencies = {'@astryxdesign/cli': '>=0.7.0'};
   if (files !== undefined) pkg.files = files;
   if (scripts !== undefined) pkg.scripts = scripts;
   fs.writeFileSync(
@@ -94,6 +96,30 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('fails a package that ships a theme on a CLI range that cannot read it', async () => {
+    writePackage({files: ['astryx.integration.mjs', 'themes']});
+    const pkgFile = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    delete pkg.peerDependencies;
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+
+    const missing = await integrationPackCheck({cwd: tmpDir});
+    expect(missing.data.packable).toBe(false);
+    expect(missing.data.issues).toContainEqual(
+      expect.objectContaining({
+        code: 'themes_need_cli',
+        message: expect.stringContaining('ships a theme'),
+      }),
+    );
+
+    pkg.peerDependencies = {'@astryxdesign/cli': '^0.6.3'};
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    const old = await integrationPackCheck({cwd: tmpDir});
+    expect(old.data.issues).toContainEqual(
+      expect.objectContaining({code: 'themes_need_cli'}),
+    );
+  });
+
   it('fails when a theme entry omits its inferred runtime export', async () => {
     writePackage({files: ['astryx.integration.mjs', 'themes']});
     fs.writeFileSync(
@@ -193,6 +219,39 @@ describe('integrationPackCheck', () => {
     );
   });
 
+  it('resolves public imports in the packed package, not the source', async () => {
+    // The root export's target is left out of `files`: the source package
+    // resolves it, but an app that installs the tarball cannot.
+    fs.writeFileSync(
+      path.join(tmpDir, 'package.json'),
+      `${JSON.stringify({
+        name: '@acme/widgets',
+        version: '1.0.0',
+        files: ['astryx.integration.mjs'],
+        exports: {'.': './index.mjs'},
+      })}\n`,
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'index.mjs'),
+      "export {AcmeWidget} from './components/AcmeWidget.tsx';\n",
+    );
+    await integrationAddComponent('AcmeWidget', {cwd: tmpDir});
+    const docFile = path.join(tmpDir, 'components', 'AcmeWidget.doc.mjs');
+    const doc = fs.readFileSync(docFile, 'utf-8');
+    expect(doc).toContain('@acme/widgets/components/AcmeWidget');
+    fs.writeFileSync(
+      docFile,
+      doc.replace('@acme/widgets/components/AcmeWidget', '@acme/widgets'),
+    );
+
+    const result = await integrationPackCheck({cwd: tmpDir});
+
+    expect(result.data.packable).toBe(false);
+    expect(result.data.issues).toContainEqual(
+      expect.objectContaining({code: 'component_export_missing'}),
+    );
+  });
+
   it('fails when packed template source is hidden by package exports', async () => {
     writePackage({
       manifest: "export default {templates: './templates'};\n",
@@ -336,6 +395,37 @@ describe('integrationPackCheck', () => {
     expect(await codes()).not.toContain('docs_tree_needs_cli');
   }, 120_000);
 
+  it('fails a package whose doc section sets id on a CLI range that rejects the field', async () => {
+    writePackage({manifest: "export default {docs: './docs'};\n", themes: false});
+    fs.mkdirSync(path.join(tmpDir, 'docs'), {recursive: true});
+    const topic = (/** @type {string} */ section) =>
+      `export default {type: 'generic', name: 'notes', title: 'Notes', description: 'Notes.', sections: [${section}]};\n`;
+    const file = path.join(tmpDir, 'docs', 'notes.doc.mjs');
+    const codes = async () =>
+      (await integrationPackCheck({cwd: tmpDir})).data.issues.map(
+        (/** @type {{code: string}} */ issue) => issue.code,
+      );
+    fs.writeFileSync(
+      file,
+      topic("{title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}"),
+    );
+    expect(await codes()).not.toContain('section_ids_need_cli');
+    // A fresh file name: the module loader caches a path once it is imported.
+    fs.rmSync(file);
+    fs.writeFileSync(
+      path.join(tmpDir, 'docs', 'notes-with-ids.doc.mjs'),
+      topic(
+        "{id: 'take-notes', title: 'Take notes', content: [{type: 'prose', text: 'Notes.'}]}",
+      ),
+    );
+    expect(await codes()).toContain('section_ids_need_cli');
+    const pkgFile = path.join(tmpDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf-8'));
+    pkg.peerDependencies = {'@astryxdesign/cli': '>=0.7.0'};
+    fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+    expect(await codes()).not.toContain('section_ids_need_cli');
+  }, 120_000);
+
   it('fails a package with a template that sets replaces on a CLI range that rejects the field', async () => {
     writePackage({manifest: "export default {templates: './templates'};\n", themes: false});
     fs.mkdirSync(path.join(tmpDir, 'templates'), {recursive: true});

package/api/integration/pack-check.type.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Colocated types for `astryx integration pack --check`.
+ * @file Colocated types for `astryx integration verify`.
  */
 
 /**

package/api/json/assertResponse.doc.mjs

@@ -49,7 +49,7 @@ export const doc = {
   throws: [
     {
       code: 'Error',
-      when: 'the CLI returned an error envelope (the CLI message is rethrown), or the response `type` is not expectedType',
+      when: 'a plain Error with no code: the CLI returned an error envelope (its message is rethrown; code and suggestions are dropped), or the response `type` is not expectedType',
     },
   ],
   examples: [