@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/README.md

@@ -13,7 +13,19 @@ npx @astryxdesign/cli docs migration
 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.
+Once it's a project dependency (`npm install -D @astryxdesign/cli`), the same scoped commands run the version you installed, or use your package manager's runner with the shorter name, such as `pnpm exec astryx component Button`. Never run the unscoped name through npx before the CLI is installed: `astryx` alone resolves to an unrelated npm package.
+
+## Install it once for your computer
+
+```bash
+npm i -g @astryxdesign/cli
+```
+
+Then `astryx` works in any folder, for you and for every coding agent on your computer. In a project, Astryx runs the project's own version, so a global install never changes what a project gets; outside a project, your global version answers. It tells you when a newer version is out, and never upgrades itself or a project.
+
+- Project install, global install, or both (recommended)? `astryx docs global/project-global-or-both` compares them.
+- How it works, and what it prints: `astryx docs global`.
+- Something looks wrong: `astryx docs global/problems`. Uninstall: `astryx docs global/uninstall`.
 
 ## Reading the CLI's own docs
 
@@ -65,7 +77,7 @@ Results for "button" (20 of 239):
                → astryx template BannerCollapsibleContent
 ```
 
-(The CLI prints the follow-up commands with your actual runner — `npx astryx …` when installed, or `npx @astryxdesign/cli …` when run one-off.)
+(The CLI prints the follow-up commands so they reach the release that answered — the project's runner, such as `pnpm exec astryx …`, when the project's own CLI answered, `astryx …` outside a project for the copy installed for your computer, or the package pinned to the answering release, such as `npx @astryxdesign/cli@0.7.2 …`, otherwise — or with the command an installed integration sets as its `cliCommand`.)
 
 Options:
 
@@ -76,25 +88,27 @@ Options:
 
 ## Commands
 
+Each command declares what it does in a folder outside any project, and `astryx manifest --json` publishes it as `outsideProject`: `same` gives the answer a new project on this release would get, `refuse` writes nothing and fails with `ERR_PROJECT_REQUIRED` (or the code its earlier releases used), and `own` does something else that its docs (`astryx docs cli/commands/<name>`) describe.
+
 <!-- 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`  | 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                               |
-| `search`      | Search components, hooks, docs, templates, and themes in one ranked list      |
-| `swizzle`     | Copy component source for customization                                       |
-| `template`    | List, show, or scaffold page and block templates                              |
-| `theme`       | Add, switch, build, and author themes                                         |
-| `upgrade`     | Update your code after upgrading Astryx, and refresh ShadCN-copied components |
+| Command       | Description                                                                   | Outside a project |
+| ------------- | ----------------------------------------------------------------------------- | ----------------- |
+| `blog`        | Read the Astryx blog from the published feed                                  | `same`            |
+| `build`       | Build a page: the template to start from, or the workflow playbook (no query) | `same`            |
+| `component`   | List components or print component docs                                       | `same`            |
+| `discover`    | Browse and search integrations: the ones you have and the ones you could add  | `same`            |
+| `docs`        | Print reference docs                                                          | `same`            |
+| `doctor`      | Diagnose Astryx projects and integration packages                             | `own`             |
+| `gap-report`  | Report a missing component or feature to the package that owns it             | `same`            |
+| `hook`        | List hooks or print hook docs                                                 | `same`            |
+| `init`        | Initialize the design system in your project                                  | `own`             |
+| `integration` | Author and verify an Astryx integration package                               | by subcommand     |
+| `search`      | Search components, hooks, docs, templates, and themes in one ranked list      | `same`            |
+| `swizzle`     | Copy component source for customization                                       | `refuse`          |
+| `template`    | List, show, or scaffold page and block templates                              | `same`            |
+| `theme`       | Add, switch, build, and author themes                                         | by subcommand     |
+| `upgrade`     | Update your code after upgrading Astryx, and refresh ShadCN-copied components | `own`             |
 
 <!-- END GENERATED: commands -->
 <!-- Generated by scripts/generate-cli-readme.mjs from `astryx manifest`. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -114,9 +128,11 @@ Options:
 Every command supports `--json` for machine-readable output. Responses are typed envelopes:
 
 ```json
-{"apiVersion": 1, "type": "component.detail", "data": {"name": "Button", ...}}
+{"apiVersion": 1, "type": "component.detail", "data": {"name": "Button", ...}, "meta": {"answeredBy": {"cli": "0.7.2", "core": "0.7.2", "copy": "project"}}}
 ```
 
