@astryxdesign/cli 0.6.4 → 0.6.5-canary.01972bc

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @xds/cli
 
+# 0.6.5
+
+#### New Features
+
+- `astryx component` accepts several exact selectors in one call. The JSON response keeps one ordered row per selector, including missing and ambiguous components, and text mode prints every row before exiting nonzero when any lookup fails. The `component()` API accepts selector arrays and always returns `component.batch` for an array, including empty and one-item arrays. Batches accept up to 100 selectors and reject larger arrays before lookup. The public API also exports shared `BatchResponse` and `BatchRow` types for typed receipts.
+- `astryx discover` browses integrations: the ones a project has and, through discover sources, the ones it could add, with every version and what each one adds. It searches every kind of item and filters with `--type`, `--installed`, `--available`, and `--limit`. A project sets a source as `discover` in `astryx.config`, and an integration exports one as a `discover` named export. Discover only reads: it prints the command that adds a package and never runs it. Existing `--json` fields keep their meaning. A free-text query now always lists its matches, even an exact component name, and `astryx discover <package>/<Name>` opens one.
+- `astryx integration verify` is the new name of `astryx integration pack --check`.
+  The check you run before publishing an integration now has a name that says what it does. `astryx integration verify` packs the package with npm, installs the tarball into a temporary app, and checks that the app sees the same components, templates, themes, docs, and codemods. It takes no flags. `astryx integration pack --check` still works as a deprecated alias: it runs the same check with the same output, JSON, and exit codes, prints a note that names `integration verify`, and shows as deprecated in help. It will be removed in a later release. The `integrationPackCheck()` API and its `integration.pack-check` JSON response do not change. With `--json`, a command group given an unknown subcommand now reports `ERR_UNKNOWN_SUBCOMMAND` and lists its subcommands, where it used to say JSON output is not supported.
+
+#### Fixes
+
+- Fix the CLI's topic docs and how they print.
+- `astryx doctor` no longer reports an integration it could not check as absent or complete (#6619)
+- `upgrade`'s `filesChanged` counts files, not (codemod, file) pairs (#6622)
+  One source file that four codemods each changed was reported as four files changed, so `filesChanged` matched `transformsApplied` and the documented meaning, "Total files changed", was not true. The human summary said the same thing: "Found 4 changes across 4 files" for one file.
+
+  `filesChanged` is now the count of distinct files. `transformsApplied` is unchanged: a code or config codemod counts once for each file it changed, and a project codemod counts once. A file that both a core codemod and an integration codemod changed counts once in `filesChanged`.
+- A parse error prints the Astryx error format in text mode.
+  `astryx theme list --lang zh-Hans` printed Commander's own line — `error: option '--lang <locale>' argument 'zh-Hans' is invalid…` — while every other CLI error prints `Error: …`. `--json` was already correct (`ERR_INVALID_LANG`), so the two modes agreed only on the exit code.
+
+  Commander writes that line before any Astryx code runs, so the JSON shim — the one place that already sees every parse failure — now suppresses it and writes the Astryx line itself, from the same message, for both modes. Every parse failure is covered: unknown option, unknown command, missing argument, and an invalid value for a global option. `--help` and `--version` are untouched and still exit 0.
+- The CLI reference now matches what the commands do. Every `--help` ends with the command's examples and a `More:` line that names its full docs page. Function docs show each parameter's default, mark required parameters, list the error codes each function throws, and use examples that run. The response-type list adds `help`, `version`, and `upgrade.registry`, and `astryx manifest` now lists `upgrade.registry` for `upgrade`. The `--zh`, `--dense`, `--lang`, and `--detail` descriptions name the commands they change, and command summaries say when to use each command. When `astryx template` refuses to overwrite a file, it now says to re-run with `--overwrite` (or `-f`). The `upgrade` command page (`astryx docs cli/commands/upgrade`) now explains which files codemods never edit, what happens when one of them needs a change, and how to regenerate it.
+- `astryx integration pack --check` now checks the tarball when a `prepack`, `prepare`, or `postpack` script prints to stdout. Before, any lifecycle output made the check fail with "npm pack produced unparseable JSON output" before it looked at the tarball. A failing lifecycle script still fails the check, and its output stays in the `pack_failed` message.
+- `astryx doctor integration docs` fails when a namespace doc or a placement fails, as its help says.
+  Such a failure hides the doc from the docs tree, so it now exits 1 with an `invalid_doc_graph` error instead of a warning. A link that names no doc still only warns, since it prints as written. `doctor integration docs` and `doctor integration components` also no longer print an `[ok]` line after a check that failed.
+
+  A mistyped subcommand under `doctor` now fails and lists the subcommands the group has: `astryx doctor integrations` used to run the project checks, and `astryx doctor integration bogus` exited 0 in text though it exited 1 with `--json`.
+- A package that ships a theme, or a doc section with an `id`, now declares the CLI that can read it.
+  A stable CLI before 0.7.0 rejects both: it cannot read the typed theme descriptors that `astryx integration add theme` writes, and it rejects a section `id`. Either way it hides the package's themes or doc topics with no warning. `astryx integration add theme` now adds `"@astryxdesign/cli": ">=0.7.0"` to `peerDependencies`, marked optional, and `astryx integration verify` fails with `themes_need_cli` or `section_ids_need_cli` when a package needs that peer range and does not declare it.
+- `astryx integration verify` resolves every public import in the packed package, not in your source folder.
+  Before, its temporary app resolved your package's own name through the source `package.json`, so an `exports` target left out of the tarball still passed. It now fails with `component_export_missing`, as an app that installs the tarball would.
+- `astryx theme add` and `astryx theme build` now undo a failed write completely. Before, when one file failed to write after others were written, the written files kept their new content. Now every replaced file gets its previous content back, every new file is removed, and the error names any file that could not be restored. Both commands also refuse to replace a destination that is a symbolic link. (#6852)
+
+#### Other Changes
+
+- A code block's label now prints above the block instead of as a `// label` line inside it, so copied bash, CSS, JSON, and HTML stay valid. Table cells escape `|`, so a union type stays in one column.
+- `astryx search dark mode` searches for both words; it used to drop every word after the first. A result that matches every word of a query, one of them by name or keyword, now outranks one that matches only some, and a section whose title or heading holds the whole query ranks near the top. Topics can declare search `keywords`, now a documented ReferenceDoc field, and a namespace's `keywords` now count too. A query keeps its phrase when common words such as `make`, `build`, or `an` drop out, so `astryx search make an integration` finds the integration guides, a plural of a doc's name matches it, one step below the exact name, and a component's name typed as words, such as `command palette`, finds the component. Outside an app, where `@astryxdesign/core` is not installed, `astryx search` searches the docs instead of failing, and says so; `--type component`, `hook`, or `template` still needs Core.
+- Snippets that failed when copied now work: StyleX token imports, the `fr-FR.json` locale path, Tailwind `rounded-lg`, `--color-background-muted`, icon and color values, and the Cursor rule path.
+- Claims that did not match the code are corrected: the 30 shipped locales and how RTL mirroring works, what `astryx init` writes, `--detail brief` for a shorter read, the Neutral and Matcha fonts, the components that need anchor positioning, `gap` steps, Card's radius, and the Next.js StyleX example. The deprecated bare classes are still emitted and will be removed in a later release.
+- `astryx docs tokens` lists all 258 tokens, adding the data visualization and syntax groups, and shows both halves of every `light-dark()` value.
+- Long sections are split, vague titles renamed, and the `--dense` and Chinese versions no longer drop blocks. Eleven long section keys are shorter, such as `astryx docs styling stylex-setup`, and every old key still resolves. An integration section that extends a Core topic by a section's old title still replaces that section.
+- `astryx integration add codemod --to` help says it takes the Core version whose upgrade runs the codemod.
+- The agent block that `astryx init` writes now says `upgrade --from <old version> --apply`; `upgrade --apply` alone stops with "Missing required --from".
+- The contributor-only sections, on adding a semantic icon and on strings and text direction inside components, moved to CONTRIBUTING.md.
+- An installed dependency whose `astryx.integration.*` manifest cannot be loaded is still kept out of the loaded set, but `implicit-integrations` now names it and says it contributes nothing. Before, doctor said that no installed dependency ships a manifest. The check stays informational, and `astryx doctor integration validate <package>` gives the details.
+- `implicit-integrations` lists only the roots that exist on disk. A package whose declared roots are missing is reported as contributing nothing, with the missing roots named. Before, it listed every root the manifest declared.
+- `provider-identity` says how many loaded integrations it could not read, instead of counting only the readable ones.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @josephfarina
+
+---
+
 # 0.6.4
 
 #### New Features

package/README.md

@@ -30,7 +30,8 @@ The CLI documents itself, so these commands print what the installed version doe
   `astryx.integration.*` manifest, codemods, and every doc type (`ComponentDoc`,
   `TemplateDoc`, `ThemeDoc`, and the rest). Read one section with
   `astryx docs authoring <section>`, for example `astryx docs authoring config`.
-- `astryx docs cli/integrations`: the guide to building an integration package.
+- `astryx docs cli/integrations`: the guides to building an integration package,
+  from a quick start to publishing.
 - `astryx docs`: every docs topic, including the design-system guides (for
   example `tokens`, `theme`, and `layout`).
 
@@ -77,37 +78,37 @@ Options:
 
 <!-- BEGIN GENERATED: commands -->
 
-| Command       | Description                                                                   |
-| ------------- | ----------------------------------------------------------------------------- |
-| `blog`        | Read the Astryx blog from the published feed                                  |
-| `build`       | Build a page: the template to start from, or the workflow playbook (no query) |
-| `component`   | List components or print component docs                                       |
-| `discover`    | Discover external packages and components                                     |
-| `docs`        | Print reference docs                                                          |
-| `doctor`      | Diagnose Astryx projects and integration packages                             |
-| `gap-report`  | Route a design-system gap to its owning package                               |
-| `hook`        | List hooks or print hook docs                                                 |
-| `init`        | Initialize the design system in your project                                  |
-| `integration` | Author and verify an Astryx integration package                               |
-| `layout`      | Generate XDS layouts from compressed expressions (XLE/XLO)                    |
-| `search`      | Search components, hooks, docs, and templates in one ranked list              |
-| `swizzle`     | Copy component source for customization                                       |
-| `template`    | Inject a page or block template                                               |
-| `theme`       | Theme tools: build, export, and manage themes                                 |
-| `upgrade`     | Migrate versions and update ShadCN-copied compositions                        |
+| Command       | Description                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `blog`        | Read the Astryx blog from the published feed                                                  |
+| `build`       | Build a page: the template to start from, or the workflow playbook (no query)                 |
+| `component`   | List components or print component docs                                                       |
+| `discover`    | Browse and search integrations: the ones you have and the ones you could add                  |
+| `docs`        | Print reference docs                                                                          |
+| `doctor`      | Diagnose Astryx projects and integration packages                                             |
+| `gap-report`  | Report a missing component or feature to the package that owns it                             |
+| `hook`        | List hooks or print hook docs                                                                 |
+| `init`        | Initialize the design system in your project                                                  |
+| `integration` | Author and verify an Astryx integration package                                               |
+| `layout`      | Generate XDS layouts from compressed expressions (XLE/XLO)                                    |
+| `search`      | Search components, hooks, docs, and templates in one ranked list                              |
+| `swizzle`     | Copy component source for customization                                                       |
+| `template`    | List, show, or scaffold page and block templates                                              |
+| `theme`       | Create and build themes: add a shipped one, compile to CSS, or list what a theme can override |
+| `upgrade`     | Update your code after upgrading Astryx, and refresh ShadCN-copied components                 |
 
 <!-- END GENERATED: commands -->
 <!-- Generated by scripts/generate-cli-readme.mjs from `astryx manifest`. Run `pnpm -F @astryxdesign/cli readme`. -->
 
 ### Global options
 
-These flags work with any command:
+`--json` works with every command listed in `jsonSupported` (`astryx manifest --json`), which is every command except the bare groups such as `astryx theme`. The other four change only the reads named here; other commands ignore them:
 
 - `--json`: Output as typed JSON envelope: `{ apiVersion, type, data, meta? }` (errors: `{ apiVersion, error, code, suggestions? }`)
-- `--detail <level>`: Detail level for list views, increasing in size: `brief` (names only, default for `--list`) < `compact` (names + 1-line descriptions) < `full` (full docs per entry). Single-item views default to `full`.
-- `--zh`: Output docs in Chinese Simplified
-- `--dense`: Compressed format (token-efficient, useful for AI agents)
-- `--lang <locale>`: Language/format shorthand (`en`, `zh`, `dense`)
+- `--detail <level>`: Detail level for `component`, `hook`, and docs tree reads (such as `astryx docs cli/commands/build`), increasing in size: `brief` (names only, default for lists) < `compact` (names + 1-line descriptions) < `full` (full docs per entry). Single-item views default to `full`.
+- `--zh`: Simplified Chinese for component reads and for docs topics that have a translation (English otherwise)
+- `--dense`: Token-efficient dense text for `astryx component <Name>` and `astryx docs <topic>`
+- `--lang <locale>`: Language or format for component and docs reads: `en` (default), `zh` (as `--zh`), or `dense` (as `--dense`)
 
 ## JSON API
 
@@ -164,9 +165,9 @@ if (isError(result)) {
 | `ERR_UNKNOWN`                     | Fallback for any error without a more specific code.                                                                                                     |
 | `ERR_UNKNOWN_COMMAND`             | A top-level command name was not recognized (e.g. `astryx bogus`).                                                                                       |
 | `ERR_UNKNOWN_SUBCOMMAND`          | A subcommand under a command group was not recognized (e.g. `astryx theme bogus`).                                                                       |
-| `ERR_INVALID_OPTION`              | An unknown flag/option was passed (Commander `unknownOption`).                                                                                           |
-| `ERR_INVALID_ARGUMENT`            | An option/argument had a value Commander's parser rejected.                                                                                              |
-| `ERR_MISSING_ARGUMENT`            | A required positional argument was omitted (Commander `missingArgument`).                                                                                |
+| `ERR_INVALID_OPTION`              | An unknown option was passed, --json was given to a command without JSON output, or layout --form got a value other than compact, outline, or auto.      |
+| `ERR_INVALID_ARGUMENT`            | An argument or option value is invalid: wrong type, out of range, an unknown choice, an extra argument, or a conflicting combination.                    |
+| `ERR_MISSING_ARGUMENT`            | A required argument or option value was omitted.                                                                                                         |
 | `ERR_INVALID_LANG`                | `--lang` was given a value outside its choices (en, zh, dense).                                                                                          |
 | `ERR_INVALID_DETAIL`              | `--detail` was given a value outside its choices (full, compact, brief).                                                                                 |
 | `ERR_NODE_VERSION`                | The running Node.js version is below the supported minimum.                                                                                              |
@@ -184,8 +185,8 @@ if (isError(result)) {
 | `ERR_UNKNOWN_THEME`               | No theme matched the requested slug (theme add).                                                                                                         |
 | `ERR_INTEGRATION_ROOT_CONFLICT`   | An integration manifest already declares a different path for the requested contribution root.                                                           |
 | `ERR_INTEGRATION_EXPORT_CONFLICT` | A package export already maps a generated contribution subpath to a different target.                                                                    |
-| `ERR_UNKNOWN_PACKAGE`             | No package matched the requested name (discover).                                                                                                        |
-| `ERR_UNKNOWN_AGENT`               | An unrecognized `--agent` value was passed to agent-docs/init.                                                                                           |
+| `ERR_UNKNOWN_PACKAGE`             | No package matched the requested name.                                                                                                                   |
+| `ERR_UNKNOWN_AGENT`               | An unrecognized `--agent` value was passed to init.                                                                                                      |
 | `ERR_UNKNOWN_FEATURE`             | An unrecognized `--features` value was passed to init.                                                                                                   |
 | `ERR_UNKNOWN_CODEMOD`             | A `--codemod` value did not match any registered codemod (upgrade).                                                                                      |
 | `ERR_CODEMOD_FAILED`              | One or more codemods failed during an upgrade run.                                                                                                       |
@@ -211,7 +212,7 @@ if (isError(result)) {
 | `ERR_FETCH_FAILED`                | A network fetch (RSS feed or post text) failed.                                                                                                          |
 | `ERR_LAYOUT_PARSE`                | A layout expression failed to parse (syntax error, with line/col).                                                                                       |
 | `ERR_LAYOUT_INVALID`              | A layout expression parsed but failed validation (unknown component/prop/enum/block).                                                                    |
-| `ERR_UNCLASSIFIED_EXIT`           | Recorded in the debug log, never printed: a command exited non-zero without going through cliError/jsonError, so no stable code was available.           |
+| `ERR_UNCLASSIFIED_EXIT`           | Recorded in the debug log, never printed: a command exited non-zero without reporting an error code.                                                     |
 | `ERR_SIGNAL_TERMINATED`           | Recorded in the debug log, never printed: the process was ended by a signal (Ctrl-C, SIGTERM) before the command reached a terminal path.                |
 
 <!-- END GENERATED: error-codes -->
@@ -302,11 +303,12 @@ Shape:
 ```
 
 The manifest is **derived from Commander metadata** (commands, arguments, options)
-so it can't drift from the real command definitions. The two facts Commander
-doesn't track (`--json` support and emitted response types) are layered on from
-the `JSON_SUPPORTED` allowlist and a small declarative `RESPONSE_TYPES` map in
-`src/lib/manifest.mjs`, guarded by a drift test (`manifest.test.mjs`) so adding a
-command without describing it fails CI.
+so it can't drift from the real command definitions. The facts Commander doesn't
+track come from each command's docs: examples from its CommandDoc, and emitted
+response types from the returns of the FunctionDoc it wraps (plus the few
+envelopes the CLI layer builds itself). `--json` support comes from the
+`JSON_SUPPORTED` allowlist. Drift tests (`manifest.test.mjs`) fail CI when a
+command is added without describing it.
 
 **Backwards-compat:** the bare `astryx --json` envelope keeps `type: "help"` and its
 original shallow fields (`name`, `version`, `commands` as a `string[]` of names,
@@ -418,64 +420,69 @@ Every response has a `type` discriminant. The full set is below (generated from
 
 <!-- BEGIN GENERATED: response-types -->
 
-| Type                              | What `data` carries                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `init.run`                        | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted.                                                                                                                                                        |
-| `init.remove`                     | Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set.                                                                                                                                                                                                                                                                                                                  |
-| `component.list`                  | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.                                                                                                                                                                           |
-| `component.detail`                | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc).                                                                                                                                                                                  |
-| `component.detail.props`          | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                                                                                                                                                                                                                                     |
-| `component.detail.source`         | One component's source file, as {component, source}.                                                                                                                                                                                                                                                                                                                                                                                       |
-| `component.detail.showcase`       | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                                                                                                                                                                                                                     |
-| `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                                                                                                                                                                                                                 |
-| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load.                                                                                                                                                                                                                |
-| `docs.detail`                     | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                                                                                                                                             |
-| `docs.index`                      | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                  |
-| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it).                                                                                                                                                                                                                                     |
-| `docs.node`                       | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names).                                                                                                                           |
-| `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                                                                                                                                                                   |
-| `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                                                                                                                                                                  |
-| `discover.list`                   | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                                                                                                                                                                         |
-| `discover.detail`                 | A single external package entry, for an @scope/name query.                                                                                                                                                                                                                                                                                                                                                                                 |
-| `discover.detail.doc`             | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                                                                                                                                                                                                                             |
-| `discover.search`                 | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                                                                                                                                                                                                                           |
-| `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates).                                        |
-| `build.help`                      | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.                                                                                                                                                              |
-| `build.kit`                       | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, command, basis, reason, alternatives, ...}, pages (search's closest templates), blocks and domain as SearchResultEntry[], frame, foundation, and hint {reason, commands} when thin.                                                                                                                                         |
-| `swizzle.list`                    | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                                                                                                                                                                                                                             |
-| `swizzle.copy`                    | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                                                                                                                                                                                                                             |
-| `gap-report.categories`           | The fixed gap category values and human-readable labels.                                                                                                                                                                                                                                                                                                                                                                                   |
-| `gap-report.file`                 | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.                                                                                                                                                                                      |
-| `template.list`                   | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list.                                                                                                                                                                                                                                                             |
-| `template.show`                   | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                                                                                                                                                                                                        |
-| `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                                                                                                                                                                                                               |
-| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                                                                                                                                                                                                                      |
-| `template.cdn`                    | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                                                                                                                                                         |
-| `hook.list`                       | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                                                                                                                                                                                                                          |
-| `hook.detail`                     | One hook's full authored HookDoc.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `hook.detail.params`              | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                                                                                                                                                                                                                         |
-| `theme.build`                     | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load).                                                                                                                                                               |
-| `theme.build.check`               | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                                                                                                                                                                                                                       |
-| `theme.build.batch`               | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS.                                                                                                                                                                                                                          |
-| `theme.list`                      | Every bundled or installed integration theme as a ThemeListEntry[]: each with slug, displayName, description, maintained flag, and owner package.                                                                                                                                                                                                                                                                                          |
-| `theme.add`                       | A scaffold receipt: resolved slug, displayName, maintained flag, owner package, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                                                                                                                                                                                                                  |
-| `theme.template`                  | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                                                                                                                                                                                                               |
-| `theme.targets`                   | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key.                                                                                                                                                                |
-| `theme.palette.generate`          | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result.                                                                                                                                                                                                                                                                                               |
-| `upgrade.list`                    | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                                                                                                                                                                                                                                 |
-| `upgrade.status`                  | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                                                                                                                                                                                                                           |
-| `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                                                                                                                                                                                                                |
-| `manifest`                        | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.                                                                                                                                                         |
-| `doctor`                          | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                                                                                                                                                                                                                                |
-| `integration.add`                 | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun.                                                                                                                                                                                                                                                                            |
-| `integration.pack-check`          | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}]. |
-| `integration.validate`            | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                   |
-| `integration.template-conflicts`  | The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                  |
-| `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                             |
-| `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                     |
-| `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).                                                                                                                                                                                                       |
-| `layout.check`                    | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                                                                                                                                                                                                                   |
-| `layout.grammar`                  | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                                                                                                                                                                                                        |
+| Type                              | What `data` carries                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init.run`                        | The install receipt: the `mode` (`default` \| `features`), the features run, agent-doc files written, any soft `docsError`, whether theme guidance was emitted, the template outcome (`workflow` \| `created` \| `skipped`) plus its path, and whether the next-steps were emitted.                                                                                                                                                                                                                                                                                                                                   |
+| `init.remove`                     | Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when --remove-agents is set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `component.list`                  | The component catalog grouped by component group (each component's group field): `detail` (the level: names \| compact \| full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.                                                                                                                                                                                                                                                                                                                |
+| `component.batch`                 | The component specialization of the shared `BatchResponse` and `BatchRow` types. An explicit programmatic selector array, or two or more CLI selectors, returns one ordered receipt: `count` plus `results`, one row per selector including duplicates. Every row carries `selector` and `status` (found \| not_found \| ambiguous \| error). A found row carries `result`, the same {type, data} response as one selector. An ambiguous row carries `code`, `error`, and `candidates` ({package, component, kind, installed}). Other failed rows carry `code`, `error`, and optional `suggestions` ({name, reason}). |
+| `component.detail`                | One component's authored ComponentDoc plus ownership fields (package, the owner; import, the specifier; sourceAvailable, whether source exists) and parentDoc (present when the component is documented inside another component's doc, naming that doc).                                                                                                                                                                                                                                                                                                                                                             |
+| `component.detail.props`          | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `component.detail.source`         | One component's source file, as {component, source}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `component.detail.showcase`       | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load.                                                                                                                                                                                                                                                                                                                                                                                           |
+| `docs.detail`                     | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                                                                                                                                                                                                                                                                                                                        |
+| `docs.index`                      | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                                                                                                                                                                                             |
+| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it).                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `docs.node`                       | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names).                                                                                                                                                                                                                                                                                                      |
+| `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `discover.list`                   | The integrations the project loads (name, category, components, version, a list per other kind they add, and latest when a source knows it); with a discover source, meta.available lists what the project could add and meta.sources reports each source; when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                                                                                                                                                                              |
+| `discover.detail`                 | One package, for an @scope/name or @scope/name@version query: what the shown version adds, whether the project has it, and, when a source knows the package, its versions, latest release, and the command that adds it.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `discover.detail.doc`             | The validated ComponentDoc for one installed component, for an @scope/name/Component query.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `discover.item`                   | One item that is not an installed component, for an @scope/name/<item> query: its kind, name, package, version, and whether the project has the package.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `discover.search`                 | The echoed query plus every matching item and package across all packages, each with its kind and whether the project has it, even when only one matches; total is set when --limit cut the list.                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates).                                                                                                                                                                                                                   |
+| `build.help`                      | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.                                                                                                                                                                                                                                                                                                                                         |
+| `build.kit`                       | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, command, basis, reason, alternatives, ...}, pages (search's closest templates), blocks and domain as SearchResultEntry[], frame, foundation, and hint {reason, commands} when thin.                                                                                                                                                                                                                                                                                                                    |
+| `swizzle.list`                    | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `swizzle.copy`                    | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.                                                                                                                                                                                                                                                                                                                                               |
+| `gap-report.categories`           | The fixed gap category values and human-readable labels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `gap-report.file`                 | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.                                                                                                                                                                                                                                                                                                                                                                 |
+| `template.list`                   | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `template.show`                   | The resolved template's 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, file count, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `template.cdn`                    | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                                                                                                                                                                                                                                                                                                                                    |
+| `hook.list`                       | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `hook.detail`                     | One hook's full authored HookDoc.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `hook.detail.params`              | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `theme.build`                     | A theme build receipt: name, tokenCount and componentCount (override counts), sizeKB, the written outputs {css, js, dts, and variantsDts when applicable}, warnings (defects to fix), and notices (advisories about a correct theme, such as a named font it does not load).                                                                                                                                                                                                                                                                                                                                          |
+| `theme.build.check`               | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `theme.build.batch`               | Several themes built in one invocation: `count` plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS.                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `theme.list`                      | Every bundled or installed integration theme as a ThemeListEntry[]: each with slug, displayName, description, maintained flag, and owner package.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `theme.add`                       | A scaffold receipt: resolved slug, displayName, maintained flag, owner package, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `theme.template`                  | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `theme.targets`                   | The whole themeable surface: the echoed filter, componentCount, and targets, one per theming target — {key, className, component, props, states, deprecatedFor?}, where props and states are its legal override keys and deprecatedFor names the canonical replacement key.                                                                                                                                                                                                                                                                                                                                           |
+| `theme.palette.generate`          | An author-reviewable OKLCH palette candidate, its reproducibility receipt, summary counts, and optional candidate/receipt file-write result.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `upgrade.list`                    | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `upgrade.registry`                | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.                                                                                                                                                                                                                                                                                                                                                                                            |
+| `upgrade.status`                  | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, 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 no integration manifest was found, so nothing was checked and the empty issues list 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`).                                                                                                                                                                                                                                                                                                                                            |
+| `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, written (the output path, or null when nothing was written), and demoMediaReplaced (count of demo media placeholders).                                                                                                                                                                                                                                                                                                                            |
+| `layout.check`                    | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                                                                                                                                                                                                                                                                                                                                                                                              |
+| `layout.grammar`                  | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 
 <!-- END GENERATED: response-types -->
 <!-- Generated by scripts/generate-cli-readme.mjs from the response-types EnumDoc. Run `pnpm -F @astryxdesign/cli readme`. -->
@@ -677,9 +684,10 @@ Warnings go to stderr and never corrupt a `--json` envelope. To inspect problems
 Core identity overlaps before publishing. Bare `astryx doctor` checks overall
 project health.
 
-For the full authoring walkthrough (component doc format, template packaging
-and `exports` requirements, and codemod authoring), see the guide:
+For the full walkthrough, from an empty folder to a published package, see the
+guides:
 
 ```bash
 astryx docs cli/integrations
+astryx docs cli/integrations/quick-start
 ```

package/api/build/_adapter.d.mts

@@ -7,8 +7,15 @@
  * @property {string} name The template's own id, as search reports it.
  * @property {string} command `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
  * @property {string} displayName Human-facing name.
- * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} description What the page is and how it is laid out.
  * @property {string} category The template's own `Family - Variant` label; empty when it declares none.
+ * @property {string[]} keywords The ideas the page serves, as its own descriptor names them; empty when it declares none.
+ */
+/**
+ * A component the project can use, as the ranker reads it.
+ * @typedef {object} ComponentWords
+ * @property {string} name The component's name, e.g. `DateRangeInput`.
+ * @property {string[]} keywords The keywords its own doc declares.
  */
 /**
  * Every ready page template the project can scaffold, in discovery order. This
@@ -23,6 +30,16 @@
  * @returns {Promise<PageTemplate[]>}
  */
 export function loadPageTemplates(cwd: string): Promise<PageTemplate[]>;
+/**
+ * The components the project can use, Core's and its integrations', each with
+ * the keywords its own doc declares: what the ranker reads to tell a part of a
+ * page from a page. Search's own discovery, so both agree on what exists; empty
+ * when Core cannot be found.
+ *
+ * @param {string} cwd
+ * @returns {Promise<ComponentWords[]>}
+ */
+export function loadComponents(cwd: string): Promise<ComponentWords[]>;
 /**
  * A page template the kit can recommend starting from.
  */
@@ -40,11 +57,28 @@ export type PageTemplate = {
      */
     displayName: string;
     /**
-     * What the page is: its layout and the ideas it serves.
+     * What the page is and how it is laid out.
      */
     description: string;
     /**
      * The template's own `Family - Variant` label; empty when it declares none.
      */
     category: string;
+    /**
+     * The ideas the page serves, as its own descriptor names them; empty when it declares none.
+     */
+    keywords: string[];
+};
+/**
+ * A component the project can use, as the ranker reads it.
+ */
+export type ComponentWords = {
+    /**
+     * The component's name, e.g. `DateRangeInput`.
+     */
+    name: string;
+    /**
+     * The keywords its own doc declares.
+     */
+    keywords: string[];
 };