@astryxdesign/cli 0.1.7 → 0.1.8-canary.07362a9

package/cli/commands/build.mjs

@@ -0,0 +1,172 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file build command — thin wrapper around api/build.
+ *
+ *   astryx build                  → the PLAYBOOK (how to build a page)
+ *   astryx build "<what>"         → a COMPOSITION KIT (closest page template,
+ *                                   blocks, components) with a recommended START.
+ *
+ * All grouping/scoring lives in api/build; this file only parses flags and
+ * renders. Command strings are prefixed for the caller's package manager here
+ * (never in the API payload) via formatCliCommand/getCliInvocation.
+ */
+
+import {getCliInvocation, formatCliCommand} from '../../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {build as buildApi} from '../../api/build/build.mjs';
+
+/**
+ * Print the build playbook (shown when `build` is run with no query).
+ * @param {string} run - The CLI invocation prefix (e.g. `npx astryx`).
+ */
+function printPlaybook(run) {
+  const lines = [
+    '',
+    'How to build a page with Astryx',
+    '',
+    "1. Find a starting point for what you're building:",
+    `     ${run} build "<what you're building>"`,
+    '   → returns the closest [page] template, the [block]s that cover parts,',
+    '     and the [component]s to fill the gaps, with a "Compose:" suggestion.',
+    '',
+    '2. If a [page] template matches → scaffold it and adapt:',
+    `     ${run} template <name> [path]`,
+    '',
+    '3. If nothing matches exactly → compose:',
+    `     ${run} template <name> --skeleton   # study a close page's layout`,
+    `     ${run} template <BlockName>         # drop in each block from the kit`,
+    `     ${run} component <Name>             # fill remaining gaps (read props)`,
+    '',
+    '4. Rules (keep it on-system):',
+    '   - No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
+    `   - No style={{}} — use component props; design tokens via \`${run} docs tokens\`.`,
+    '   - Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
+    '',
+    `Tip: \`${run} build "<idea>"\` is the fastest way in. For a neutral`,
+    `lookup of any component/doc/template, use \`${run} search <query>\`.`,
+    '',
+  ];
+  for (const l of lines) humanLog(l);
+}
+
+/**
+ * @param {import('commander').Command} program
+ */
+export function registerBuild(program) {
+  program
+    .command('build [query]')
+    .description('Build a page: composition kit for an idea, or the workflow playbook (no args)')
+    .option('--type <domain>', 'Filter the kit to one domain (component|hook|template)')
+    .option('--limit <n>', 'Max candidates to draw from (default 60)')
+    .option('--detail', 'Verbose output (include import paths and match reason)')
+    .action(async (/** @type {string | undefined} */ query, /** @type {{type?: import('../../types/search').SearchDomain, limit?: string, detail?: boolean}} */ options) => {
+      const run = getCliInvocation();
+      const json = program.opts().json || false;
+
+      // No query → the playbook. Still routed through the API for the envelope.
+      if (!query || !String(query).trim()) {
+        const result = await buildApi(undefined, {cwd: process.cwd()});
+        if (json) return jsonOut(result.type, result.data);
+        printPlaybook(run);
+        return;
+      }
+
+      // Arg validation stays in the CLI.
+      let limit = 60;
+      if (options.limit != null) {
+        const parsed = Number.parseInt(options.limit, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+          cliError(`Invalid --limit value "${options.limit}". Must be a positive integer.`);
+          return;
+        }
+        limit = parsed;
+      }
+
+      /** @type {import('../../types/build').BuildKitResponse} */
+      let result;
+      try {
+        result = /** @type {import('../../types/build').BuildKitResponse} */ (
+          await buildApi(query, {cwd: process.cwd(), type: options.type, limit})
+        );
+      } catch (e) {
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions});
+        return;
+      }
+
+      if (json) return jsonOut(result.type, result.data);
+
+      const {query: q, hasResults, directMatch, pages, blocks, domain, frame, foundation} =
+        result.data;
+
+      if (!hasResults) {
+        humanLog('');
+        humanLog(`No matches for "${q}".`);
+        humanLog(`Try a broader term, or browse: ${run} component --list`);
+        humanLog('');
+        return;
+      }
+
+      const printItem = (/** @type {import('../../types/search').SearchResultEntry} */ r, /** @type {string} */ label) => {
+        const display = r.domain === 'template' && r.displayName ? r.displayName : r.name;
+        humanLog('');
+        humanLog(`  [${label}] ${display}`);
+        if (r.description) humanLog(`          ${r.description}`);
+        humanLog(`          → ${formatCliCommand(r.command)}`);
+        if (options.detail) {
+          if (r.import) humanLog(`          import: ${r.import}`);
+          humanLog(`          match: ${r.reason} (score ${r.score})`);
+        }
+      };
+
+      humanLog('');
+      humanLog(`Building "${q}":`);
+
+      // START — the single recommended path.
+      humanLog('');
+      if (directMatch) {
+        humanLog(`START → Scaffold the \`${pages[0].name}\` page template, then adapt: ${run} template ${pages[0].name} ./src/App.tsx`);
+      } else if (pages.length) {
+        humanLog(`START → No exact page template. Use \`${pages[0].name}\` as a layout reference (${run} template ${pages[0].name} --skeleton) and compose the pieces below.`);
+      } else {
+        humanLog(`START → No page template fits. Frame with AppShell and compose the blocks + components below.`);
+      }
+
+      // PAGE
+      if (pages.length) {
+        humanLog('');
+        humanLog(directMatch ? 'PAGE TEMPLATE — direct match:' : 'CLOSEST PAGE TEMPLATES — layout reference:');
+        pages.forEach(p => printItem(p, directMatch ? 'page' : 'closest'));
+      }
+
+      // FRAME — always (the page shell).
+      humanLog('');
+      humanLog(`FRAME — page shell (always): ${frame.join(', ')}`);
+      humanLog(`          full-page → AppShell; or Layout + SideNav/TopNav. ${run} component AppShell`);
+
+      // BLOCKS — idea-specific composed patterns.
+      if (blocks.length) {
+        humanLog('');
+        humanLog('BLOCKS — drop-in patterns that cover parts of it:');
+        blocks.forEach(b => printItem(b, 'block'));
+      }
+
+      // DOMAIN COMPONENTS — idea-specific atoms.
+      if (domain.length) {
+        humanLog('');
+        humanLog('DOMAIN COMPONENTS — specific to this idea:');
+        domain.forEach(c => printItem(c, c.domain === 'hook' ? 'hook' : 'component'));
+      }
+
+      // FOUNDATION — always (layout/typography/actions).
+      humanLog('');
+      humanLog(`FOUNDATION — always available (layout/text/actions): ${foundation.join(' ')}`);
+
+      // SETUP — so it renders / stays on-system.
+      humanLog('');
+      humanLog('SETUP — import "@astryxdesign/core/reset.css" + "astryx.css". No <div>/style for layout — use Stack/Grid + tokens.');
+      humanLog('');
+    });
+}