+Every successful envelope carries `meta.answeredBy`: the CLI version that answered, the Core version it paired with (`null` when there is none), and which copy answered (`project`, `starting`, `matched`, `carried`, or `fallback`).
+
 Errors:
 
 ```json
@@ -159,60 +175,62 @@ if (isError(result)) {
 
 <!-- BEGIN GENERATED: error-codes -->
 
-| Code                              | Meaning                                                                                                                                                  |
-| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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 option was passed, --json was given to a command without JSON output.                                                                         |
-| `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.                                                                                              |
-| `ERR_CORE_NOT_FOUND`              | `@astryxdesign/core` could not be located (not installed / not in a monorepo).                                                                           |
-| `ERR_CORE_INCOMPATIBLE`           | The installed `@astryxdesign/core` loaded but is too old for this input — it lacks a capability the CLI must call to emit correct output (upgrade core). |
-| `ERR_UNKNOWN_COMPONENT`           | No component matched the requested name.                                                                                                                 |
-| `ERR_UNKNOWN_HOOK`                | No hook matched the requested name.                                                                                                                      |
-| `ERR_UNKNOWN_TOPIC`               | No docs topic matched the requested name.                                                                                                                |
-| `ERR_UNKNOWN_SECTION`             | A docs topic exists but the requested section within it does not.                                                                                        |
-| `ERR_UNKNOWN_CATEGORY`            | A `--category` filter value did not match any known category.                                                                                            |
-| `ERR_UNKNOWN_TEMPLATE`            | No template matched the requested name.                                                                                                                  |
-| `ERR_AMBIGUOUS_TEMPLATE`          | A template id matched more than one template (narrow with --type/--package).                                                                             |
-| `ERR_AMBIGUOUS_COMPONENT`         | A component name is owned by more than one package (narrow with --package).                                                                              |
-| `ERR_AMBIGUOUS_THEME`             | A theme slug is owned by more than one package (narrow with --package).                                                                                  |
-| `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.                                                                                                                   |
-| `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.                                                                                                                   |
-| `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 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.                                                                                          |
-| `ERR_INVALID_VERSION`             | A `--from`/`--to` value was not a valid semver string.                                                                                                   |
-| `ERR_DEP_MISSING`                 | A required external dependency (e.g. jscodeshift) is missing.                                                                                            |
-| `ERR_GH_CLI`                      | GitHub CLI (`gh`) is not installed or not authenticated.                                                                                                 |
-| `ERR_UNKNOWN_POST`                | No blog post matched the requested slug in the feed.                                                                                                     |
-| `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 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.                |
+| Code                              | Meaning                                                                                                                                                                                            |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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 option was passed, --json was given to a command without JSON output.                                                                                                                   |
+| `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.                                                                                                                                        |
+| `ERR_CORE_NOT_FOUND`              | `@astryxdesign/core` could not be located (not installed / not in a monorepo).                                                                                                                     |
+| `ERR_CORE_INCOMPATIBLE`           | The installed `@astryxdesign/core` loaded but is too old for this input — it lacks a capability the CLI must call to emit correct output (upgrade core).                                           |
+| `ERR_UNKNOWN_COMPONENT`           | No component matched the requested name.                                                                                                                                                           |
+| `ERR_UNKNOWN_HOOK`                | No hook matched the requested name.                                                                                                                                                                |
+| `ERR_UNKNOWN_TOPIC`               | No docs topic matched the requested name.                                                                                                                                                          |
+| `ERR_UNKNOWN_SECTION`             | A docs topic exists but the requested section within it does not.                                                                                                                                  |
+| `ERR_UNKNOWN_CATEGORY`            | A `--category` filter value did not match any known category.                                                                                                                                      |
+| `ERR_UNKNOWN_TEMPLATE`            | No template matched the requested name.                                                                                                                                                            |
+| `ERR_AMBIGUOUS_TEMPLATE`          | A template id matched more than one template (narrow with --type/--package).                                                                                                                       |
+| `ERR_AMBIGUOUS_COMPONENT`         | A component name is owned by more than one package (narrow with --package).                                                                                                                        |
+| `ERR_AMBIGUOUS_THEME`             | A theme slug is owned by more than one package (narrow with --package).                                                                                                                            |
+| `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.                                                                                                                                                             |
+| `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.                                                                                                                                                             |
+| `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 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.                                                                                                                                    |
+| `ERR_INVALID_VERSION`             | A `--from`/`--to` value was not a valid semver string.                                                                                                                                             |
+| `ERR_DEP_MISSING`                 | A required external dependency (e.g. jscodeshift) is missing.                                                                                                                                      |
+| `ERR_GH_CLI`                      | GitHub CLI (`gh`) is not installed or not authenticated.                                                                                                                                           |
+| `ERR_UNKNOWN_POST`                | No blog post matched the requested slug in the feed.                                                                                                                                               |
+| `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 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.                                                          |
+| `ERR_VERSIONS_UNAVAILABLE`        | Nothing could answer this run, and nothing was written: the project's own CLI could not start and nothing else could answer, or the Core a command needs outside a project could not be installed. |
+| `ERR_PROJECT_REQUIRED`            | The command needs a project (an app with Astryx installed, or an integration package) and was run outside one. Nothing was written.                                                                |
 
 <!-- END GENERATED: error-codes -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the error-codes EnumDoc (== ERROR_CODES). Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -419,67 +437,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`                     | The removal receipt — returned when --remove-agents is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `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 ({name, package, description, import}), or a full ComponentDoc per entry with its package.                                                                                                                                                                                                                                                                                                                                                |
-| `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). The envelope's package names the same owner.                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `component.detail.props`          | Just one component's props table (ComponentPropDoc[]). The envelope's package names the npm package that owns the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `component.detail.source`         | One component's source file, as {component, source}. The envelope's package names the npm package that owns the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `component.detail.showcase`       | One component's showcase example, as {component, aspectRatio, source}. The envelope's package names the npm package that owns the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry ({name, package, displayName, description, isShowcase, category}); each block names the package that owns it, and the envelope's package names the component's owner.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `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 and each section naming the package that wrote it, 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, package, summary} (pass the id as the section argument; package is the npm package that wrote the section; 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). The envelope's package names the npm package that wrote the section.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `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, each naming its package) 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, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), 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, package, command, basis, reason, alternatives, ...} (the start and each alternative name the package that owns the template), pages (search's closest templates), blocks and domain as SearchResultEntry[] (each naming its package), frame and foundation (Core component names), and hint {reason, commands} when thin.                                                                                                                                                                                                                                                                      |
-| `swizzle.list`                    | The names of swizzlable components discoverable from cwd's @astryxdesign/core. The envelope's package is @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. The envelope's package names the same owning package.                                                                                                                                                                                                                                                                                                                                                                                 |
-| `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 source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. The envelope's package names the npm package that owns the template.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing, or when several lockfiles leave the package manager undetermined). The envelope's package names the npm package that owns the template. |
-| `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. The envelope's package is @astryxdesign/core, the only package that ships hooks.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `hook.detail`                     | One hook's full authored HookDoc. The envelope's package is @astryxdesign/core.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `hook.detail.params`              | Just one hook's parameters table (HookParamDoc[]). The envelope's package is @astryxdesign/core.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `theme.build`                     | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, cssDts, 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, installed package, and local theme as a ThemeListEntry[]. Each entry has slug, displayName, description, maintained, owner package or local root, source, added, and default fields. Optional meta.unmigratedCopies names earlier descriptor-less copies, their missing descriptor, and the upgrade command; those copies are not data entries.                                                                                                                                                                                                                                                                                                                                                |
-| `theme.app`                       | The app theme record after add, remove, or use. It includes every added theme and its built imports, the default slug, generated module path, and the command change. After add, the envelope package names the npm package that owns the added theme; a local theme has none.                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `theme.eject`                     | A local source-fork receipt with the resolved slug, displayName, source theme maintained flag, source-selector package, outputDir, source entry, exportName, and every file written, including the descriptor. The written local descriptor always uses maintained: false.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `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}, 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, package, 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, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), 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: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                                                     |
-| `integration.template-conflicts`  | validated (false when no integration manifest was found, so nothing was inspected), 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` | validated (false when no integration manifest was found, so nothing was inspected), 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`       | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| 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`                     | The removal receipt — returned when --remove-agents is set: `data.removed` is true when a managed agent-docs block was found and removed, and false when there was none to remove.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `init.user`                       | The computer-level agent text receipt — returned when --user is set: `data.files`, one `{path, action, reason?}` per path acted on, the skill file first and then each link to its folder (action `written` \| `linked` \| `unchanged` \| `removed` \| `absent` \| `kept`; `reason` only on `kept`: `edited` when a person changed the text, `not-astryx` when Astryx did not write it), `data.command` (the command the text names), and `data.warnings`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `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 ({name, package, description, import}), or a full ComponentDoc per entry with its package.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `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). The envelope's package names the same owner.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `component.detail.props`          | Just one component's props table (ComponentPropDoc[]). The envelope's package names the npm package that owns the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `component.detail.source`         | One component's source file, as {component, source}. The envelope's package names the npm package that owns the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `component.detail.showcase`       | One component's showcase example, as {component, aspectRatio, source}. The envelope's package names the npm package that owns the component.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry ({name, package, displayName, description, isShowcase, category}); each block names the package that owns it, and the envelope's package names the component's owner.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `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 and each section naming the package that wrote it, 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, package, summary} (pass the id as the section argument; package is the npm package that wrote the section; 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). The envelope's package names the npm package that wrote the section.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `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, each naming its package) 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`                   | What the project has, the integrations it loads and the official packages it declares, official packages first (name, category, components, version, a list per other kind they add, and latest when a source knows it); meta.available lists what the project could add, the official packages first, each with the command that adds it, and meta.sources reports each source, the official list last; when it lists no integration 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, package, score, reason, description, command} (package is the npm package that owns the result), plus import (components, hooks), title, parent (the command that opens the level above), and, for a hit on one section, section (docs), or displayName and kind (templates). When a search with no `type` could not obtain @astryxdesign/core, `meta.partial` is {skipped, reason}: the domains it skipped (component, hook, template) and why.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `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, package, command, basis, reason, alternatives, ...} (the start and each alternative name the package that owns the template), pages (search's closest templates), blocks and domain as SearchResultEntry[] (each naming its package), frame and foundation (Core component names), and hint {reason, commands} when thin.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `swizzle.list`                    | The names of swizzlable components discoverable from cwd's @astryxdesign/core. The envelope's package is @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. The envelope's package names the same owning package.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `gap-report.categories`           | The fixed gap category values and human-readable labels; when a loaded integration names its own issues URL, meta.destinations lists every destination ({to, default, issuesUrl}) and meta.ask tells an agent to ask the person.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `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; without --to, when a loaded integration names its own issues URL, destinations and ask as on gap-report.categories.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `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 source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. The envelope's package names the npm package that owns the template.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, file count, demoMediaReplaced (how many Astryx demo media references were replaced with placeholders), notes (setup notes naming what the template needs that the project lacks — missing packages, missing StyleX compiler; empty when satisfied), missingPackages (external package names the template imports that are not in the project), and installCommand (a ready-to-run install command with the detected package manager and workspace version ranges; null when nothing is missing, or when several lockfiles leave the package manager undetermined). The envelope's package names the npm package that owns the template.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `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. The envelope's package is @astryxdesign/core, the only package that ships hooks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `hook.detail`                     | One hook's full authored HookDoc. The envelope's package is @astryxdesign/core.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `hook.detail.params`              | Just one hook's parameters table (HookParamDoc[]). The envelope's package is @astryxdesign/core.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `theme.build`                     | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, cssDts, 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, installed package, and local theme as a ThemeListEntry[]. Each entry has slug, displayName, description, maintained, owner package or local root, source, added, and default fields. Optional meta.unmigratedCopies names earlier descriptor-less copies, their missing descriptor, and the upgrade command; those copies are not data entries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `theme.app`                       | The app theme record after add, remove, or use. It includes every added theme and its built imports, the default slug, generated module path, and the command change. After add, the envelope package names the npm package that owns the added theme; a local theme has none.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `theme.eject`                     | A local source-fork receipt with the resolved slug, displayName, source theme maintained flag, source-selector package, outputDir, source entry, exportName, and every file written, including the descriptor. The written local descriptor always uses maintained: false.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `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}, 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, package, 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. no_codemods and config_fixable carry cliBehindCore ({cliVersion, command}) when the installed Core is newer than the CLI, which then has no codemods for the releases after its own version.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors. When the installed Core is newer than the CLI, it also carries cliBehindCore ({cliVersion, command}): codemods for the releases after cliVersion did not run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `manifest`                        | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], outsideProject? (same, refuse, or own; absent on a group), subcommands?), jsonSupported, globalMode ({docs, summary}: what a run may do beyond its command, such as the hand-off to the project's own CLI, the daily update check, and the agent skill file, and the docs topic that explains it), 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, fix?, file?, line?}] (the issues validation finds in the source and, prefixed packed_, in the packed tree, with the fix and the place when the check knows them).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `integration.validate`            | The validation result: validated (false when nothing was validated: with no package.json the issues list carries one no_package error so the command exits 1, and with a package.json but no integration manifest the issues list is empty and proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message, fix?, file?, line?} (fix: the change that resolves it; file and line: where, relative to the package), and notes when there are any: {code, message} information that fails nothing, such as invalid_cli_command for a malformed cliCommand. When the manifest loads, docTypes checks each doc against its published authoring type: status (checked \| skipped), reason, typescript, docs, findings (all warnings, each naming the field and a fix), unchecked, and fixtures (test fixture docs not checked).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `integration.template-conflicts`  | validated (false when no integration manifest was found, so nothing was inspected), 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` | validated (false when no integration manifest was found, so nothing was inspected), 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. When the manifest loads and declares a components root, propDrift compares documented props with the TypeScript props: status (checked \| skipped), reason, typescript, components, typesCompared, typesSkipped, findings (all warnings; a default_mismatch carries docDefault, codeDefault, and a fix), unchecked, typesNotCompared, and propsNotChecked.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `integration.doc-conflicts`       | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`). copiedPassages lists each pair of topics that repeat 10 or more words of prose word for word: topic, section, otherTopic, otherOwner (package \| core), words, passages, owner (the topic that should keep the text), text (the passage as the topic writes it), line (where the copy starts in the topic to change, or null), and message (the exact replacement); each is also a copied_passage warning in issues. fluff lists padding phrases and low-density topics: topic, kind (phrase \| density), phrase, section, file (relative to the package root), line, density, and message (what to cut or write instead); each is also a doc_fluff warning in issues. strayPointers lists each code span that is exactly `astryx docs <name>` for a doc that exists, in the prose, description or summary of a topic or the text fields of a component doc: topic (the topic or component doc), kind (topic \| component), section, field (the field outside any section, such as description or usage.bestPractices[0].description, else null), file (relative to the package root), line, pointer (the written command), link (the {@link} that replaces it), and message; each is also a stray_doc_pointer warning in issues. |
+| `integration.check`               | Every source check of an integration package in one result: validated (false when no integration manifest was found, so nothing was checked), the package name and version, strict, and checks, one entry per check (validate, components, templates, docs), each with check, errors, warnings, skipped, failed, and response, the envelope that check returns on its own. The totals are errors, warnings, and skipped; unchecked counts what the checks could not compare. With --strict, failures lists each warning and each piece of skipped work again as an error, in the issue format the checks use; it is empty without --strict. failed decides the exit code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -551,12 +571,12 @@ data: { checks, summary } }`) that AI agents and scripts can parse.
 Omit `[package]` to inspect the package at the current directory, or pass an
 installed package name:
 
