@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.dea6813

package/README.md

@@ -51,8 +51,8 @@ Options:
 
 - `--type <component|hook|doc|template>`: restrict to a single domain
 - `--limit <n>`: cap the number of results (default 20)
-- `--detail`: include the import path and the match reason/score
-- `--json`: typed `{ type: 'search', data: { query, matchCount, results } }` envelope — `matchCount` is how many candidates matched in total, `results` the slice `--limit` allowed
+- `--verbose`: also print each result's match score and reason
+- `--json`: typed `{ apiVersion, type: 'search', data: { query, matchCount, results } }` envelope — `matchCount` is how many candidates matched in total, `results` the slice `--limit` allowed
 
 ## Commands
 
@@ -84,7 +84,7 @@ Options:
 
 These flags work with any command:
 
-- `--json`: Output as typed JSON envelope: `{ type, data }` (errors: `{ error, code, suggestions? }`)
+- `--json`: Output as typed JSON envelope: `{ apiVersion, type, data, meta? }` (errors: `{ apiVersion, error, code, suggestions? }`)
 - `--detail <level>`: Detail level for list views, increasing in size: `brief` (names only, default for `--list`) < `compact` (names + 1-line descriptions) < `full` (full docs per entry). Single-item views default to `full`.
 - `--zh`: Output docs in Chinese Simplified
 - `--dense`: Compressed format (token-efficient, useful for AI agents)
@@ -95,13 +95,14 @@ These flags work with any command:
 Every command supports `--json` for machine-readable output. Responses are typed envelopes:
 
 ```json
-{"type": "component.detail", "data": {"name": "Button", ...}}
+{"apiVersion": 1, "type": "component.detail", "data": {"name": "Button", ...}}
 ```
 
 Errors:
 
 ```json
 {
+  "apiVersion": 1,
   "error": "No component named \"Buttn\"",
   "code": "ERR_UNKNOWN_COMPONENT",
   "suggestions": [{"name": "Button", "reason": "similar name"}]
@@ -175,7 +176,7 @@ if (isError(result)) {
 | `ERR_NO_SOURCE`                   | No source file could be located for the requested component/template.                                                                                    |
 | `ERR_INVALID_DOC`                 | A component's docs failed validation (malformed `.doc.mjs`).                                                                                             |
 | `ERR_FILE_NOT_FOUND`              | A required input file did not exist.                                                                                                                     |
-| `ERR_FILE_EXISTS`                 | Refused to overwrite an existing file in non-interactive mode.                                                                                           |
+| `ERR_FILE_EXISTS`                 | Refused to overwrite an existing file.                                                                                                                   |
 | `ERR_PATH_TRAVERSAL`              | A path escaped its allowed root, or a name contained traversal markers.                                                                                  |
 | `ERR_WRITE_FAILED`                | Writing output files failed (and was rolled back).                                                                                                       |
 | `ERR_THEME_INVALID`               | A theme definition or contributed theme catalog is invalid.                                                                                              |
@@ -199,8 +200,9 @@ if (isError(result)) {
 
 Agents don't have to scrape `--help` to learn the CLI. A single call returns a
 **self-describing manifest**: every command, its arguments, flags (with types,
-choices, and defaults), whether it supports `--json`, and the response `type`
-discriminators each command can emit. Think of it as an OpenAPI spec for the CLI.
+choices, and defaults), whether it supports `--json`, the response `type`
+discriminators each command can emit, and its documented exit codes. Think of it
+as an OpenAPI spec for the CLI.
 
 ```bash
 astryx manifest --json        # dedicated surface — type: "manifest"
@@ -262,6 +264,10 @@ Shape:
           "…",
         ],
         "examples": ["astryx component Button --props --json"],
+        "exitCodes": [
+          {"code": 0, "when": "success"},
+          {"code": 1, "when": "…"},
+        ],
       },
       // …one entry per command; subcommands (e.g. `theme build`) nest under `subcommands`
     ],
@@ -343,9 +349,9 @@ import type {
   // ...import the response types for the commands you consume
 } from '@astryxdesign/cli/json';
 
