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

package/README.md

@@ -30,7 +30,8 @@ The CLI documents itself, so these commands print what the installed version doe
   `astryx.integration.*` manifest, codemods, and every doc type (`ComponentDoc`,
   `TemplateDoc`, `ThemeDoc`, and the rest). Read one section with
   `astryx docs authoring <section>`, for example `astryx docs authoring config`.
-- `astryx docs cli/integrations`: the guide to building an integration package.
+- `astryx docs cli/integrations`: the guides to building an integration package,
+  from a quick start to publishing.
 - `astryx docs`: every docs topic, including the design-system guides (for
   example `tokens`, `theme`, and `layout`).
 
@@ -77,36 +78,37 @@ Options:
 
 <!-- BEGIN GENERATED: commands -->
 
-| Command       | Description                                                                   |
-| ------------- | ----------------------------------------------------------------------------- |
-| `blog`        | Read the Astryx blog from the published feed                                  |
-| `build`       | Build a page: the template to start from, or the workflow playbook (no query) |
-| `component`   | List components or print component docs                                       |
-| `discover`    | Browse and search integrations: the ones you have and the ones you could add  |
-| `docs`        | Print reference docs                                                          |
-| `doctor`      | Diagnose Astryx projects and integration packages                             |
-| `gap-report`  | Route a design-system gap to its owning package                               |
-| `hook`        | List hooks or print hook docs                                                 |
-| `init`        | Initialize the design system in your project                                  |
-| `integration` | Author and verify an Astryx integration package                               |
-| `search`      | Search components, hooks, docs, and templates in one ranked list              |
-| `swizzle`     | Copy component source for customization                                       |
-| `template`    | Inject a page or block template                                               |
-| `theme`       | Theme tools: build, export, and manage themes                                 |
-| `upgrade`     | Migrate versions and update ShadCN-copied compositions                        |
+| Command       | Description                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `blog`        | Read the Astryx blog from the published feed                                                  |
+| `build`       | Build a page: the template to start from, or the workflow playbook (no query)                 |
+| `component`   | List components or print component docs                                                       |
+| `discover`    | Browse and search integrations: the ones you have and the ones you could add                  |
+| `docs`        | Print reference docs                                                                          |
+| `doctor`      | Diagnose Astryx projects and integration packages                                             |
+| `gap-report`  | Report a missing component or feature to the package that owns it                             |
+| `hook`        | List hooks or print hook docs                                                                 |
+| `init`        | Initialize the design system in your project                                                  |
+| `integration` | Author and verify an Astryx integration package                                               |
+| `layout`      | Generate XDS layouts from compressed expressions (XLE/XLO)                                    |
+| `search`      | Search components, hooks, docs, and templates in one ranked list                              |
+| `swizzle`     | Copy component source for customization                                                       |
+| `template`    | List, show, or scaffold page and block templates                                              |
+| `theme`       | Create and build themes: add a shipped one, compile to CSS, or list what a theme can override |
+| `upgrade`     | Update your code after upgrading Astryx, and refresh ShadCN-copied components                 |
 
 <!-- END GENERATED: commands -->
 <!-- Generated by scripts/generate-cli-readme.mjs from `astryx manifest`. Run `pnpm -F @astryxdesign/cli readme`. -->
 
 ### Global options
 