-| Command                                   | What it checks                                               | Exit `1` when                                           |
-| ----------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
-| `doctor integration validate [package]`   | Manifest shape and every declared contribution               | A structural issue has error severity                   |
-| `doctor integration templates [package]`  | Template IDs shared with Core                                | The integration is invalid; ID conflicts are warnings   |
-| `doctor integration components [package]` | Component names shared with Core                             | The integration is invalid; name conflicts are warnings |
-| `doctor integration docs [package]`       | Core topic replacements, extensions, and same-name conflicts | A Core overlap is accidental or the docs are invalid    |
+| Command                                   | What it checks                                                                      | Exit `1` when                                                                |
+| ----------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `doctor integration validate [package]`   | Manifest shape and every declared contribution                                      | A structural issue has error severity                                        |
+| `doctor integration templates [package]`  | Template IDs shared with Core                                                       | The integration is invalid; ID conflicts are warnings                        |
+| `doctor integration components [package]` | Component names shared with Core, and each props table against the TypeScript props | The integration is invalid; name conflicts and prop differences are warnings |
+| `doctor integration docs [package]`       | Core topic replacements, extensions, and same-name conflicts                        | A Core overlap is accidental or the docs are invalid                         |
 
 Template and component conflicts include the exact `--package` command needed
 to select the integration contribution. Doc replacements and extensions are