-// parseResponse returns the structural { type, data, meta? } envelope; `data`
-// is `unknown` until you narrow it. Reconstruct the union you care about from
-// the per-command response types, then narrow on `type`:
+// parseResponse returns the structural { apiVersion, type, data, meta? }
+// envelope; `data` is `unknown` until you narrow it. Reconstruct the union you
+// care about from the per-command response types, then narrow on `type`:
 type MyResponse =
   ComponentDetailResponse | ComponentListResponse | DocsListResponse;
 
@@ -412,7 +418,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `discover.detail.doc`             | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                                                                                |
 | `discover.search`                 | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                                                                              |
 | `search`                          | The echoed query, `matchCount` (how many candidates matched in total, before `limit`), plus a ranked SearchResultEntry[] bounded by `limit` (domain, name, score, reason, description, follow-up command, and import path where relevant).                                                    |
-| `build.help`                      | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.                                                                                                                                                                  |
+| `build.help`                      | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.                 |
 | `build.kit`                       | The grouped composition kit: echoed query, hasResults/matchCount/directMatch fields (matchCount is the total matched, never a cap read back), the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays. |
 | `swizzle.list`                    | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                                                                                |
 | `swizzle.copy`                    | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                                                                                |
@@ -426,7 +432,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `hook.list`                       | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                                                                             |
 | `hook.detail`                     | One hook's full authored HookDoc.                                                                                                                                                                                                                                                             |
 | `hook.detail.params`              | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                                                                            |
-| `theme.build`                     | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                                                                             |
+| `theme.build`                     | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load).                  |
 | `theme.build.check`               | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                                                                          |
 | `theme.build.batch`               | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS.                                                                             |
 | `theme.list`                      | Every bundled or installed integration theme as a ThemeListEntry[]: each with slug, displayName, description, maintained flag, and owner package.                                                                                                                                             |
@@ -437,7 +443,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `upgrade.list`                    | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                                                                                    |
 | `upgrade.status`                  | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                                                                              |
 | `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                                                                   |
-| `manifest`                        | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.                                                                 |
+| `manifest`                        | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.            |
 | `doctor`                          | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                                                                                   |
 | `integration.add`                 | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun.                                                                                                                               |
 | `integration.pack-check`          | The packed-package check: package identity, tarball facts, local and packed contribution inventories, and issues.                                                                                                                                                                             |
@@ -456,25 +462,33 @@ Every response has a `type` discriminant. The full set is below (generated from
 
 `astryx doctor` runs read-only health checks against your project and
 environment. Each record uses `[ok]`, `[warn]`, `[fail]`, or `[info]`, and
-includes an actionable `fix` when one is available. The exact checks and values
-depend on the project; the output shape is stable:
+includes an actionable `fix` when one is available. Field names match the
+`--json` keys. The exact checks and values depend on the project; the output
+shape is stable:
 
 ```
 $ astryx doctor
 astryx doctor - diagnosing your setup
 
+id:      node-version
 status:  [ok]
-check:   Node.js version
+label:   Node.js version
 message: Node v24.18.1 meets the minimum (>=22.13.0).
 
+id:      themes
 status:  [warn]
-check:   Theme packages
+label:   Theme packages
 message: No @astryxdesign/theme-* packages are installed.
 fix:     Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.
 
 ...
 