-These flags work with any command:
+`--json` works with every command listed in `jsonSupported` (`astryx manifest --json`), which is every command except the bare groups such as `astryx theme`. The other four change only the reads named here; other commands ignore them:
 
 - `--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)
-- `--lang <locale>`: Language/format shorthand (`en`, `zh`, `dense`)
+- `--detail <level>`: Detail level for `component`, `hook`, and docs tree reads (such as `astryx docs cli/commands/build`), increasing in size: `brief` (names only, default for lists) < `compact` (names + 1-line descriptions) < `full` (full docs per entry). Single-item views default to `full`.
+- `--zh`: Simplified Chinese for component reads and for docs topics that have a translation (English otherwise)
+- `--dense`: Token-efficient dense text for `astryx component <Name>` and `astryx docs <topic>`
+- `--lang <locale>`: Language or format for component and docs reads: `en` (default), `zh` (as `--zh`), or `dense` (as `--dense`)
 
 ## JSON API
 
@@ -163,9 +165,9 @@ if (isError(result)) {
 | `ERR_UNKNOWN`                     | Fallback for any error without a more specific code.                                                                                                     |
 | `ERR_UNKNOWN_COMMAND`             | A top-level command name was not recognized (e.g. `astryx bogus`).                                                                                       |
 | `ERR_UNKNOWN_SUBCOMMAND`          | A subcommand under a command group was not recognized (e.g. `astryx theme bogus`).                                                                       |
-| `ERR_INVALID_OPTION`              | An unknown flag/option was passed (Commander `unknownOption`).                                                                                           |
-| `ERR_INVALID_ARGUMENT`            | An option/argument had a value Commander's parser rejected.                                                                                              |
-| `ERR_MISSING_ARGUMENT`            | A required positional argument was omitted (Commander `missingArgument`).                                                                                |
+| `ERR_INVALID_OPTION`              | An unknown option was passed, --json was given to a command without JSON output, or layout --form got a value other than compact, outline, or auto.      |
+| `ERR_INVALID_ARGUMENT`            | An argument or option value is invalid: wrong type, out of range, an unknown choice, an extra argument, or a conflicting combination.                    |
+| `ERR_MISSING_ARGUMENT`            | A required argument or option value was omitted.                                                                                                         |
 | `ERR_INVALID_LANG`                | `--lang` was given a value outside its choices (en, zh, dense).                                                                                          |
 | `ERR_INVALID_DETAIL`              | `--detail` was given a value outside its choices (full, compact, brief).                                                                                 |
 | `ERR_NODE_VERSION`                | The running Node.js version is below the supported minimum.                                                                                              |
@@ -183,8 +185,8 @@ if (isError(result)) {
 | `ERR_UNKNOWN_THEME`               | No theme matched the requested slug (theme add).                                                                                                         |
 | `ERR_INTEGRATION_ROOT_CONFLICT`   | An integration manifest already declares a different path for the requested contribution root.                                                           |
 | `ERR_INTEGRATION_EXPORT_CONFLICT` | A package export already maps a generated contribution subpath to a different target.                                                                    |
-| `ERR_UNKNOWN_PACKAGE`             | No package matched the requested name (discover).                                                                                                        |
-| `ERR_UNKNOWN_AGENT`               | An unrecognized `--agent` value was passed to agent-docs/init.                                                                                           |
+| `ERR_UNKNOWN_PACKAGE`             | No package matched the requested name.                                                                                                                   |
+| `ERR_UNKNOWN_AGENT`               | An unrecognized `--agent` value was passed to init.                                                                                                      |
 | `ERR_UNKNOWN_FEATURE`             | An unrecognized `--features` value was passed to init.                                                                                                   |
 | `ERR_UNKNOWN_CODEMOD`             | A `--codemod` value did not match any registered codemod (upgrade).                                                                                      |
 | `ERR_CODEMOD_FAILED`              | One or more codemods failed during an upgrade run.                                                                                                       |
@@ -210,7 +212,7 @@ if (isError(result)) {
 | `ERR_FETCH_FAILED`                | A network fetch (RSS feed or post text) failed.                                                                                                          |
 | `ERR_LAYOUT_PARSE`                | A layout expression failed to parse (syntax error, with line/col).                                                                                       |
 | `ERR_LAYOUT_INVALID`              | A layout expression parsed but failed validation (unknown component/prop/enum/block).                                                                    |
-| `ERR_UNCLASSIFIED_EXIT`           | Recorded in the debug log, never printed: a command exited non-zero without going through cliError/jsonError, so no stable code was available.           |
+| `ERR_UNCLASSIFIED_EXIT`           | Recorded in the debug log, never printed: a command exited non-zero without reporting an error code.                                                     |
 | `ERR_SIGNAL_TERMINATED`           | Recorded in the debug log, never printed: the process was ended by a signal (Ctrl-C, SIGTERM) before the command reached a terminal path.                |
 
 <!-- END GENERATED: error-codes -->
@@ -421,7 +423,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `init.run`                        | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted.                                                                                                                                                                                                                                                                                                                                   |
 | `init.remove`                     | Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `component.list`                  | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.                                                                                                                                                                                                                                                                                                                                                      |
+| `component.list`                  | The component catalog grouped by component group (each component's group field): `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.                                                                                                                                                                                                                                                                                                                |
 | `component.batch`                 | The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found \| not_found \| ambiguous \| error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}). |
 | `component.detail`                | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc).                                                                                                                                                                                                                                                                                                                                                             |
 | `component.detail.props`          | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -444,7 +446,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `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 template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, command, basis, reason, alternatives, ...}, pages (search's closest templates), blocks and domain as SearchResultEntry[], frame, foundation, and hint {reason, commands} when thin.                                                                                                                                                                                                                                                                                                                    |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `swizzle.copy`                    | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.                                                                                                                                                                                                                                                                                                                                               |
 | `gap-report.categories`           | The fixed gap category values and human-readable labels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `gap-report.file`                 | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.                                                                                                                                                                                                                                                                                                                                                                 |
 | `template.list`                   | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
@@ -464,16 +466,22 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `theme.targets`                   | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key.                                                                                                                                                                                                                                                                                                                                           |
 | `theme.palette.generate`          | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `upgrade.list`                    | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `upgrade.registry`                | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.                                                                                                                                                                                                                                                                                                                                                                                            |
 | `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 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.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `help`                            | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second.                                                                                     |