@@ -580,12 +600,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>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
+| 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>` | Custom components for the removed layout expander, keyed by component name. The CLI still validates the field, so an entry without a string `from` makes `astryx.config` invalid, but nothing reads it. |
 
 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`
@@ -652,13 +672,14 @@ export default {
 };
 ```
 
-| Field        | Type     | Purpose                                                                           |
-| ------------ | -------- | --------------------------------------------------------------------------------- |
-| `components` | `string` | Directory holding the package's components and their `.doc.*` files.              |
-| `templates`  | `string` | Directory holding the package's page/block templates.                             |
-| `codemods`   | `string` | Directory holding upgrade codemods run by `astryx upgrade`.                       |
-| `docs`       | `string` | Directory of reference docs; each `{topic}.doc.*` becomes a topic the CLI serves. |
-| `issuesUrl`  | `string` | Where "report an issue" links for this package's contributions point.             |
+| Field        | Type     | Purpose                                                                                                     |
+| ------------ | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `components` | `string` | Directory holding the package's components and their `.doc.*` files.                                        |
+| `templates`  | `string` | Directory holding the package's page/block templates.                                                       |
+| `codemods`   | `string` | Directory holding upgrade codemods run by `astryx upgrade`.                                                 |
+| `docs`       | `string` | Directory of reference docs; each `{topic}.doc.*` becomes a topic the CLI serves.                           |
+| `issuesUrl`  | `string` | Where "report an issue" links for this package's contributions point.                                       |
+| `cliCommand` | `string` | The command its users run the CLI with, such as `acme astryx`; every command the CLI prints starts with it. |
 
 Every field is optional; declare only the roots the package ships. There is no
 factory: write a plain object, and annotate it with the `AstryxIntegration` type