-Summary: 4 passed, 2 warnings, 0 failures, 2 info
+summary
+
+pass: 4
+warn: 2
+fail: 0
+info: 2
 
 No failures - but review the [warn] warnings above when you can.
 ```

package/api/build/build.doc.mjs

@@ -16,8 +16,8 @@ export const doc = {
     'Page-building assistant: the how-to-build playbook, or a composition kit for an idea.',
   description:
     'The "assemble a page" entry point. Called with no query it returns the ' +
-    'playbook signal that the renderer expands into the how-to-build-a-page ' +
-    'workflow. Called with a query it runs the unified search and groups the ' +
+    'how-to-build-a-page playbook as data: the workflow steps with their ' +
+    'commands, the on-system rules, and related lookups. Called with a query it runs the unified search and groups the ' +
     'hits into a composition KIT: the closest page templates, drop-in blocks, ' +
     'and idea-specific components/hooks, plus the always-on frame + foundation.',
   importPath: '@astryxdesign/cli/api',
@@ -54,7 +54,7 @@ export const doc = {
     {
       type: 'build.help',
       description:
-        'Emitted when the query is omitted: a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
+        'Emitted when the query is omitted: the page-building playbook — `playbook: true`, a `title`, the ordered `steps` (each a `title`, its `commands`, and optionally what the step `returns`), the on-system `rules`, and `related` lookups. Each command is a bare subcommand ({command, purpose?}) for the caller to render with its own CLI invocation.',
     },
     {
       type: 'build.kit',

package/api/build/build.test.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Tests for the build API (playbook signal + composition kit).
+ * @file Tests for the build API (playbook + composition kit).
  */
 
 import {describe, it, expect, vi} from 'vitest';
@@ -20,10 +20,21 @@ const REPO = path.resolve(
 vi.setConfig({testTimeout: 30000});
 
 describe('build API', () => {
-  it('no query → build.help playbook signal', async () => {
+  it('no query → build.help carries the playbook as data', async () => {
     const r = await build();
     expect(r.type).toBe('build.help');
-    expect(r.data).toEqual({playbook: true});
+    if (r.type !== 'build.help') return;
+    expect(r.data.playbook).toBe(true);
+    expect(r.data.title).toMatch(/build a page/i);
+    expect(r.data.steps.length).toBeGreaterThan(0);
+    for (const step of r.data.steps) {
+      expect(step.title).toBeTruthy();
+      expect(step.commands.length).toBeGreaterThan(0);
+    }
+    expect(r.data.rules.length).toBeGreaterThan(0);
+    // Bare subcommands: the caller adds its own invocation.
+    const commands = [...r.data.steps.flatMap(s => s.commands), ...r.data.related];
+    for (const {command} of commands) expect(command).not.toMatch(/^(astryx|npx|pnpm|yarn|bunx?)\b/);
   });
 
   it('query → build.kit with raw entries + static frame/foundation', async () => {

package/api/build/build.type.d.mts

@@ -2,12 +2,46 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * astryx --json build (no query) — the "how to build a page" playbook signal.
+ * A command the playbook tells the caller to run.
+ */
+export type BuildPlaybookCommand = {
+    /**
+     * Bare subcommand with `<placeholder>` arguments (e.g. `template <name> --skeleton`) and no package-manager prefix — render it with your own CLI invocation.
+     */
+    command: string;
+    /**
+     * What running it is for.
+     */
+    purpose?: string | undefined;
+};
+/**
+ * One step of the page-building workflow.
+ */
+export type BuildPlaybookStep = {
+    /**
+     * What to do.
+     */
+    title: string;
+    /**
+     * The commands for this step, in the order to run them.
+     */
+    commands: BuildPlaybookCommand[];
+    /**
+     * What the step's command gives back, when that decides the next step.
+     */
+    returns?: string | undefined;
+};
+/**
+ * astryx --json build (no query) — the "how to build a page" playbook.
  */
 export type BuildHelpResponse = {
     type: "build.help";
     data: {
         playbook: true;
+        title: string;
+        steps: BuildPlaybookStep[];
+        rules: string[];
+        related: BuildPlaybookCommand[];
     };
 };
 /**

package/api/build/build.type.mjs

@@ -2,17 +2,38 @@
 
 /**
  * @file Colocated types for the `build` command — source of truth for the
- * `build.help` (playbook signal) and `build.kit` (composition kit) JSON
- * responses. Re-exported by types/build.d.ts.
+ * `build.help` (playbook) and `build.kit` (composition kit) JSON responses.
+ * Re-exported by types/build.d.ts.
  */
 
 /**
- * astryx --json build (no query) — the "how to build a page" playbook signal.
+ * A command the playbook tells the caller to run.
+ *
+ * @typedef {object} BuildPlaybookCommand
+ * @property {string} command Bare subcommand with `<placeholder>` arguments (e.g. `template <name> --skeleton`) and no package-manager prefix — render it with your own CLI invocation.
+ * @property {string} [purpose] What running it is for.
+ */
+
+/**
+ * One step of the page-building workflow.
+ *
+ * @typedef {object} BuildPlaybookStep
+ * @property {string} title What to do.
+ * @property {BuildPlaybookCommand[]} commands The commands for this step, in the order to run them.
+ * @property {string} [returns] What the step's command gives back, when that decides the next step.
+ */
+
+/**
+ * astryx --json build (no query) — the "how to build a page" playbook.
  *
  * @typedef {object} BuildHelpResponse
  * @property {'build.help'} type
  * @property {object} data
  * @property {true} data.playbook Always true; marks this envelope as the playbook rather than a result set.
+ * @property {string} data.title The playbook's heading.
+ * @property {BuildPlaybookStep[]} data.steps The workflow, in order.
+ * @property {string[]} data.rules The rules that keep a page on-system.
+ * @property {BuildPlaybookCommand[]} data.related Lookups to reach for alongside the workflow.
  */
 
 /**

package/api/build/help/help.d.mts

@@ -2,14 +2,17 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @file build.help leaf — the "how to build a page" playbook signal.
+ * @file build.help leaf — the "how to build a page" playbook.
  *
- * `build` with no query returns this envelope: a pure marker that the command
- * renderer expands into the workflow playbook prose. It carries no data beyond
- * `playbook: true`, so the JSON shape stays environment-agnostic and stable.
+ * `build` with no query returns this envelope. The playbook is data — steps,
+ * rules, and related lookups — so a `--json` or programmatic caller gets the
+ * same guidance the terminal shows. Commands are bare subcommands with no
+ * package-manager prefix, which keeps the JSON environment-agnostic; the CLI
+ * renders each one with the caller's invocation, as it does build.kit's
+ * `hint.commands`.
  */
 /**
- * The page-building playbook signal (emitted when `build` runs with no query).
+ * The page-building playbook (emitted when `build` runs with no query).
  *
  * @returns {import('../build.type.mjs').BuildHelpResponse}
  */

package/api/build/help/help.mjs

@@ -1,18 +1,68 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file build.help leaf — the "how to build a page" playbook signal.
+ * @file build.help leaf — the "how to build a page" playbook.
  *
- * `build` with no query returns this envelope: a pure marker that the command
- * renderer expands into the workflow playbook prose. It carries no data beyond
- * `playbook: true`, so the JSON shape stays environment-agnostic and stable.
+ * `build` with no query returns this envelope. The playbook is data — steps,
+ * rules, and related lookups — so a `--json` or programmatic caller gets the
+ * same guidance the terminal shows. Commands are bare subcommands with no
+ * package-manager prefix, which keeps the JSON environment-agnostic; the CLI
+ * renders each one with the caller's invocation, as it does build.kit's
+ * `hint.commands`.
  */
 
 /**
- * The page-building playbook signal (emitted when `build` runs with no query).
+ * The page-building playbook (emitted when `build` runs with no query).
  *
  * @returns {import('../build.type.mjs').BuildHelpResponse}
  */
 export function buildHelp() {
-  return {type: 'build.help', data: {playbook: true}};
+  return {
+    type: 'build.help',
+    data: {
+      playbook: true,
+      title: 'How to build a page with Astryx',
+      steps: [
+        {
+          title: "Find a starting point for what you're building",
+          commands: [{command: '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 recommended start',
+        },
+        {
+          title: 'If a [page] template matches, scaffold it and adapt',
+          commands: [{command: 'template <name> [path]'}],
+        },
+        {
+          title: 'If nothing matches exactly, compose',
+          commands: [
+            {
+              command: 'template <name> --skeleton',
+              purpose: "study a close page's layout",
+            },
+            {
+              command: 'template <BlockName>',
+              purpose: 'drop in each block from the kit',
+            },
+            {
+              command: 'component <Name>',
+              purpose: 'fill remaining gaps (read props)',
+            },
+          ],
+        },
+      ],
+      rules: [
+        'No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.',
+        'No style={{}} — use component props, and design tokens for values.',
+        'Wrap the app in <Theme theme={...}> and import core reset.css + astryx.css.',
+      ],
+      related: [
+        {command: 'docs tokens', purpose: 'the design tokens'},
+        {
+          command: 'search <query>',
+          purpose: 'a neutral lookup of any component, doc, or template',
+        },
+      ],
+    },
+  };
 }

package/api/component/component.doc.mjs

@@ -91,7 +91,8 @@ export const doc = {
     {
       name: 'options.lang',
       type: 'string',
-      description: 'Language code for localized doc content.',
+      description:
+        "Language code for localized doc content: 'en', 'zh', or 'dense'.",
     },
     {
       name: 'options.zh',
@@ -113,7 +114,7 @@ export const doc = {
     {
       type: 'component.detail',
       description:
-        "One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, whether source is available).",
+        "One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, whether source is available). When the name is a sub-component documented in a parent's doc, the payload is scoped to it and parentDoc names that parent.",
     },
     {
       type: 'component.detail.props',
@@ -135,6 +136,14 @@ export const doc = {
     },
   ],
   throws: [
+    {
+      code: 'ERR_INVALID_DETAIL',
+      when: "options.detail is not 'full', 'compact', or 'brief'",
+    },
+    {
+      code: 'ERR_INVALID_LANG',
+      when: "options.lang is set to anything other than 'en', 'zh', or 'dense'",
+    },
     {
       code: 'ERR_CORE_NOT_FOUND',
       when: '@astryxdesign/core cannot be resolved from cwd',

package/api/component/component.mjs

@@ -34,6 +34,11 @@ import {componentDetailSource} from './detail/source/source.mjs';
 import {componentDetailShowcase} from './detail/showcase/showcase.mjs';
 import {componentDetailBlocks} from './detail/blocks/blocks.mjs';
 
+/** @type {ReadonlyArray<string>} */
+const DETAIL_LEVELS = ['full', 'compact', 'brief'];
+/** @type {ReadonlyArray<string>} */
+const LANGS = ['en', 'zh', 'dense'];
+
 /**
  * @param {string} [name]
  * @param {object} [options]
@@ -81,6 +86,23 @@ export async function component(name, options = {}) {
   const isListView = list || category != null || !name;
   const detail = detailOption ?? (isListView ? 'brief' : 'full');
 
+  // Same accepted values and codes as the CLI's --detail and --lang, checked
+  // first as the CLI parser does.
+  if (!DETAIL_LEVELS.includes(detail)) {
+    throw new AstryxError(
+      `Invalid detail "${String(detail)}". Valid levels: ${DETAIL_LEVELS.join(', ')}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_DETAIL,
+    );
+  }
+  if (lang != null && !LANGS.includes(lang)) {
+    throw new AstryxError(
+      `Invalid lang "${String(lang)}". Valid values: ${LANGS.join(', ')}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_LANG,
+    );
+  }
+
   const coreDir = requireCoreDir(cwd);
 
   // A public API caller could pass a non-string category; the list leaf does
@@ -156,6 +178,13 @@ export async function component(name, options = {}) {
     }
     const extDocPath = resolveLegacyExternalDoc(scoped.ext, dirName);
     if (extDocPath) {
+      // Legacy packages ship docs, never source.
+      if (source) {
+        return componentDetailSource(dirName, null, {name, notFoundInPackage: packageScope});
+      }
+      if (blocks) {
+        return componentDetailBlocks(dirName);
+      }
       const docs = await loadComponentDoc(extDocPath, docOpts);
       if (props) return componentDetailProps(docs);
       return componentDetail(docs, {package: scoped.ext.name, sourcePath: null}, dirName, coreDir);

package/api/component/component.test.mjs

@@ -14,6 +14,7 @@ import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {component} from './component.mjs';
 import {AstryxError} from '../error.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
 
 // api/component/ -> up 4 = repo root (has packages/core, which findCoreDir walks to).
 const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
@@ -161,3 +162,40 @@ describe('component dispatcher — category guard', () => {
     }
   }, SLOW);
 });
+
+describe('component dispatcher — detail and lang guards', () => {
+  // `detail` and `lang` are the same controls as the CLI's --detail and --lang:
+  // same accepted values, same error codes.
+  it('rejects a detail level the CLI rejects, with the same code', async () => {
+    const cliRun = await runCli(['--json', 'component', '--list', '--detail', 'bogus'], cwd);
+    expect(cliRun.code).toBe(1);
+    expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_DETAIL');
+
+    const bogus = /** @type {any} */ ('bogus');
+    for (const call of [
+      () => component(undefined, {cwd, list: true, detail: bogus}),
+      () => component('Button', {cwd, detail: bogus}),
+    ]) {
+      const err = await call().catch(e => e);
+      expect(err).toBeInstanceOf(AstryxError);
+      expect(err.code).toBe('ERR_INVALID_DETAIL');
+    }
+  }, SLOW);
+
+  it('rejects a lang the CLI rejects, with the same code', async () => {
+    const cliRun = await runCli(['--json', 'component', 'Button', '--lang', 'fr'], cwd);
+    expect(cliRun.code).toBe(1);
+    expect(JSON.parse(cliRun.stdout).code).toBe('ERR_INVALID_LANG');
+
+    for (const call of [
+      () => component('Button', {cwd, lang: 'fr'}),
+      () => component(undefined, {cwd, list: true, detail: 'compact', lang: 'fr'}),
+    ]) {
+      const err = await call().catch(e => e);
+      expect(err).toBeInstanceOf(AstryxError);
+      expect(err.code).toBe('ERR_INVALID_LANG');
+    }
+    const zh = await component('Button', {cwd, lang: 'zh'});
+    expect(zh.type).toBe('component.detail');
+  }, SLOW);
+});

package/api/component/component.type.d.mts

@@ -59,7 +59,17 @@ export type ComponentBriefEntry = {
  */
 export type ComponentDetailResponse = {
     type: "component.detail";
-    data: import("@astryxdesign/cli/authoring").ComponentDoc & ComponentOwnership;
+    data: import("@astryxdesign/cli/authoring").ComponentDoc & ComponentOwnership & ComponentDetailScope;
+};
+/**
+ * Present only when the requested name is a sub-component documented inside a
+ * parent's doc (e.g. `HStack` in the `Stack` doc); the payload is scoped to it.
+ */
+export type ComponentDetailScope = {
+    /**
+     * - Name of the parent doc the payload was scoped from, e.g. 'Stack'.
+     */
+    parentDoc?: string | undefined;
 };
 /**
  * Ownership metadata attached to every `component.detail` payload. Exposes the

package/api/component/component.type.mjs

@@ -73,7 +73,14 @@
  * astryx --json component <name>
  * @typedef {object} ComponentDetailResponse
  * @property {'component.detail'} type
- * @property {import('@astryxdesign/cli/authoring').ComponentDoc & ComponentOwnership} data
+ * @property {import('@astryxdesign/cli/authoring').ComponentDoc & ComponentOwnership & ComponentDetailScope} data
+ */
+
+/**
+ * Present only when the requested name is a sub-component documented inside a
+ * parent's doc (e.g. `HStack` in the `Stack` doc); the payload is scoped to it.
+ * @typedef {object} ComponentDetailScope
+ * @property {string} [parentDoc] - Name of the parent doc the payload was scoped from, e.g. 'Stack'.
  */
 
 /**

package/api/discover/discover.doc.mjs

@@ -41,7 +41,7 @@ export const doc = {
       name: 'options.components',
       type: 'boolean',
       description:
-        'List components only. A CLI display flag consumed by the renderer; the programmatic response shape is unchanged.',
+        'In the CLI package list, print every component of each package instead of the first 10. A display flag for the CLI renderer; the programmatic response is unchanged.',
     },
     {
       name: 'options.lang',

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

@@ -32,17 +32,19 @@ export const doc = {
       name: 'component',
       type: 'string',
       description:
-        'Component or general design-system area. Required unless listCategories is true.',
+        'Component or general design-system area, up to 120 characters. Required unless listCategories is true.',
     },
     {
       name: 'options.category',
       type: 'GapReportCategory',
-      description: 'Fixed category from the reported category vocabulary.',
+      description:
+        'Fixed category from the reported category vocabulary. Required unless listCategories is true.',
     },
     {
       name: 'options.reason',
       type: 'string',
-      description: 'What capability was missing or difficult.',
+      description:
+        'What capability was missing or difficult, up to 2000 characters. Required unless listCategories is true.',
     },
     {
       name: 'options.detail',
@@ -65,7 +67,8 @@ export const doc = {
     {
       name: 'options.listCategories',
       type: 'boolean',
-      description: 'Return categories without resolving a route or writing.',
+      description:
+        'Return categories without resolving a route or writing; the component and every other option are ignored.',
       default: 'false',
     },
     {

package/api/init/init.doc.mjs

@@ -90,6 +90,10 @@ export const doc = {
       code: 'ERR_FILE_EXISTS',
       when: 'scaffolding a template would overwrite an existing page.tsx',
     },
+    {
+      code: 'ERR_PATH_TRAVERSAL',
+      when: 'the template output path resolves outside cwd, for example through a symlinked src directory',
+    },
   ],
   examples: [
     {label: 'Default setup', code: 'const r = await init();'},