@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

package/README.md

@@ -15,6 +15,26 @@ npx @astryxdesign/cli template --list
 
 Once it's a project dependency (`npm install -D @astryxdesign/cli`), drop the scope and use the shorter `astryx` — e.g. `npx astryx component Button` or `pnpm exec astryx component Button`. Bare `astryx` resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.
 
+## Reading the CLI's own docs
+
+The CLI documents itself, so these commands print what the installed version does:
+
+- `astryx <command> --help`: one command's arguments and options.
+- `astryx manifest --json`: every command, option, and response type, as JSON.
+- `astryx docs cli`: the CLI's docs tree, one level at a time.
+  `astryx docs cli/commands` lists every command, `astryx docs cli/api` lists
+  the API's functions, schemas, and enums, and a route such as
+  `astryx docs cli/api/functions/search` prints one.
+- `astryx docs authoring --index`: the authoring reference, with one section for
+  each file an author writes: the `astryx.config.*` file, the
+  `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 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`).
+
 ## Finding things: `astryx search`
 
 When you don't know whether what you need is a component, a hook, a docs topic,
@@ -51,57 +71,58 @@ 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
 
 <!-- BEGIN GENERATED: commands -->
 
-| Command       | Description                                                                   |
-| ------------- | ----------------------------------------------------------------------------- |
-| `blog`        | Read the Astryx blog from the published feed                                  |
-| `build`       | Build a page: composition kit for an idea, or the workflow playbook (no args) |
-| `component`   | List components or print component docs                                       |
-| `discover`    | Discover external packages and components                                     |
-| `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                               |
-| `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`    | 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: `{ type, data }` (errors: `{ 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`)
+- `--json`: Output as typed JSON envelope: `{ apiVersion, type, data, meta? }` (errors: `{ apiVersion, error, code, suggestions? }`)
+- `--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
 
 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"}]
@@ -144,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.                                                                                              |
@@ -164,21 +185,23 @@ 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.                                                                                                       |
+| `ERR_CODEMOD_PROTECTED`           | A required codemod change remains blocked by a protected consumer file.                                                                                  |
+| `ERR_CODEMOD_PROTECTION_SOURCE`   | A working-tree protection declaration could not be read or parsed.                                                                                       |
 | `ERR_NOT_FOUND`                   | A generic discover/lookup query matched nothing in any package.                                                                                          |
 | `ERR_NO_DOC`                      | A component exists but has no typed `.doc.mjs` file.                                                                                                     |
 | `ERR_NO_SHOWCASE`                 | No showcase exists for the requested component.                                                                                                          |
 | `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.                                                                                              |
+| `ERR_THEME_INVALID`               | A theme definition or contributed theme descriptor is invalid.                                                                                           |
 | `ERR_THEME_LOAD`                  | A theme file could not be loaded / parsed into a defineTheme result.                                                                                     |
 | `ERR_PALETTE_GENERATION`          | A palette generation request or one of its constraints was invalid.                                                                                      |
 | `ERR_VERSION_DETECT`              | The current `@astryxdesign/core` version could not be detected.                                                                                          |
@@ -189,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 -->
@@ -199,8 +222,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 +286,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 +371,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;
 
@@ -391,62 +419,69 @@ Every response has a `type` discriminant. The full set is below (generated from
 
 <!-- BEGIN GENERATED: response-types -->
 
-| Type                              | What `data` carries                                                                                                                                                                                                                                                                           |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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.detail`                | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).                                                                                                                                                             |
-| `component.detail.props`          | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                                                                                        |
-| `component.detail.source`         | One component's source file, as {component, source}.                                                                                                                                                                                                                                          |
-| `component.detail.showcase`       | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                                                                        |
-| `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                                                                    |
-| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                                                                                       |
-| `docs.detail`                     | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                                                                                 |
-| `docs.detail.section`             | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                                                                                       |
-| `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                      |
-| `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                     |
-| `discover.list`                   | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                            |
-| `discover.detail`                 | A single external package entry, for an @scope/name query.                                                                                                                                                                                                                                    |
-| `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.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.                                                                                                                |
-| `gap-report.categories`           | The fixed gap category values and human-readable labels.                                                                                                                                                                                                                                      |
-| `gap-report.file`                 | An aggregate receipt with overall status, the selected package and issues URL, ordered per-handler deliveries, and filedCount/routedOnlyCount totals.                                                                                                                                         |
-| `template.list`                   | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.                                                                                                                          |
-| `template.show`                   | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                                                           |
-| `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                                                                  |
-| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                                                                         |
-| `template.cdn`                    | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                            |
-| `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.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.                                                                                                                                             |
-| `theme.add`                       | A scaffold receipt: resolved slug, displayName, maintained flag, owner package, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                                                                     |
-| `theme.template`                  | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                                                                  |
-| `theme.targets`                   | The whole themeable surface: the echoed filter, the component count, and one entry per theming target — {key, className, component, props, states}, where props and states are its legal override keys.                                                                                       |
-| `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.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.                                                                 |
-| `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.                                                                                                                                                                             |
-| `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 conflicts where an integration template id is also owned by Core; each conflict includes the exact package-qualified 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 classified as intentional replacements, intentional extensions, or accidental same-name conflicts.                                                                                                                         |
-| `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.                                                                                                                           |
+| Type                              | What `data` carries                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 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[]).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `component.detail.source`         | One component's source file, as {component, source}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `component.detail.showcase`       | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load.                                                                                                                                                                                                                                                                                                                                                                                           |
+| `docs.detail`                     | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                                                                                                                                                                                                                                                                                                                        |
+| `docs.index`                      | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                                                                                                                                                                                             |
+| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it).                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `docs.node`                       | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names).                                                                                                                                                                                                                                                                                                      |
+| `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `discover.list`                   | The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                                                                                                                                                                              |
+| `discover.detail`                 | One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `discover.detail.doc`             | The validated ComponentDoc for one installed component, for an @scope/name/Component query.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `discover.item`                   | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `discover.search`                 | The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list.                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates).                                                                                                                                                                                                                   |
+| `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, 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.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `template.show`                   | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `template.cdn`                    | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                                                                                                                                                                                                                                                                                                                                    |
+| `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, 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `theme.add`                       | A scaffold receipt: resolved slug, displayName, maintained flag, owner package, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `theme.template`                  | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `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.                                                                                                                                                                                                                                                                                                                                    |
+| `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`. -->
@@ -455,25 +490,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.
 ```
@@ -631,17 +674,19 @@ wrong type fails there; a field this CLI does not know is ignored with a
 warning naming it, so a manifest written against a newer CLI still contributes
 everything this one understands.
 
-Discovery is resilient: a broken or misconfigured integration is skipped with a
-one-line warning on stderr instead of crashing the CLI, and it never corrupts a
-`--json` envelope. To inspect problems, run
+Discovery is resilient. A manifest load failure skips that package with a warning.
+An invalid contribution kind remains reportable without hiding other valid kinds,
+and invalid template or component metadata is omitted without hiding valid siblings.
+Warnings go to stderr and never corrupt a `--json` envelope. To inspect problems, run
 `astryx doctor integration validate <package>` for structure, then use `templates`,
 `components`, or `docs` under the same `astryx doctor integration` group to check
 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
+astryx docs cli/integrations/quick-start
 ```