package/cli/commands/cli-postinstall.test.mjs

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guardrail tests for the @astryxdesign/cli postinstall nudge (layer 2).
+ *
+ * Tests the pure decision matrix (shouldNudge) — nudges for a real dependency
+ * install when not set up; stays quiet in the monorepo/source, during npx's
+ * transient fetch (path _npx or npm_command=exec), and once set up.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {shouldNudge} from '../../scripts/postinstall.mjs';
+
+const DEP = '/proj/node_modules/@astryxdesign/cli/scripts/postinstall.mjs'; // real dep install
+const NPX = '/Users/x/.npm/_npx/a1b2/node_modules/@astryxdesign/cli/scripts/postinstall.mjs';
+const REPO = '/repo/packages/cli/scripts/postinstall.mjs'; // monorepo/source
+
+describe('cli postinstall — shouldNudge', () => {
+  it('nudges for a real dependency install when not set up', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: false})).toBe(true);
+  });
+
+  it('quiet in the monorepo/source (not under node_modules)', () => {
+    expect(shouldNudge({scriptPath: REPO, npmCommand: 'install', isSetUp: false})).toBe(false);
+  });
+
+  it('quiet during npx transient install (path contains _npx)', () => {
+    expect(shouldNudge({scriptPath: NPX, npmCommand: 'install', isSetUp: false})).toBe(false);
+  });
+
+  it('quiet during npx (npm_command=exec) — avoids double-nudge before init', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'exec', isSetUp: false})).toBe(false);
+  });
+
+  it('quiet once the project is already set up', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: true})).toBe(false);
+  });
+
+  it('quiet with no script path (defensive)', () => {
+    expect(shouldNudge({})).toBe(false);
+  });
+});

package/{src → cli}/commands/component/index.mjs

@@ -6,27 +6,47 @@
  * Global options: --detail full|compact|brief, --lang en|zh|dense
  */
 