+| `version`                         | The CLI version, for `astryx --version --json`: {version}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `doctor`                          | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) 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: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].                                                                                                                                                                            |
 | `integration.validate`            | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `integration.template-conflicts`  | The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).                                                                                                                                                                                                                                                                                                                                                                                  |
+| `layout.check`                    | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                                                                                                                                                                                                                                                                                                                                                                                              |
+| `layout.grammar`                  | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -574,12 +582,12 @@ There is no factory: write a plain object. For editor autocomplete and
 type-checking, annotate it with the `AstryxConfig` type exported from
 `@astryxdesign/cli/authoring`.
 
-| Field                         | Type                           | Purpose                                                                                                                  |
-| ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                                                   |
-| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.                                |
-| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).                             |
-| `experimental.xle.components` | `Record<string, XleComponent>` | No effect. Its only reader was the removed `layout` command. Still accepted so existing configs keep loading; delete it. |
+| Field                         | Type                           | Purpose                                                                                         |
+| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                          |
+| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.       |
+| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).    |
+| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
 
 The config is validated against a strict schema when the CLI loads it, so an
 unknown field is a hard error rather than a silent no-op. `astryx doctor`
@@ -675,9 +683,10 @@ Warnings go to stderr and never corrupt a `--json` envelope. To inspect problems
 Core identity overlaps before publishing. Bare `astryx doctor` checks overall
 project health.
 
-For the full authoring walkthrough (component doc format, template packaging
-and `exports` requirements, and codemod authoring), see the guide:
+For the full walkthrough, from an empty folder to a published package, see the
+guides:
 
 ```bash
 astryx docs cli/integrations
+astryx docs cli/integrations/quick-start
 ```

package/api/build/build.doc.mjs

@@ -40,6 +40,7 @@ export const doc = {
       type: 'string',
       description:
         'Directory to resolve @astryxdesign/core and templates from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.type',
@@ -69,7 +70,11 @@ export const doc = {
   throws: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: 'options.type is not a known domain, or options.limit is not a positive integer',
+      when: 'a query is given and options.type is not a known domain, or options.limit is not a positive integer',
+    },
+    {
+      code: 'ERR_CORE_NOT_FOUND',
+      when: 'a query is given and @astryxdesign/core cannot be found from cwd',
     },
   ],
   examples: [

package/api/build/build.test.mjs

@@ -179,6 +179,28 @@ describe('build kit — coverage gates the pages group', () => {
     }
   });
 