package/api/blog/blog.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'blog',
+  namespace: 'cli/api',
   displayName: 'blog()',
   summary: 'List blog posts, or read one, from the published RSS feed.',
   description:

package/api/build/_adapter.d.mts

@@ -0,0 +1,50 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * A page template the kit can recommend starting from.
+ * @typedef {object} PageTemplate
+ * @property {string} name The template's own id, as search reports it.
+ * @property {string} command `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
+ * @property {string} displayName Human-facing name.
+ * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} category The template's own `Family - Variant` label; empty when it declares none.
+ */
+/**
+ * Every ready page template the project can scaffold, in discovery order. This
+ * is the default discovery view: an active integration replacement stands in
+ * for the Core template it replaces, as it does for `astryx template <id>`.
+ *
+ * Discovery failures leave the kit without a start rather than failing the
+ * command: the kit still carries its search matches, and `template --list`
+ * reports what went wrong.
+ *
+ * @param {string} cwd
+ * @returns {Promise<PageTemplate[]>}
+ */
+export function loadPageTemplates(cwd: string): Promise<PageTemplate[]>;
+/**
+ * A page template the kit can recommend starting from.
+ */
+export type PageTemplate = {
+    /**
+     * The template's own id, as search reports it.
+     */
+    name: string;
+    /**
+     * `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
+     */
+    command: string;
+    /**
+     * Human-facing name.
+     */
+    displayName: string;
+    /**
+     * What the page is: its layout and the ideas it serves.
+     */
+    description: string;
+    /**
+     * The template's own `Family - Variant` label; empty when it declares none.
+     */
+    category: string;
+};