-import {findCoreDir} from '../../utils/paths.mjs';
+import {findCoreDir} from '../../../utils/paths.mjs';
 import {
   resolveImportPath,
-} from '../../lib/component-discovery.mjs';
+} from '../../../lib/component-discovery.mjs';
 import {
   formatFull,
   formatCompact,
   formatBrief,
   formatProps,
   formatBriefAll,
-} from '../../lib/component-format.mjs';
-import {resolveTheme} from '../../lib/resolve-theme.mjs';
-import {getRunPrefix} from '../../utils/package-manager.mjs';
-import {jsonOut, humanLog} from '../../lib/json.mjs';
-import {cliError} from '../../lib/cli-error.mjs';
-import {ERROR_CODES} from '../../lib/error-codes.mjs';
-import {component as componentApi} from '../../api/component.mjs';
-import {findRelatedBlocks} from '../../api/template.mjs';
-import {Project} from '../../lib/project.mjs';
-import {warnOnIntegrationIssues} from '../../lib/integration-warnings.mjs';
+} from '../../../lib/component-format.mjs';
+import {resolveTheme} from '../../../lib/resolve-theme.mjs';
+import {getCliInvocation} from '../../../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../../../lib/json.mjs';
+import {cliError} from '../../../lib/cli-error.mjs';
+import {ERROR_CODES} from '../../../lib/error-codes.mjs';
+import {component as componentApi} from '../../../api/component/component.mjs';
+import {findRelatedBlocks} from '../../../api/template/template.mjs';
+import {Project} from '../../../lib/project.mjs';
+import {warnOnIntegrationIssues} from '../../../lib/integration-warnings.mjs';
 