+  it('does not call a page that only mentions every word a direct match', async () => {
+    // `empty state` and `command palette` name components. A page whose text
+    // mentions both words, or that renders the component, is a layout
+    // reference, not the page the reader asked for.
+    for (const query of ['empty state', 'command palette']) {
+      const r = await build(query, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error('expected build.kit');
+      expect(r.data.directMatch, query).toBe(false);
+    }
+  });
+
+  it('keeps the page and component a query names first', async () => {
+    const pageOf = async (/** @type {string} */ query) => {
+      const r = await build(query, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error('expected build.kit');
+      return r.data;
+    };
+    expect((await pageOf('checkout flow')).pages[0]).toMatchObject({name: 'checkout-wizard'});
+    expect((await pageOf('sign in with sso')).pages[0]).toMatchObject({name: 'login-sso'});
+    expect((await pageOf('search results')).domain.map(e => e.name)).toContain('PowerSearch');
+  });
+
   it('leaves single-concept queries alone (nothing to cover)', async () => {
     const r = await build('dashboard', {cwd: REPO});
     expect(r.type).toBe('build.kit');

package/api/build/kit/kit.mjs

@@ -28,6 +28,9 @@
  */
 
 import {search} from '../../search/search.mjs';
+import {findCoreDir} from '../../../foundation/fs/paths.mjs';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {getResultCoverage} from '../../search/coverage.mjs';
 import {loadPageTemplates} from '../_adapter.mjs';
 import {pickAlternatives, pickStart, rankPages} from './rank.mjs';
@@ -188,12 +191,30 @@ function chooseStart(ranked, pages, directMatch, catalog) {
  */
 export async function buildKit(query, options = {}) {
   const {cwd = process.cwd(), type, limit = 60} = options;
+  // A kit is built from Core's components, hooks, and templates. An open
+  // search without core covers the docs alone, so the kit asks for core here.
+  if (type !== 'doc' && !findCoreDir(cwd)) {
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
+  }
   // search()'s JSDoc @returns widens results to object[]; the SearchResponse
   // shape is the contract (api/search/search.type.mjs). Cast locally rather than
   // tightening the search @returns (a separate follow-up).
   const result =
     /** @type {import('../../search/search.type.mjs').SearchResponse} */ (
-      await search(query, {cwd, type, limit})
+      await search(query, {
+        cwd,
+        type,
+        // Search wider than the surfaced kit so a flood of doc matches cannot
+        // bury the page templates past the cutoff; the caller's `limit` still
+        // caps the kit below. A non-positive or non-integer limit is passed
+        // through unchanged so search rejects it (ERR_INVALID_ARGUMENT).
+        limit:
+          Number.isInteger(limit) && limit > 0 ? Math.max(limit, 200) : limit,
+      })
     );
   const results = result.data.results;
   // The TOTAL number of matches, not the number that survived `limit`. The kit
@@ -257,6 +278,24 @@ export async function buildKit(query, options = {}) {
         command: `${page.command} --skeleton`,
       }));
 
+  // The caller's `limit` caps the surfaced kit, even though the search above
+  // ran wider to find templates that a flood of doc matches would otherwise
+  // bury past the cutoff. Keep pages first, then blocks, then components.
+  let budget = limit;
+  /**
+   * @template T
+   * @param {T[]} arr
+   * @returns {T[]}
+   */
+  const toLimit = arr => {
+    const out = arr.slice(0, Math.max(0, budget));
+    budget -= out.length;
+    return out;
+  };
+  const pagesKept = toLimit(pages);
+  const blocksKept = toLimit(blocks);
+  const domainKept = toLimit(domain);
+
   // A kit narrowed to components or hooks has no page to start from; every
   // other kit does, so the reader is never left to compose a page from scratch.
   const wantsPages = !type || type === 'template';
@@ -288,7 +327,7 @@ export async function buildKit(query, options = {}) {
   // not resolve — the same defect `getCliInvocation` exists to prevent, and
   // the renderer applies it. A JSON caller gets the parts, not a sentence.
   const hint =
-    pages.length + blocks.length + domain.length < THIN_KIT
+    pagesKept.length + blocksKept.length + domainKept.length < THIN_KIT
       ? {
           reason:
             'Few matches. This is keyword search, not semantic — try other wordings.',
@@ -306,9 +345,9 @@ export async function buildKit(query, options = {}) {
       matchCount,
       directMatch,
       start,
-      pages,
-      blocks,
-      domain,
+      pages: pagesKept,
+      blocks: blocksKept,
+      domain: domainKept,
       frame: FRAME,
       foundation: FOUNDATION,
       hint,

package/api/component/component.doc.mjs

@@ -45,6 +45,7 @@ export const doc = {
       name: 'options.cwd',
       type: 'string',
       description: 'Directory to resolve @astryxdesign/core from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.list',
@@ -54,13 +55,14 @@ export const doc = {
     {
       name: 'options.category',
       type: 'string',
-      description: 'List only components in this category.',
+      description:
+        "List only the components in this group: a key of the unfiltered list (each component's group field), such as 'Layout' or 'Button'. It is not the category field of a component detail.",
     },
     {
       name: 'options.package',
       type: 'string',
       description:
-        "Scope lookup to a specific external package (e.g. '@acme/xds-widgets').",
+        "Scope lookup to a specific external package (e.g. '@acme/widgets').",
     },
     {
       name: 'options.props',
@@ -87,7 +89,8 @@ export const doc = {
       name: 'options.detail',
       type: "'full' | 'compact' | 'brief'",
       description: 'Detail level for list views.',
-      default: "'full' for a named component, 'brief' for list views",
+      default:
+        "'full' for a named component; 'brief' for lists (returned as data.detail: 'names')",
     },
     {
       name: 'options.lang',
@@ -110,7 +113,7 @@ export const doc = {
     {
       type: 'component.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
+        "The catalog grouped by component group. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names entries with name, package, and an optional canonical import for integration and legacy package components; brief entries; or full ComponentDoc entries.",
     },
     {
       type: 'component.batch',
@@ -160,7 +163,7 @@ export const doc = {
     },
     {
       code: 'ERR_UNKNOWN_CATEGORY',
-      when: 'options.category is not a string or matches no known category',
+      when: 'options.category is not a string or matches no component group',
     },
     {
       code: 'ERR_UNKNOWN_COMPONENT',
@@ -174,6 +177,10 @@ export const doc = {
       code: 'ERR_NO_DOC',
       when: 'the resolved component has no .doc.mjs typed doc file',
     },
+    {
+      code: 'ERR_INVALID_DOC',
+      when: "the resolved component's .doc.mjs fails to load or validate",
+    },
     {
       code: 'ERR_NO_SOURCE',
       when: 'options.source is set but the component has no source file',
@@ -194,8 +201,8 @@ export const doc = {
     },
     {label: 'Props only', code: "await component('Button', {props: true});"},
     {
-      label: 'Browse a category',
-      code: "await component(undefined, {category: 'Form', detail: 'compact'});",
+      label: 'Browse one group',
+      code: "await component(undefined, {category: 'Layout', detail: 'compact'});",
     },
   ],
   command: 'component',

package/api/docs/_adapter.d.mts

@@ -77,10 +77,12 @@ export function docsLinkProblems(catalog: DocsCatalog, tree: DocsTree, { owner,
 /**
  * What \`astryx doctor integration docs\` checks in one integration's docs: the
  * docs tree they build beside the CLI's (namespaces, placements, routes) and
- * every link in them (spec:AST-046, spec:AST-047).
+ * every link in them (spec:AST-046, spec:AST-047). A tree problem hides a doc,
+ * so it is an error; a link that names no doc prints as written, so it is a
+ * warning.
  * @param {{name: string}} integration
  * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
- * @returns {Promise<string[]>}
+ * @returns {Promise<Array<{severity: 'error' | 'warning', message: string}>>}
  */
 export function packageDocsProblems(integration: {
     name: string;
@@ -88,7 +90,10 @@ export function packageDocsProblems(integration: {
     records: import("../../foundation/discovery/docs-discovery.mjs").DocsTopicRecord[];
     namespaces: import("../../foundation/doc-compiler/tree.mjs").TreeNamespaceInput[];
     guides: import("../../foundation/doc-compiler/tree.mjs").TreeDocInput[];
-}): Promise<string[]>;
+}): Promise<Array<{
+    severity: "error" | "warning";
+    message: string;
+}>>;
 /**
  * How a token reference finds its target: the topic it names in `catalog`,
  * lowered for the same language.

package/api/docs/_adapter.mjs

@@ -667,10 +667,12 @@ export async function docsLinkProblems(
 /**
  * What \`astryx doctor integration docs\` checks in one integration's docs: the
  * docs tree they build beside the CLI's (namespaces, placements, routes) and
- * every link in them (spec:AST-046, spec:AST-047).
+ * every link in them (spec:AST-046, spec:AST-047). A tree problem hides a doc,
+ * so it is an error; a link that names no doc prints as written, so it is a
+ * warning.
  * @param {{name: string}} integration
  * @param {{records: import('../../foundation/discovery/docs-discovery.mjs').DocsTopicRecord[], namespaces: import('../../foundation/doc-compiler/tree.mjs').TreeNamespaceInput[], guides: import('../../foundation/doc-compiler/tree.mjs').TreeDocInput[]}} discovered
- * @returns {Promise<string[]>}
+ * @returns {Promise<Array<{severity: 'error' | 'warning', message: string}>>}
  */
 export async function packageDocsProblems(integration, discovered) {
   const catalog = DocsCatalog.fromBuiltins();
@@ -680,12 +682,18 @@ export async function packageDocsProblems(integration, discovered) {
     guides: discovered.guides.map(input => ({...input, rank: 1})),
   });
   const tree = await projectTree(catalog);
+  /** @type {Array<{severity: 'error' | 'warning', message: string}>} */
   const problems = tree.diagnostics
     .filter(d => d.severity === 'error' && d.provider === integration.name)
-    .map(d => `${d.source ?? integration.name}: ${d.message}`);
-  problems.push(
-    ...(await docsLinkProblems(catalog, tree, {owner: integration.name})),
-  );
+    .map(d => ({
+      severity: /** @type {const} */ ('error'),
+      message: `${d.source ?? integration.name}: ${d.message}`,
+    }));
+  for (const message of await docsLinkProblems(catalog, tree, {
+    owner: integration.name,
+  })) {
+    problems.push({severity: 'warning', message});
+  }
   return problems;
 }
 

package/api/docs/docOverlays.test.mjs

@@ -76,6 +76,32 @@ describe('reference doc overlays (#2182)', () => {
       ).toEqual([]);
     });
 
+    it(`${topic} --${variant}: every content override lands on a block of its own type`, async () => {
+      // Blocks are matched by index and type, and a mismatch is dropped with
+      // no warning: a prose override aimed at a code block leaves the base
+      // text in place, so the reader gets a translated title over an English
+      // body. Pad with null to reach the block you mean.
+      const base = await load(basePath);
+      const overlayMod = await load(overlayPath);
+      const overlay = overlayMod.docsDense || overlayMod.docsZh;
+      const byTitle = new Map(base.docs.sections.map(s => [s.title, s]));
+      const dropped = [];
+      for (const entry of overlay.sections || []) {
+        const section = byTitle.get(entry.section);
+        if (!section) continue;
+        (entry.content || []).forEach((block, i) => {
+          if (block == null) return;
+          const target = section.content[i];
+          if (target?.type !== block.type) {
+            dropped.push(
+              `${entry.section} block ${i}: ${block.type} over ${target?.type ?? 'nothing'}`,
+            );
+          }
+        });
+      }
+      expect(dropped, `${topic}.doc.${variant}.mjs overrides that never apply`).toEqual([]);
+    });
+
     it(`${topic} --${variant}: no base section is overridden twice`, async () => {
       const overlayMod = await load(overlayPath);
       const overlay = overlayMod.docsDense || overlayMod.docsZh;
@@ -127,7 +153,7 @@ describe('the reported defect: docs tokens --dense (#2182)', () => {
     const zh = await docs('theme', null, {zh: true});
     const titles = zh.data.sections.map(s => s.title);
     // Every section the overlay translates must appear once, in Chinese only.
-    expect(titles).not.toContain('Light/Dark Mode');
+    expect(titles).not.toContain('Dark mode');
     expect(titles).toContain('亮/暗模式');
   });
 });

package/api/docs/docs.doc.mjs

@@ -27,7 +27,7 @@ export const doc = {
     'A route opens a node of the docs tree instead: a namespace such as ' +
     "`cli/api` returns its children one level down, a typed doc such as " +
     "`cli/api/functions/search` returns its content, and a guide the tree " +
-    'places (`cli/integrations`) reads like any topic. ' +
+    'places (`cli/integrations/quick-start`) reads like any topic. ' +
     'Every read but the list carries `links`, the commands that move from it: ' +
     '`up` to the level it sits in, `previous` and `next` to its neighbors, and, ' +
     'for a typed doc, `related` to the docs it names (its command or function, ' +
@@ -137,7 +137,7 @@ export const doc = {
     {label: 'One API function', code: "await docs('cli/api/functions/search');"},
     {
       label: 'A whole guide from the docs tree',
-      code: "await docs('cli/integrations');",
+      code: "await docs('cli/integrations/quick-start');",
     },
     {label: 'One section by key', code: "await docs('tokens', 'spacing');"},
   ],

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'});",