@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/api/docs/integrationDocs.test.mjs

@@ -243,7 +243,7 @@ describe('integration-contributed topics', () => {
       const english = await docs('theme', undefined, {full: true});
       const englishTitles = english.data.sections.map(section => section.title);
       expect(englishTitles).toEqual(
-        expect.arrayContaining(['Quick Start', 'Theme Props']),
+        expect.arrayContaining(['Available Themes', 'Theme Props']),
       );
       scaffold({
         'theme-internal.doc.mjs': topic({
@@ -251,9 +251,9 @@ describe('integration-contributed topics', () => {
           extends: 'theme',
           sections: [
             {
-              id: 'acme-quick-start',
-              title: 'Quick Start',
-              content: [{type: 'prose', text: 'Acme quick start.'}],
+              id: 'acme-available-themes',
+              title: 'Available Themes',
+              content: [{type: 'prose', text: 'Acme themes.'}],
             },
             {
               title: 'Theme Props',
@@ -271,7 +271,7 @@ describe('integration-contributed topics', () => {
       expect(extended.data.sections).toHaveLength(base.data.sections.length);
       expect(
         extended.data.sections.filter(
-          section => section.id === 'acme-quick-start',
+          section => section.id === 'acme-available-themes',
         ),
       ).toHaveLength(1);
       expect(
@@ -305,6 +305,28 @@ describe('integration-contributed topics', () => {
     });
   }, SLOW);
 
+  it('ranks the topics that match every word of the query first', async () => {
+    // Dozens of CLI docs match `integration` alone, by name or in a code
+    // tick; the topics that hold both words, this one and the CLI's own
+    // troubleshooting guide, must still come first.
+    scaffold({
+      'troubleshooting.doc.mjs': topic({
+        name: 'troubleshooting',
+        title: 'Troubleshooting',
+        description: 'What to check when an integration does not load.',
+      }),
+    });
+    const {data} = await search('troubleshoot integration', {cwd: tmpDir, type: 'doc'});
+    const top = data.results.slice(0, 2).map(result => result.name);
+    // This topic, and the CLI's own troubleshooting guide wherever the tree
+    // places it.
+    expect(top).toContain('troubleshooting');
+    expect(
+      top.some(name => /^cli\/integrations\/(?:.+\/)?troubleshooting$/.test(name)),
+      top.join(', '),
+    ).toBe(true);
+  }, SLOW);
+
   it("falls back to the CLI's own topics when the project config is unreadable", async () => {
     scaffold({'deploying.doc.mjs': topic()}, {config: 'export default {integrations: 42};\n'});
     const catalog = await loadDocsCatalog(tmpDir);

package/api/doctor/doctor.d.mts

@@ -257,15 +257,20 @@ export type DoctorContext = {
      * could not be built, when it could not.
      */
     docsCatalogError?: string | null | undefined;
-    /**
-     * Combined project-level integration issues, including cross-package template replacement warnings.
-     */
     integrationIssues?: {
         package: string;
         code: string;
         severity: "warning" | "error";
         message: string;
     }[] | null | undefined;
+    /**
+     * installed dependencies whose integration manifest could not be loaded
+     * Combined project-level integration issues, including cross-package template replacement warnings.
+     */
+    autolinkFailures?: {
+        spec: string;
+        error: string;
+    }[] | null | undefined;
     /**
      * - Error thrown while resolving the config
      * path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.

package/api/doctor/doctor.doc.mjs

@@ -13,14 +13,18 @@ export const doc = {
   name: 'doctor',
   namespace: 'cli/api',
   displayName: 'doctor()',
-  summary: 'Read-only project + environment health check.',
+  summary:
+    "Check a project's Astryx setup and get a pass/warn/fail report per check. Use it as a CI gate or before debugging a broken install.",
   description:
-    'Runs a series of side-effect-free diagnostics: Node version, ' +
+    'Runs a series of diagnostics: Node version, ' +
     '@astryxdesign/core install and version alignment with the CLI, installed ' +
     'themes and wiring, astryx.config validity, integrations linked from ' +
-    'package.json without a config entry, agent docs, core peer ' +
-    'dependencies, and the detected package manager, and returns a structured ' +
-    'report. It only reads (never installs, writes, or mutates), so it is safe ' +
+    'package.json without a config entry, core peer dependencies, ' +
+    'integration provider identity and contribution issues, agent docs, the ' +
+    'detected package manager, and the health of the docs the CLI reads (authoring ' +
+    'and CLI docs, the docs tree, doc size), and returns a structured ' +
+    'report. It only reads (never installs, writes, or mutates), apart from ' +
+    "importing astryx.config, which runs that file's top-level code, so it is safe " +
     'as a CI gate and for agents to invoke.',
   importPath: '@astryxdesign/cli/api',
   signature: 'doctor(options?: DoctorOptions): Promise<DoctorResponse>',
@@ -29,18 +33,23 @@ export const doc = {
     {
       name: 'options.cwd',
       type: 'string',
-      description: 'Directory to diagnose.',
+      description:
+        'Directory to diagnose. A missing directory is not an error; it shows up in the checks (e.g. core-installed: fail).',
+      default: 'process.cwd()',
     },
   ],
   returns: [
     {
       type: 'doctor',
       description:
-        'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass`; plus `data.summary` with counts per status.',
+        'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and an optional `fix` (always present on `warn` and `fail`; some `info` checks carry one too); plus `data.summary` with counts per status.',
     },
   ],
   examples: [
-    {label: 'Run diagnostics', code: 'const r = await doctor();'},
+    {
+      label: 'Fail a CI step on any failed check',
+      code: 'const r = await doctor();\nif (r.data.summary.fail > 0) process.exitCode = 1;',
+    },
     {
       label: 'Diagnose a directory',
       code: "await doctor({cwd: '/path/to/app'});",

package/api/doctor/doctor.mjs

@@ -26,7 +26,11 @@ import * as path from 'node:path';
 import {MIN_NODE_VERSION, isNodeVersionSupported} from '../../foundation/env/node-version.mjs';
 import {CLI_ROOT, findCoreDir, findInstalledPackage} from '../../foundation/fs/paths.mjs';
 import {explainPackageManager, getCliInvocation} from '../../foundation/env/package-manager.mjs';
-import {findConfigPath, Project} from '../../foundation/config/project.mjs';
+import {
+  findConfigPath,
+  Project,
+  providerLedgerOf,
+} from '../../foundation/config/project.mjs';
 import {DocsCatalog} from '../../foundation/discovery/docs-discovery.mjs';
 import {buildDocsIndexData} from '../../foundation/discovery/docs-section-key.mjs';
 import {
@@ -76,6 +80,8 @@ import {semverCompare, isValidSemver, satisfiesRange} from '../../foundation/env
  * @property {string|null} [docsCatalogError] - Why the project's docs catalog
  *   could not be built, when it could not.
  * @property {Array<{package: string, code: string, severity: 'warning'|'error', message: string}>|null} [integrationIssues]
+ * @property {Array<{spec: string, error: string}>|null} [autolinkFailures]
+ *   installed dependencies whose integration manifest could not be loaded
  *   Combined project-level integration issues, including cross-package template replacement warnings.
  * @property {Error|null} [configError] - Error thrown while resolving the config
  *   path (e.g. multiple config files present), surfaced by checkConfig as a FAIL.
@@ -417,6 +423,9 @@ export function checkImplicitIntegrations(ctx) {
   const implicit = ctx.integrations.filter(
     integration => integration.__autolinked,
   );
+  // A dependency whose manifest cannot be loaded leaves no loaded record, so
+  // without this line doctor would say no dependency ships a manifest at all.
+  const unreadable = describeUnreadableManifests(ctx.autolinkFailures ?? []);
 
   if (implicit.length === 0) {
     return {
@@ -424,9 +433,12 @@ export function checkImplicitIntegrations(ctx) {
       label,
       status: 'info',
       message:
-        ctx.integrations.length > 0
+        (ctx.integrations.length > 0
           ? 'None — every loaded integration is named in astryx.config.'
-          : 'None — no installed dependency ships an astryx.integration.* manifest.',
+          : unreadable
+            ? 'None loaded.'
+            : 'None — no installed dependency ships an astryx.integration.* manifest.') +
+        unreadable,
     };
   }
 
@@ -439,11 +451,25 @@ export function checkImplicitIntegrations(ctx) {
       integration.__spec && integration.__spec !== integration.name
         ? ` (declared as "${integration.__spec}")`
         : '';
-    const roots = ['components', 'templates', 'themes', 'docs', 'codemods'].filter(
+    // A declared root counts only when it exists: the manifest's keys are a
+    // claim, and `integration-issues` reports the ones that are not true.
+    const declared = ['components', 'templates', 'themes', 'docs', 'codemods'].filter(
       root => integration[/** @type {'components'} */ (root)],
     );
+    const missing = declared.filter(root => {
+      const dir = integration[/** @type {'components'} */ (root)];
+      if (typeof dir !== 'string') return false;
+      const base =
+        typeof integration.__packageDir === 'string'
+          ? integration.__packageDir
+          : (ctx.cwd ?? process.cwd());
+      return !fs.existsSync(path.isAbsolute(dir) ? dir : path.resolve(base, dir));
+    });
+    const roots = declared.filter(root => !missing.includes(root));
     const contributes = roots.length > 0 ? roots.join(', ') : 'nothing';
-    return `${integration.name}${version}${alias} from ${integration.__dependencyField}, contributing ${contributes}`;
+    const absent =
+      missing.length > 0 ? ` (declared ${missing.join(', ')} missing on disk)` : '';
+    return `${integration.name}${version}${alias} from ${integration.__dependencyField}, contributing ${contributes}${absent}`;
   });
 
   const plural = implicit.length === 1 ? '' : 's';
@@ -453,7 +479,8 @@ export function checkImplicitIntegrations(ctx) {
     status: 'info',
     message:
       `${implicit.length} integration${plural} loaded from installed ` +
-      `dependencies with no astryx.config entry: ${described.join('; ')}.`,
+      `dependencies with no astryx.config entry: ${described.join('; ')}.` +
+      unreadable,
     fix:
       'Nothing to fix. Keep these dependencies installed. The CLI links them ' +
       'from package.json, so an unused-dependency check that looks only for ' +
@@ -462,6 +489,30 @@ export function checkImplicitIntegrations(ctx) {
   };
 }
 
+/**
+ * The sentence `implicit-integrations` adds for dependencies whose manifest
+ * could not be loaded, or '' when there are none. Still informational: the
+ * package is a dependency's own bug, which `doctor integration validate`
+ * diagnoses, but doctor must not report it as absent.
+ * @param {Array<{spec: string, error: string}>} failures
+ * @returns {string}
+ */
+function describeUnreadableManifests(failures) {
+  if (failures.length === 0) return '';
+  const one = failures.length === 1;
+  const listed = failures
+    .map(({spec, error}) => {
+      const reason = String(error).split('\n')[0].slice(0, 160);
+      return `${spec} (${reason})`;
+    })
+    .join('; ');
+  return (
+    ` ${failures.length} installed ${one ? 'dependency ships' : 'dependencies ship'} ` +
+    `an astryx.integration.* manifest that could not be loaded, so ${one ? 'it contributes' : 'they contribute'} ` +
+    `nothing: ${listed}. Run \`astryx doctor integration validate <package>\` for details.`
+  );
+}
+
 /**
  * Check 7 — agent docs exist and contain the Astryx section markers.
  * @param {DoctorContext} ctx
@@ -738,12 +789,26 @@ export function checkProviderIdentity(ctx) {
     integration =>
       integration.providerId != null && integration.__loadError == null,
   ).length;
+  // An integration that could not be read has no provider ID to check, so the
+  // count above is not a complete survey. Say so instead of counting silently.
+  const unread = ctx.integrations.filter(
+    integration => integration.__loadError != null,
+  ).length;
+  const unreadNote =
+    unread === 0
+      ? ''
+      : unread === 1
+        ? ' 1 loaded integration could not be read, so its provider ID is unknown.'
+        : ` ${unread} loaded integrations could not be read, so their provider IDs are unknown.`;
   if (count === 0) {
     return {
       id,
       label,
       status: 'info',
-      message: 'None — no loaded integration has a provider identity.',
+      message:
+        (unread === 0
+          ? 'None — no loaded integration has a provider identity.'
+          : 'No readable integration has a provider identity.') + unreadNote,
     };
   }
   return {
@@ -751,9 +816,10 @@ export function checkProviderIdentity(ctx) {
     label,
     status: 'pass',
     message:
-      count === 1
+      (count === 1
         ? '1 loaded integration has its own provider ID.'
-        : `${count} loaded integrations each have their own provider ID.`,
+        : `${count} loaded integrations each have their own provider ID.`) +
+      unreadNote,
   };
 }
 
@@ -1198,11 +1264,25 @@ export async function runChecks(options = {}) {
   let docsCatalogError = null;
   /** @type {Array<{package: string, code: string, severity: 'warning'|'error', message: string}>|null} */
   let integrationIssues = null;
+  /** @type {Array<{spec: string, error: string}>|null} */
+  let autolinkFailures = null;
   try {
     const project = await Project.load(cwd);
     configTheme =
       /** @type {{theme?: string}} */ (project.config ?? {}).theme ?? null;
     integrations = project.loadedIntegrations;
+    // An installed dependency whose manifest cannot be loaded is kept out of
+    // loadedIntegrations on purpose. The provider ledger still records it.
+    autolinkFailures = [...providerLedgerOf(project).values()]
+      .filter(
+        entry =>
+          entry.outcome === 'load-failed' &&
+          entry.candidate.source === 'autolinked',
+      )
+      .map(entry => ({
+        spec: entry.candidate.spec ?? entry.label,
+        error: entry.error ?? 'its manifest could not be loaded',
+      }));
     try {
       docsCatalog = await project.docs();
       docsCatalogIssues = (await project.issues()).filter(
@@ -1229,6 +1309,7 @@ export async function runChecks(options = {}) {
     docsCatalogIssues,
     docsCatalogError,
     integrationIssues,
+    autolinkFailures,
     configError,
   };
 

package/api/doctor/doctor.test.mjs

@@ -354,16 +354,31 @@ describe('checkImplicitIntegrations', () => {
   });
 
   it('names the package, the field, and what it contributes', () => {
-    const c = checkImplicitIntegrations({
-      integrations: [
-        autolinked({templates: '/abs/templates', themes: '/abs/themes'}),
-      ],
-    });
-    expect(c.message).toContain('@acme/widgets@1.0.0');
-    expect(c.message).toContain('from dependencies');
-    expect(c.message).toContain(
-      'contributing components, templates, themes',
-    );
+    // Roots count only when they exist, so this one gives them real folders.
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-implicit-'));
+    try {
+      const dir = name => {
+        fs.mkdirSync(path.join(root, name));
+        return path.join(root, name);
+      };
+      const c = checkImplicitIntegrations({
+        integrations: [
+          autolinked({
+            components: dir('components'),
+            templates: dir('templates'),
+            themes: dir('themes'),
+          }),
+        ],
+      });
+      expect(c.message).toContain('@acme/widgets@1.0.0');
+      expect(c.message).toContain('from dependencies');
+      expect(c.message).toContain(
+        'contributing components, templates, themes',
+      );
+      expect(c.message).not.toContain('missing on disk');
+    } finally {
+      fs.rmSync(root, {recursive: true, force: true});
+    }
   });
 
   it('names the declared key too when an npm alias makes them differ', () => {
@@ -906,3 +921,100 @@ describe('checkDocsProgressiveDisclosure languages', () => {
     expect(c.message).not.toMatch(/deploying overview:/);
   });
 });
+
+describe('doctor says what it could not check', () => {
+  const CORE = {
+    'node_modules/@astryxdesign/core/package.json': JSON.stringify({
+      name: '@astryxdesign/core',
+      version: '0.6.3',
+    }),
+  };
+
+  /** Installed dependency whose manifest declares roots that do not exist. */
+  const dangling = {
+    'node_modules/@acme/dangling/package.json': JSON.stringify({
+      name: '@acme/dangling',
+      version: '2.0.0',
+    }),
+    'node_modules/@acme/dangling/astryx.integration.mjs':
+      "export default {providerId: 'acme-dangling', components: './components', templates: './templates', docs: './docs'};\n",
+  };
+
+  /** Installed dependency whose manifest cannot be parsed at all. */
+  const broken = {
+    'node_modules/@acme/broken/package.json': JSON.stringify({
+      name: '@acme/broken',
+      version: '1.0.0',
+    }),
+    'node_modules/@acme/broken/astryx.integration.mjs':
+      'export default {  this is not valid javascript ((\n',
+  };
+
+  /** @param {Record<string, string>} extra @param {string[]} deps */
+  const project = (extra, deps) =>
+    mkProject({
+      'package.json': JSON.stringify({
+        name: 'consumer',
+        version: '1.0.0',
+        dependencies: Object.fromEntries(
+          ['@astryxdesign/core', ...deps].map(d => [d, '1.0.0']),
+        ),
+      }),
+      ...CORE,
+      ...extra,
+    });
+
+  // An unparseable manifest is kept out of the loaded set on purpose, and
+  // doctor used to report that no installed dependency ships a manifest.
+  it('names an installed dependency whose manifest cannot be loaded', async () => {
+    const report = (await doctor({cwd: project(broken, ['@acme/broken'])})).data;
+    const check = report.checks.find(c => c.id === 'implicit-integrations');
+
+    expect(check.status).toBe('info');
+    expect(check.message).toContain('@acme/broken');
+    expect(check.message).toContain('could not be loaded');
+    expect(check.message).not.toContain('no installed dependency ships');
+    expect(report.summary.fail).toBe(0);
+  }, SLOW);
+
+  it('does not claim contributions from roots that are missing on disk', async () => {
+    const report = (await doctor({cwd: project(dangling, ['@acme/dangling'])}))
+      .data;
+    const implicit = report.checks.find(c => c.id === 'implicit-integrations');
+    const issues = report.checks.find(c => c.id === 'integration-issues');
+
+    expect(implicit.message).toContain('contributing nothing');
+    expect(implicit.message).toContain('missing on disk');
+    expect(implicit.message).not.toContain('contributing components');
+    expect(issues.status).toBe('warn');
+    expect(issues.message).toContain('@acme/dangling');
+  }, SLOW);
+
+  it('still says no dependency ships a manifest when none does', async () => {
+    const report = (await doctor({cwd: project({}, [])})).data;
+    const check = report.checks.find(c => c.id === 'implicit-integrations');
+
+    expect(check.message).toBe(
+      'None — no installed dependency ships an astryx.integration.* manifest.',
+    );
+  }, SLOW);
+
+  it('says how many integrations could not be read, rather than counting silently', () => {
+    /** @type {any} */
+    const ctx = {
+      cwd: '/x',
+      nodeVersion: process.versions.node,
+      coreDir: null,
+      configPath: null,
+      configTheme: null,
+      integrations: [
+        {name: '@acme/ok', __spec: '@acme/ok', providerId: 'ok'},
+        {name: '@acme/bad', __spec: '@acme/bad', __loadError: 'boom'},
+      ],
+    };
+    const check = checkProviderIdentity(ctx);
+
+    expect(check.message).toContain('1 loaded integration has its own provider ID.');
+    expect(check.message).toContain('could not be read');
+  });
+});

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/error.d.mts

@@ -1,6 +1,28 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
+/**
+ * The error for a write that failed on the filesystem: no permission, a
+ * read-only mount, a full disk, a path component that is not a directory.
+ *
+ * A raw Node errno error reached the envelope as
+ * `{"error": "EACCES: permission denied, open '/home/you/p/readonly/x.tsx'",
+ * "code": "ERR_UNKNOWN"}` — the wrong code (ERR_WRITE_FAILED is in the frozen
+ * registry for exactly this) and an absolute host path in the message. This
+ * keeps the errno, which is the part that tells you what to fix, and reports
+ * the target the way every other Astryx message does: relative to the project.
+ *
+ * A caller that wrote files before the failure must undo them first and pass
+ * the ones it could not restore as `unrestored`, so the message never says
+ * nothing was written when something was.
+ *
+ * @param {string} target absolute path the write was aimed at
+ * @param {string} cwd project root, for the relative form
+ * @param {unknown} cause the error the filesystem call threw
+ * @param {string[]} [unrestored] absolute paths an undo could not put back
+ * @returns {AstryxError}
+ */
+export function writeFailed(target: string, cwd: string, cause: unknown, unrestored?: string[]): AstryxError;
 export class AstryxError extends Error {
     /**
      * @param {string} message

package/api/error.mjs

@@ -12,6 +12,7 @@
  */
 
 import {ERROR_CODES} from '../foundation/response/error-codes.mjs';
+import * as path from 'node:path';
 
 export class AstryxError extends Error {
   /** @type {import('../foundation/response/base').Suggestion[] | undefined} */
@@ -36,3 +37,44 @@ export class AstryxError extends Error {
     if (Array.isArray(suggestions) && suggestions.length) this.suggestions = suggestions;
   }
 }
+
+/**
+ * The error for a write that failed on the filesystem: no permission, a
+ * read-only mount, a full disk, a path component that is not a directory.
+ *
+ * A raw Node errno error reached the envelope as
+ * `{"error": "EACCES: permission denied, open '/home/you/p/readonly/x.tsx'",
+ * "code": "ERR_UNKNOWN"}` — the wrong code (ERR_WRITE_FAILED is in the frozen
+ * registry for exactly this) and an absolute host path in the message. This
+ * keeps the errno, which is the part that tells you what to fix, and reports
+ * the target the way every other Astryx message does: relative to the project.
+ *
+ * A caller that wrote files before the failure must undo them first and pass
+ * the ones it could not restore as `unrestored`, so the message never says
+ * nothing was written when something was.
+ *
+ * @param {string} target absolute path the write was aimed at
+ * @param {string} cwd project root, for the relative form
+ * @param {unknown} cause the error the filesystem call threw
+ * @param {string[]} [unrestored] absolute paths an undo could not put back
+ * @returns {AstryxError}
+ */
+export function writeFailed(target, cwd, cause, unrestored = []) {
+  const rel = path.relative(cwd, target) || target;
+  const errno =
+    typeof (/** @type {any} */ (cause)?.code) === 'string'
+      ? /** @type {any} */ (cause).code
+      : null;
+  const why = errno === 'EACCES' || errno === 'EPERM' ? ' (no permission)' : '';
+  const outcome =
+    unrestored.length === 0
+      ? 'Nothing was written.'
+      : `Earlier writes could not all be undone: ${unrestored
+          .map(file => path.relative(cwd, file) || file)
+          .join(', ')}.`;
+  return new AstryxError(
+    `Could not write ${rel}${errno ? `: ${errno}` : ''}${why}. ${outcome}`,
+    undefined,
+    ERROR_CODES.ERR_WRITE_FAILED,
+  );
+}

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',