+/**
+ * The api layer's component() widens its return to `{type: string, data: unknown}`,
+ * so annotate the command-local result with the precise discriminated union from
+ * src/types/component to get narrowing + typed data.
+ *
+ * @typedef {(
+ *   | import('../../../types/component').ComponentListResponse
+ *   | import('../../../types/component').ComponentBriefResponse
+ *   | import('../../../types/component').ComponentFullResponse
+ *   | import('../../../types/component').ComponentDetailResponse
+ *   | import('../../../types/component').ComponentDetailPropsResponse
+ *   | import('../../../types/component').ComponentDetailSourceResponse
+ *   | import('../../../types/component').ComponentDetailShowcaseResponse
+ *   | import('../../../types/component').ComponentDetailBlocksResponse
+ * )} ComponentResult
+ */
+
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerComponent(program) {
   program
     .command('component [name]')
@@ -38,8 +58,8 @@ export function registerComponent(program) {
     .option('--showcase', 'Print showcase source code')
     .option('--blocks', 'List example blocks: showcase, examples, and related')
     .option('--package <name>', 'Scope lookup to an external package (e.g. @acme/xds-widgets)')
-    .action(async (name, options) => {
-      const run = getRunPrefix();
+    .action(async (/** @type {string | undefined} */ name, /** @type {{list?: boolean, category?: string, props?: boolean, source?: boolean, showcase?: boolean, blocks?: boolean, package?: string}} */ options) => {
+      const run = getCliInvocation();
       const zh = program.opts().zh || false;
       const dense = program.opts().dense || false;
       const lang = program.opts().lang || null;
@@ -67,9 +87,10 @@ export function registerComponent(program) {
         // Never let the nudge break the command.
       }
 
+      /** @type {ComponentResult} */
       let result;
       try {
-        result = await componentApi(name, {
+        result = /** @type {ComponentResult} */ (await componentApi(name, {
           cwd: process.cwd(),
           list: options.list,
           category: options.category,
@@ -80,16 +101,19 @@ export function registerComponent(program) {
           blocks: options.blocks,
           detail,
           lang, zh, dense,
-        });
+        }));
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions, code: e.code});
+        const err = /** @type {import('../../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions, code: err.code});
         return;
       }
 
       if (json) return jsonOut(result.type, result.data);
 
       // ── Text output ────────────────────────────────────────────
-      const coreDir = findCoreDir(process.cwd());
+      // The api layer already resolved against core (result exists), so core is
+      // present on this path; narrow away the null branch findCoreDir allows.
+      const coreDir = /** @type {string} */ (findCoreDir(process.cwd()));
       const themeData = resolveTheme(process.cwd());
 
       switch (result.type) {
@@ -101,6 +125,7 @@ export function registerComponent(program) {
           const CORE_PKG = '@astryxdesign/core';
           // Names that appear under more than one package across the whole
           // listing — these must always be package-qualified to disambiguate.
+          /** @type {Map<string, Set<string>>} */
           const nameCounts = new Map();
           for (const items of Object.values(result.data)) {
             for (const item of items) {
@@ -109,7 +134,9 @@ export function registerComponent(program) {
               nameCounts.set(item.name, set);
             }
           }
+          /** @param {string} n */
           const isCollision = n => (nameCounts.get(n)?.size ?? 0) > 1;
+          /** @param {import('../../../types/component').ComponentListEntry} item */
           const pkgSuffix = item => {
             if (item.package !== CORE_PKG) return `  [${item.package}]`;
             if (isCollision(item.name)) return `  [${item.package}]`;
@@ -142,7 +169,7 @@ export function registerComponent(program) {
             }
             humanLog('');
             humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
-            humanLog(`Usage: ${run} astryx component <name>`);
+            humanLog(`Usage: ${run} component <name>`);
             humanLog('');
           }
           break;
@@ -165,7 +192,7 @@ export function registerComponent(program) {
             humanLog('');
           }
           humanLog(`Import from the path shown (e.g. import {Button} from '@astryxdesign/core/Button')`);
-          humanLog(`Usage: ${run} astryx component <name>`);
+          humanLog(`Usage: ${run} component <name>`);
           humanLog('');
           break;
         }
@@ -251,8 +278,8 @@ export function registerComponent(program) {
 
 // Re-export lib functions for backward compatibility
 // (agent-docs.mjs, tests, and generate-skill-doc.sh import from here)
-export {discoverComponents, discoverExternalComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../lib/component-discovery.mjs';
-export {discoverExternalPackages} from '../../utils/paths.mjs';
-export {loadDocs} from '../../lib/component-loader.mjs';
-export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../lib/component-format.mjs';
-export {levenshteinDistance, findClosestComponents, searchComponents} from '../../lib/string-utils.mjs';
+export {discoverComponents, discoverExternalComponents, discoverExternalComponentsGrouped, findComponentReadme, findComponentSource, findExternalComponentDoc, resolveImportPath} from '../../../lib/component-discovery.mjs';
+export {discoverExternalPackages} from '../../../utils/paths.mjs';
+export {loadDocs} from '../../../lib/component-loader.mjs';
+export {formatFull, formatCompact, formatBrief, formatProps, formatBriefAll} from '../../../lib/component-format.mjs';
+export {levenshteinDistance, findClosestComponents, searchComponents} from '../../../lib/string-utils.mjs';

package/{src → cli}/commands/component-ownership.test.mjs

@@ -10,7 +10,7 @@ import {
   findIntegrationComponentDoc,
   findIntegrationComponentSource,
   CORE_PACKAGE,
-} from '../lib/component-discovery.mjs';
+} from '../../lib/component-discovery.mjs';
 
 // The api `component()` reads integrations via Project.load(). In the vitest
 // environment, Vite's `server.fs.allow` only permits loading modules from
@@ -20,12 +20,12 @@ import {
 // produces) while keeping the integration's `components` dir on disk under
 // node_modules so its `.doc.mjs` files load normally.
 const projectLoadMock = vi.fn();
-vi.mock('../lib/project.mjs', () => ({
+vi.mock('../../lib/project.mjs', () => ({
   Project: {load: (...args) => projectLoadMock(...args)},
 }));
 
 // Import the api AFTER the mock is registered.
-const {component} = await import('../api/component.mjs');
+const {component} = await import('../../api/component/component.mjs');
 
 let tmpDir;
 

package/{src → cli}/commands/component-package.test.mjs

@@ -4,7 +4,7 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-import {component} from '../api/component.mjs';
+import {component} from '../../api/component/component.mjs';
 
 // These tests create a minimal monorepo fixture with:
 // - packages/core (symlinked to real @astryxdesign/core for loadDocs compatibility)

package/{src → cli}/commands/component-resolution.test.mjs

@@ -1,8 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, it, expect} from 'vitest';
-import {component} from '../api/component.mjs';
-import {findShowcase, findRelatedBlocks} from '../api/template.mjs';
+import {component} from '../../api/component/component.mjs';
+import {findShowcase, findRelatedBlocks} from '../../api/template/template.mjs';
 
 const CWD = {cwd: '.'};
 

package/{src → cli}/commands/discover.mjs

@@ -10,27 +10,38 @@
  *   astryx discover searchterm                Search across all packages
  */
 
-import {formatFull, formatBrief, formatCompact} from '../lib/component-format.mjs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {discover as discoverApi} from '../api/discover.mjs';
+import {formatFull, formatBrief, formatCompact} from '../../lib/component-format.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {discover as discoverApi} from '../../api/discover/discover.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerDiscover(program) {
   program
     .command('discover [query]')
     .description('Discover external packages and components')
     .option('--components', 'List components only')
-    .action(async (query, options) => {
+    .action(
+      /**
+       * @param {string | undefined} query
+       * @param {{components?: boolean}} options
+       */
+      async (query, options) => {
       const detail = program.opts().detail || 'full';
       const json = program.opts().json || false;
       const lang = program.opts().lang || null;
       const zh = program.opts().zh || false;
+      const run = getCliInvocation();
 
       let result;
       try {
         result = await discoverApi(query, {components: options.components, lang, zh});
       } catch (e) {
-        cliError(e.message, {suggestions: e.suggestions, code: e.code});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions, code: err.code});
         return;
       }
 
@@ -38,7 +49,7 @@ export function registerDiscover(program) {
         // Forward optional meta (e.g. configured flag for discover.list) as a
         // sibling of data via jsonOut, so the envelope still carries
         // apiVersion and goes through the single sanctioned emit path.
-        return jsonOut(result.type, result.data, result.meta);
+        return jsonOut(result.type, result.data, 'meta' in result ? result.meta : undefined);
       }
 
       switch (result.type) {
@@ -80,9 +91,9 @@ export function registerDiscover(program) {
               humanLog('');
             }
             humanLog('Usage:');
-            humanLog('  astryx discover <package>            Browse a package');
-            humanLog('  astryx discover <package>/Component  View component docs');
-            humanLog('  astryx discover <search>             Search all packages');
+            humanLog(`  ${run} discover <package>            Browse a package`);
+            humanLog(`  ${run} discover <package>/Component  View component docs`);
+            humanLog(`  ${run} discover <search>             Search all packages`);
             humanLog('');
           }
           break;
@@ -99,7 +110,7 @@ export function registerDiscover(program) {
           humanLog('');
           for (const comp of result.data.components) humanLog('  ' + comp);
           humanLog('');
-          humanLog('Usage: astryx discover ' + result.data.name + '/<ComponentName>');
+          humanLog(`Usage: ${run} discover ` + result.data.name + '/<ComponentName>');
           humanLog('');
           break;
         }
@@ -122,7 +133,7 @@ export function registerDiscover(program) {
           humanLog('Found ' + result.data.matches.length + ' matches for "' + result.data.query + '":');
           humanLog('');
           for (const m of result.data.matches) {
-            humanLog('  astryx discover ' + m.package + '/' + m.component);
+            humanLog(`  ${run} discover ` + m.package + '/' + m.component);
           }
           humanLog('');
           break;

package/{src → cli}/commands/docs.mjs

@@ -12,13 +12,18 @@
  *   astryx docs <topic> <section>        Print one section
  */
 
-import {getRunPrefix} from '../utils/package-manager.mjs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
-import {cliError} from '../lib/cli-error.mjs';
-import {docs as docsApi} from '../api/docs.mjs';
+import {getCliInvocation} from '../../utils/package-manager.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
+import {cliError} from '../../lib/cli-error.mjs';
+import {docs as docsApi} from '../../api/docs/docs.mjs';
 
 // ─── Formatting ──────────────────────────────────────────────────────────────
 
+/**
+ * @param {string[]} headers
+ * @param {string[][]} rows
+ * @returns {string}
+ */
 function formatTable(headers, rows) {
   const widths = headers.map((h, i) =>
     Math.max(h.length, ...rows.map(r => (r[i] || '').length)),
@@ -31,15 +36,28 @@ function formatTable(headers, rows) {
   return `${head}\n${sep}\n${body}`;
 }
 
+/**
+ * @param {string[]} headers
+ * @param {string[][]} rows
+ * @returns {string}
+ */
 function formatTableCompact(headers, rows) {
   return rows.map(r => r.join(' = ')).join('\n');
 }
 
+/**
+ * @param {import('../../../core/src/docs-types').ContentBlock} block
+ * @param {'full' | 'compact' | 'brief'} detail
+ * @returns {string | null}
+ */
 function formatBlock(block, detail) {
   switch (block.type) {
     case 'prose':
       return block.text;
 
+    case 'heading':
+      return `${'#'.repeat(block.level || 3)} ${block.text}`;
+
     case 'code':
       if (detail === 'compact' || detail === 'brief') return null;
       {
@@ -57,7 +75,7 @@ function formatBlock(block, detail) {
       return formatTable(block.headers, block.rows);
 
     case 'list': {
-      const prefix = block.style === 'ordered' ? (i) => `${i + 1}. `
+      const prefix = block.style === 'ordered' ? (/** @type {number} */ i) => `${i + 1}. `
         : block.style === 'dont' ? () => '❌ '
         : block.style === 'do' ? () => '✓ '
         : () => '- ';
@@ -69,6 +87,11 @@ function formatBlock(block, detail) {
   }
 }
 
+/**
+ * @param {import('../../../core/src/docs-types').ReferenceSection} section
+ * @param {'full' | 'compact' | 'brief'} detail
+ * @returns {string}
+ */
 function formatSection(section, detail) {
   const blocks = section.content
     .map(b => formatBlock(b, detail))
@@ -83,6 +106,11 @@ function formatSection(section, detail) {
   return `${heading}\n\n${blocks.join('\n\n')}`;
 }
 
+/**
+ * @param {import('../../../core/src/docs-types').ReferenceDoc} docs
+ * @param {'full' | 'compact' | 'brief'} detail
+ * @returns {string}
+ */
 function formatReferenceFull(docs, detail) {
   if (detail === 'brief') {
     const header = `${docs.title}: ${docs.description}`;
@@ -100,12 +128,15 @@ function formatReferenceFull(docs, detail) {
 
 // ─── Command ─────────────────────────────────────────────────────────────────
 
+/**
+ * @param {import('commander').Command} program
+ */
 export function registerDocs(program) {
   program
     .command('docs [topic] [section]')
     .description('Print reference docs')
-    .action(async (topic, section) => {
-      const run = getRunPrefix();
+    .action(async (/** @type {string | undefined} */ topic, /** @type {string | undefined} */ section) => {
+      const run = getCliInvocation();
       const lang = program.opts().lang || null;
       const zh = program.opts().zh || false;
       const dense = program.opts().dense || false;
@@ -118,7 +149,8 @@ export function registerDocs(program) {
       } catch (e) {
         // docs API throws structured errors with {name, reason} suggestions —
         // pass them through untouched so the CLI envelope matches the API.
-        cliError(e.message, {suggestions: e.suggestions || [], code: e.code});
+        const err = /** @type {import('../../api/error.mjs').AstryxError} */ (e);
+        cliError(err.message, {suggestions: err.suggestions || [], code: err.code});
         return;
       }
 
@@ -130,8 +162,8 @@ export function registerDocs(program) {
           for (const entry of result.data) {
             humanLog(`  ${entry.topic.padEnd(14)} ${entry.description}`);
           }
-          humanLog(`\nUsage: ${run} astryx docs <topic>`);
-          humanLog(`       ${run} astryx docs <topic> <section>\n`);
+          humanLog(`\nUsage: ${run} docs <topic>`);
+          humanLog(`       ${run} docs <topic> <section>\n`);
           break;
         }
 

package/{src → cli}/commands/docs.test.mjs

@@ -71,7 +71,7 @@ describe('hyphenated doc filenames', () => {
   });
 
   it('returns docs.detail via API for hyphenated topic', async () => {
-    const {docs: docsApi} = await import('../api/docs.mjs');
+    const {docs: docsApi} = await import('../../api/docs/docs.mjs');
     const result = await docsApi('getting-started');
     expect(result.type).toBe('docs.detail');
     expect(result.data).toBeDefined();

package/{src → cli}/commands/doctor.mjs

@@ -10,8 +10,8 @@
  * as a CI gate.
  */
 
-import {runChecks} from '../api/doctor.mjs';
-import {jsonOut, humanLog} from '../lib/json.mjs';
+import {runChecks} from '../../api/doctor/doctor.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
 
 /** Status → human glyph (monochrome, matching the rest of the CLI). */
 const GLYPH = {
@@ -23,7 +23,7 @@ const GLYPH = {
 
 /**
  * Render the report as a human-readable checklist.
- * @param {import('../api/doctor.mjs').DoctorReport} report
+ * @param {import('../../api/doctor/doctor.mjs').DoctorReport} report
  */
 function printHuman(report) {
   humanLog('astryx doctor — diagnosing your setup\n');