@astryx-vue/cli 0.3.0 → 0.4.0

package/README.md

@@ -53,9 +53,14 @@ npm run astryx-vue -- component Button
 | `astryx-vue composable <Name>` | Parameters, return values, usage, and examples for one composable |
 | `astryx-vue docs` | Every guide and theme topic |
 | `astryx-vue docs <topic>` | One topic's page text, such as `docs guide/dark-mode` or `docs themes/tokens` |
+| `astryx-vue docs <topic> --depth <n>` | The same page, cut off below heading level `n` |
 | `astryx-vue search <query>` | Ranked components, composables, docs topics, and templates |
 | `astryx-vue manifest --json` | Commands, options, response types, error codes, and exit codes |
-| `astryx-vue init --features agents` | Creates or refreshes the managed block in an agent file |
+| `astryx-vue theme` | Every built-in theme, one line each |
+| `astryx-vue theme <name>` | How to load one theme: stylesheet, `data-astryx-theme`, switching and scoping, verification |
+| `astryx-vue upgrade` | What upgrading the project's `@astryx-vue/core` takes, and where old names still appear |
+| `astryx-vue doctor` | Checks versions, the theme stylesheet, and the theme attribute. Reports only |
+| `astryx-vue init` | The setup guide for an AI assistant, plus the managed block in an agent file |
 
 Global flags:
 
@@ -64,17 +69,47 @@ Global flags:
 | `--json` | Typed envelope `{ apiVersion, type, data }` on stdout. Errors use `{ apiVersion, error, code, suggestions? }` and a non-zero exit code. |
 | `--dense` | Shorter text. Ignored with `--json`, which stays the full envelope. |
 | `--zh` | Simplified Chinese where the docs have a translation. |
-| `--cwd <dir>` | Project directory. Defaults to the working directory; `template` and `init` write inside it. |
+| `--cwd <dir>` | Project directory. Defaults to the working directory; `template` and `init` write inside it, and `upgrade`/`doctor` read it. |
 
-A composable takes `useClipboard` or `use-clipboard`. `component useClipboard` still prints it, and adds a line that points at the `composable` command. `component --list` lists components only. `search --type` accepts `component`, `composable`, `doc`, or `template`; composable hits carry `domain: "composable"` and a `command` that points at `composable <Name>`. A query that hits a name outranks one that only hits page text.
+A composable takes `useClipboard` or `use-clipboard`. `component useClipboard` still prints it, and adds a line that points at the `composable` command. `component --list` lists components only. `search --type` accepts `component`, `composable`, `doc`, or `template`; composable hits carry `domain: "composable"` and a `command` that points at `composable <Name>`. A query that hits a name outranks one that only hits page text. Each result names the package it comes from, ranked by score and then, when scores tie, by domain (component, composable, doc, template) and name, so the order never moves between runs.
 
-`docs` takes a topic id, the same id with `themes/` instead of `theme/`, or a bare name that matches one topic, such as `dark-mode`. `--json` returns `docs.list` or `docs.detail`, and `docs.detail` includes the page `body`.
+`docs` takes a topic id, the same id with `themes/` instead of `theme/`, or a bare name that matches one topic, such as `dark-mode`. `--json` returns `docs.list` or `docs.detail`, and `docs.detail` includes the page `body`. `--depth 2` keeps `#` and `##` and drops every deeper heading with the body under it, which is how a long page stays readable; `headings` in the JSON lists only the headings that survived, and `depth` says what was asked for.
+
+## Themes
+
+`theme` lists the seven shipped themes with their own one-sentence summaries. `theme <name>` prints the four steps that load one: the stylesheet import, the `data-astryx-theme` attribute, how switching or running two side by side works, and how to verify. The steps come from the theme's own docs page and the themes index page; the command writes nothing.
+
+A theme slug or its display name both resolve, so `theme butter` and `theme Butter` are the same request. `--json` returns `theme.list` or `theme.detail`, and `theme.detail` carries the whole docs page as `body` for an agent that wants the long version.
+
+## Upgrading
+
+`upgrade` reads the `@astryx-vue/core` version from the project's `package.json` and compares it with the version this CLI was generated from. It never asks the network.
+
+- Older: it prints every section of the upgrade guide — what changed, how it was written before, how it is written now, what to do — then looks through the project's own sources for the old names the guide replaces, and lists file and line. A theme target name only counts as an object key (`progressbar: {`), because the same word is also an HTML tag; a property or option name counts as a word, in camelCase or kebab-case.
+- Current: it says nothing needs doing and prints the changelog link.
+- Not installed, or a range it cannot read as a version: it says that, and either names the install command for the project's package manager or prints every form.
+
+Both lists come from `apps/docs/docs/{en,zh}/guide/migration.md`: the sections are the page's `###` sections, and the old names are the names its section titles and its `Removed | Use instead` table state.
+
+## Doctor
+
+`doctor` reports five checks and changes nothing:
+
+| Check | Fails or warns when |
+| --- | --- |
+| `core-version` | `@astryx-vue/core` is missing (fail), its range cannot be read as a version, or it is older or newer than this CLI's catalog (warn) |
+| `themes-installed` | `@astryx-vue/themes` is not a dependency (fail) |
+| `vue-version` | `vue` is missing (fail) or below 3.5.0 (warn) |
+| `theme-stylesheet` | No `@astryx-vue/themes/*.css` import is found (fail), or the file name is not one of the built-in themes (warn) |
+| `theme-attribute` | No `data-astryx-theme` is found (warn; Neutral works without it) |
+
+Exit code is `0` when every check passed or only warned, and `1` when one failed; the text still prints, and `--json` returns `doctor.report`. Sources are read from the project directory, skipping `node_modules`, build output, and hidden directories.
 
 ## Templates
 
-`template --list` prints all 53 playground pages. `--type page` is the only kind today; `--type block` answers with a note instead of an error.
+`template --list` prints all 57 playground pages. `--type page` is the only kind today; `--type block` answers with a note instead of an error.
 
-Every template carries a hand-written one-sentence description and a keyword list in English and Chinese, in `src/generate/template-meta.ts`. The component list is extracted from the page's `@astryx-vue/core` imports, so it cannot drift from the source.
+Every template carries a hand-written one-sentence description and a keyword list in English and Chinese, in `src/generate/template-meta/` (one file per template category). The component list is extracted from the page's `@astryx-vue/core` imports, so it cannot drift from the source. Each record also carries `dependencies`, the npm packages the page imports; a ready page names only `vue` and `@astryx-vue/core`, and the catalog generator fails when a ready page pulls in anything else. That is why `template --list`, `template <slug>`, and their `--json` forms can say exactly what a copied page needs.
 
 Some pages import a package a project cannot install: five use `@astryx-vue/playground-charts`, a path alias that only exists inside the docs playground. Those are marked `isReady: false` with the reason. A page is ready when every non-relative import it really performs is `vue` or `@astryx-vue/core`; text inside a code sample the page displays, such as `@astryxdesign/core`, is page content and does not count. `--list` and `template <slug>` still show them; copying is refused with `ERR_TEMPLATE_NOT_READY`.
 
@@ -100,7 +135,7 @@ Copying rewrites the playground's `/template-assets/…` photo paths to an inlin
 
 ## JSON envelopes
 
-Success responses are `{ apiVersion: 1, type, data }`. Template and build responses also carry `package: "@astryx-vue/cli"`.
+Success responses are `{ apiVersion: 1, type, data }`. `template`, `build`, and `docs` responses carry `package` for where the records come from (`@astryx-vue/cli` for templates, `@astryx-vue/docs` for pages). Every template entry of `template.list`, `template.show`, and `template.skeleton` carries its own `dependencies` array next to `components`. `component.detail` and `composable.detail` carry the owning package, and every entry of `component.list` and `composable.list` carries its own, because one list can span packages.
 
 | Type | Command |
 | --- | --- |
@@ -111,6 +146,9 @@ Success responses are `{ apiVersion: 1, type, data }`. Template and build respon
 | `docs.list`, `docs.detail` | `docs` |
 | `search` | `search` |
 | `manifest` | `manifest` |
+| `theme.list`, `theme.detail` | `theme` |
+| `upgrade.report` | `upgrade` |
+| `doctor.report` | `doctor` |
 | `init.run` | `init` |
 | `help`, `version` | `--help`, `--version`, or no arguments with `--json` |
 
@@ -126,12 +164,13 @@ Exit codes are `0` for success, `1` when the command ran but failed, and `2` for
 | `ERR_UNKNOWN_COMPONENT`, `ERR_UNKNOWN_COMPOSABLE`, `ERR_UNKNOWN_TOPIC` | No record matches the name. |
 | `ERR_UNKNOWN_AGENT` | `--agent` is not `cursor`, `claude`, `codex`, `hermes`, or `all`. |
 | `ERR_UNKNOWN_FEATURE` | `--features` names something other than `agents`. |
+| `ERR_UNKNOWN_THEME` | No theme has that slug or display name. |
 
 `manifest --json` carries the same list per command, so an agent can read the codes without this table.
 
 ## Agent block
 
-`init --features agents` writes this managed block:
+`init` prints the setup guide — which packages to install (canary ones with `@canary`, once they are on npm), the theme import, the locale snippet, and what to verify — and writes this managed block:
 
 ```html
 <!-- Maintained by astryx-vue, do not edit manually -->
@@ -141,7 +180,9 @@ Exit codes are `0` for success, `1` when the command ran but failed, and `2` for
 
 If the file is missing, the command creates it. If the markers are already there, every run replaces only the block with freshly generated text. Other text stays. If the file exists without the markers, the block is appended. A second run still rewrites the block; it does not skip because the markers are already present. When the generated text matches, the bytes stay the same.
 
-The block teaches the three-step workflow (`build` to pick a page, `template` to copy it, `component`/`composable`/`docs` before writing code), lists the lookup commands, and says how to run the binary. It does not paste the component catalog.
+The block names every package the catalog covers. A package npm does not serve yet (a `private` one) is still named, but with a note and no install command, so nobody is sent to a 404; a published canary package would get the `@canary` specifier. Then it teaches the three-step workflow (`build` to pick a page, `template` to copy it, `component`/`composable`/`docs` before writing code), lists the lookup commands, and says how to run the binary. It does not paste the component catalog.
+
+The install command in the guide follows the project: the `packageManager` field first, then `pnpm-lock.yaml`, `yarn.lock`, `bun.lock(b)`, or `package-lock.json`. With neither, all four forms are listed. `--features` is optional now; passing `agents` is the same as leaving it out, and any other feature is `ERR_UNKNOWN_FEATURE`.
 
 Where it writes:
 
@@ -160,11 +201,12 @@ The CLI does not keep a second copy of the component docs. `packages/cli/scripts
 - `apps/docs/docs/{en,zh}/components/<slug>/` for usage, props, slots, events, and example titles
 - `apps/docs/components/demos/<slug>/*.vue` for the example source those pages point at
 - `apps/docs/components/demo-infra/reference/*.json` for anatomy and accessibility
-- `apps/docs/docs/{en,zh}/guide` and `themes` for search topics and topic bodies
+- `apps/docs/docs/{en,zh}/guide` and `themes` for search topics, topic bodies, and the theme records (`theme`), plus the install commands and snippets `init` prints
+- `apps/docs/docs/{en,zh}/guide/migration.md` for the upgrade guide's sections and the old names `upgrade` searches for
 - `apps/docs/components/playground/pages/*.vue` for the template sources, and `templateManifest.ts` for their titles and categories
-- `packages/core/package.json` exports when a page does not show an import
+- every `packages/*/package.json` for which package owns a component, and its exports when a page does not show an import
 
-The template descriptions and keywords are hand-written in `packages/cli/src/generate/template-meta.ts`. They are source data, not a generated file.
+The template descriptions and keywords are hand-written in `packages/cli/src/generate/template-meta/`, one file per template category, and merged by `template-meta.ts`. They are source data, not a generated file.
 
 Example titles and descriptions are kept once per language, but the example code is stored once for both: both pages point at the same `.vue` file. The generator stops with an error naming the component and the example number if the two pages ever show different code, so one language cannot silently borrow the other's snippet. `examplesFor()` in `packages/cli/src/catalog.ts` is the only place that picks a language back out.
 
@@ -174,9 +216,11 @@ The result is committed at `packages/cli/src/generated/catalog.json`. `pnpm --fi
 pnpm --filter @astryx-vue/cli generate
 ```
 
-`pnpm check` runs `generate:check`. That fails when `catalog.json` is stale, when a PascalCase `@astryx-vue/core` export is not imported by any documented component, and when a playground page has no metadata in `template-meta.ts`. `./icons`, `./locale`, CSS, and the package root are not component exports.
+`pnpm check` runs `generate:check`. That fails when `catalog.json` is stale, when a PascalCase export of any package is not imported by a documented component, and when a playground page has no metadata in `template-meta.ts`. `./icons`, `./locale`, CSS, and the package root are not component exports.
+
+`catalog.packages` lists every package the catalog covers (`core`, `themes`, `richtext`, `charts`, `lab`) with its directory, whether it publishes only under the `canary` tag, and whether it is `published`. `published` is false for a `private` package: npm has no version of it, so no output prints an install command for it. A component's `package` is the one that exports it by subpath, else the one that has a source entry for it.
 
-Theme, upgrade, doctor, swizzle, and MCP commands are not part of this package.
+`swizzle`, `discover`, `gap-report`, `integration`, and `blog` are not part of this package, and there is no MCP server. `theme`, `upgrade`, and `doctor` print guidance and reports; none of them edits a project file.
 
 ## Related packages
 

package/README.zh-CN.md

@@ -53,9 +53,14 @@ npm run astryx-vue -- component Button
 | `astryx-vue composable <Name>` | 一个组合式函数的参数、返回值、用法和示例 |
 | `astryx-vue docs` | 全部指南和主题 |
 | `astryx-vue docs <topic>` | 一篇正文，例如 `docs guide/dark-mode` 或 `docs themes/tokens` |
+| `astryx-vue docs <topic> --depth <n>` | 同一篇正文，只留到第 n 层标题 |
 | `astryx-vue search <query>` | 排好序的组件、组合式函数、文档主题和模板 |
 | `astryx-vue manifest --json` | 命令、选项、响应类型、错误码和退出码 |
-| `astryx-vue init --features agents` | 创建或刷新 agent 文件里的受管理区块 |
+| `astryx-vue theme` | 全部内置主题，一行一个 |
+| `astryx-vue theme <名字>` | 一套主题的接入四步：样式、`data-astryx-theme`、切换与局部使用、验证 |
+| `astryx-vue upgrade` | 把项目里的 `@astryx-vue/core` 升上来要做什么，以及旧名字还出现在哪 |
+| `astryx-vue doctor` | 检查版本、主题样式有没有引、主题有没有设。只报告 |
+| `astryx-vue init` | 给 AI 助手的接入说明，外加 agent 文件里的受管理区块 |
 
 全局选项：
 
@@ -64,17 +69,47 @@ npm run astryx-vue -- component Button
 | `--json` | 在 stdout 输出类型化信封 `{ apiVersion, type, data }`。出错时是 `{ apiVersion, error, code, suggestions? }`，退出码非 0。 |
 | `--dense` | 缩短给人看的文本。和 `--json` 一起时忽略，信封始终完整。 |
 | `--zh` | 文档有中文版时用简体中文。 |
-| `--cwd <dir>` | 项目目录，默认当前工作目录；`template` 和 `init` 只往这里面写。 |
+| `--cwd <dir>` | 项目目录，默认当前工作目录；`template` 和 `init` 只往这里面写，`upgrade` 和 `doctor` 只在这里读。 |
 
-组合式函数可写 `useClipboard` 或 `use-clipboard`。`component useClipboard` 也能查到，并多印一行指向 `composable` 命令。`component --list` 只列组件。`search --type` 接受 `component`、`composable`、`doc`、`template`；组合式函数命中的结果是 `domain: "composable"`，`command` 指向 `composable <Name>`。命中名字的结果排在只命中正文的结果前面。
+组合式函数可写 `useClipboard` 或 `use-clipboard`。`component useClipboard` 也能查到，并多印一行指向 `composable` 命令。`component --list` 只列组件。`search --type` 接受 `component`、`composable`、`doc`、`template`；组合式函数命中的结果是 `domain: "composable"`，`command` 指向 `composable <Name>`。命中名字的结果排在只命中正文的结果前面。每条结果都标出来自哪个包；分数相同时按领域（组件、组合式函数、文档、模板）再按名字排序，跑两次顺序不会变。
 
-`docs` 接受主题 id、把 `theme/` 换成 `themes/` 的写法，或能唯一匹配某个主题的裸名，例如 `dark-mode`。`--json` 返回 `docs.list` 或 `docs.detail`，`docs.detail` 里有整页 `body`。
+`docs` 接受主题 id、把 `theme/` 换成 `themes/` 的写法，或能唯一匹配某个主题的裸名，例如 `dark-mode`。`--json` 返回 `docs.list` 或 `docs.detail`，`docs.detail` 里有整页 `body`。`--depth 2` 只留 `#` 和 `##`，更深的标题连同它下面的正文一起省掉，长页面因此读得下去；JSON 里的 `headings` 只列还在正文里的标题，`depth` 说明调用方要的是第几层。
+
+## 主题
+
+`theme` 列出内置的 7 套主题，每套带文档页自己的那句说明。`theme <名字>` 输出接入四步：引哪个样式表、`data-astryx-theme` 写什么、怎么换主题或同时用两套、改完怎么验证。这些文字来自主题自己的文档页和主题索引页，命令不写任何文件。
+
+slug 和显示名都能用，`theme butter` 和 `theme Butter` 是同一个请求。`--json` 返回 `theme.list` 或 `theme.detail`，`theme.detail` 里带整页 `body`，供想要长文的助手读。
+
+## 升级
+
+`upgrade` 读项目 `package.json` 里 `@astryx-vue/core` 的版本，和这个 CLI 生成时对应的版本比，不联网。
+
+- 比 CLI 旧：打印升级指南的每一节（变了什么、以前怎么写、现在怎么写、怎么改），再在项目自己的源码里找出指南里被替换掉的旧名字，列出文件和行号。主题挂点名只认对象键（`progressbar: {`），因为同一个词也是 HTML 标签；属性和选项名按单词认，camelCase 和 kebab-case 都算。
+- 已经一样：说明不用升级，并给出更新日志链接。
+- 没装，或版本写法读不出来：说明情况，并按项目包管理器给出安装命令（读不出包管理器就列全部写法）。
+
+这两份内容都来自 `apps/docs/docs/{en,zh}/guide/migration.md`：小节就是页面的 `###` 小节，旧名字来自小节标题和页面里 `Removed | Use instead` 表格。
+
+## 体检
+
+`doctor` 报告五项检查，不改任何文件：
+
+| 检查 | 什么时候失败或提醒 |
+| --- | --- |
+| `core-version` | 没装 `@astryx-vue/core`（失败）；版本写法读不出来，或比 CLI 的 catalog 旧/新（提醒） |
+| `themes-installed` | 没有依赖 `@astryx-vue/themes`（失败） |
+| `vue-version` | 没装 `vue`（失败）或低于 3.5.0（提醒） |
+| `theme-stylesheet` | 没找到任何 `@astryx-vue/themes/*.css` 引入（失败），或文件名不是内置主题（提醒） |
+| `theme-attribute` | 没找到 `data-astryx-theme`（提醒；Neutral 不写也能用） |
+
+全部通过或只有提醒时退出码是 `0`，有失败时是 `1`，文本照样打印；`--json` 返回 `doctor.report`。只读项目目录里的源码，跳过 `node_modules`、构建产物和隐藏目录。
 
 ## 模板
 
-`template --list` 列出全部 53 个演练场页面。目前 `--type` 只有 `page` 一种；`--type block` 会给一句说明，不报错。
+`template --list` 列出全部 57 个演练场页面。目前 `--type` 只有 `page` 一种；`--type block` 会给一句说明，不报错。
 
-每个模板都有一句手写说明和中英两套关键词，放在 `src/generate/template-meta.ts`。组件清单从页面里 `@astryx-vue/core` 的 import 自动提取，不会和源码脱节。
+每个模板都有一句手写说明和中英两套关键词，放在 `src/generate/template-meta/`，每类模板一个文件。组件清单从页面里 `@astryx-vue/core` 的 import 自动提取，不会和源码脱节。每条记录还带 `dependencies`：这个页面 import 了哪些 npm 包。可复制的模板只会有 `vue` 和 `@astryx-vue/core`，可复制模板若多引一个包，生成 catalog 时直接报错。所以 `template --list`、`template <slug>` 和它们的 `--json` 都能直接说清落地要装什么。
 
 有些页面引用了用户项目装不上的包：5 个用 `@astryx-vue/playground-charts`（只存在于文档站演练场的路径别名）。这些标为 `isReady: false` 并写明原因。判断标准是页面真正执行的导入：只要非相对导入都是 `vue` 或 `@astryx-vue/core` 就算可复制；页面里展示的示例代码文本（例如 `@astryxdesign/core`）属于页面内容，不算导入。`--list` 和 `template <slug>` 照样能看，复制会被拒绝，报 `ERR_TEMPLATE_NOT_READY`。
 
@@ -100,7 +135,7 @@ npm run astryx-vue -- component Button
 
 ## JSON 信封
 
-成功响应是 `{ apiVersion: 1, type, data }`。`template` 和 `build` 的响应还带 `package: "@astryx-vue/cli"`。
+成功响应是 `{ apiVersion: 1, type, data }`。`template`、`build`、`docs` 的响应带 `package`，说明记录来自哪个包（模板是 `@astryx-vue/cli`，文档页是 `@astryx-vue/docs`）。`template.list`、`template.show`、`template.skeleton` 的每条模板记录在 `components` 旁边带 `dependencies`。`component.detail` 和 `composable.detail` 带所属的包；`component.list` 和 `composable.list` 的每一条各自带 `package`，因为一个列表可能横跨多个包。
 
 | 类型 | 命令 |
 | --- | --- |
@@ -111,6 +146,9 @@ npm run astryx-vue -- component Button
 | `docs.list`、`docs.detail` | `docs` |
 | `search` | `search` |
 | `manifest` | `manifest` |
+| `theme.list`、`theme.detail` | `theme` |
+| `upgrade.report` | `upgrade` |
+| `doctor.report` | `doctor` |
 | `init.run` | `init` |
 | `help`、`version` | `--help`、`--version`，或带 `--json` 不带参数 |
 
@@ -131,7 +169,7 @@ npm run astryx-vue -- component Button
 
 ## agent 区块
 
-`init --features agents` 写入这个受管理区块：
+`init` 先打印接入说明（装哪些包、canary 的带 `@canary`（前提是已经发到 npm）、主题样式引哪一行、语言怎么提供、改完怎么验证），再写入这个受管理区块：
 
 ```html
 <!-- Maintained by astryx-vue, do not edit manually -->
@@ -141,7 +179,9 @@ npm run astryx-vue -- component Button
 
 文件不存在就创建。已经有标记时，每次只替换区块内容，其余文字保持不动。文件存在但没有标记时，把区块追加到末尾。第二次运行仍然重写区块，不会因为标记已存在就跳过；生成内容一致时字节不变。
 
-区块里写的是三步工作流（用 `build` 挑页面，用 `template` 复制，写代码前用 `component`/`composable`/`docs` 查），加上查询命令清单和怎么运行这个命令。它不会把组件目录贴进来。
+区块开头列一遍 catalog 覆盖的包。npm 上还没有的包（仓库里标了 `private`）照样列名字，但会写明「还没发布到 npm」并且不给安装命令，免得有人照着敲一个 404；已经发布的 canary 包才会写成 `@canary`。然后写三步工作流（用 `build` 挑页面，用 `template` 复制，写代码前用 `component`/`composable`/`docs` 查），加上查询命令清单和怎么运行这个命令。它不会把组件目录贴进来。
+
+接入说明里的安装命令跟着项目走：先看 `packageManager` 字段，再看 `pnpm-lock.yaml`、`yarn.lock`、`bun.lock(b)`、`package-lock.json`。两样都没有就把四种写法都列出来。`--features` 现在是可选的，写 `agents` 和不写一样，写别的仍然是 `ERR_UNKNOWN_FEATURE`。
 
 写到哪里：
 
@@ -160,11 +200,12 @@ CLI 不另存一份组件文档。`packages/cli/scripts/generate-catalog.mjs`
 - `apps/docs/docs/{en,zh}/components/<slug>/`：用法、props、插槽、事件和示例标题
 - `apps/docs/components/demos/<slug>/*.vue`：那些页面指向的示例源码
 - `apps/docs/components/demo-infra/reference/*.json`：anatomy 和无障碍信息
-- `apps/docs/docs/{en,zh}/guide` 和 `themes`：搜索主题和正文
+- `apps/docs/docs/{en,zh}/guide` 和 `themes`：搜索主题和正文，以及 `theme` 用的主题记录、`init` 用的安装命令和代码片段
+- `apps/docs/docs/{en,zh}/guide/migration.md`：`upgrade` 打印的升级小节，和它去源码里找的旧名字
 - `apps/docs/components/playground/pages/*.vue`：模板源码；`templateManifest.ts`：模板标题和分类
-- 页面里没写 import 时，用 `packages/core/package.json` 的 exports 推断
+- 每个 `packages/*/package.json`：判断组件属于哪个包、版本和说明（`upgrade`/`doctor`/`init` 用）；页面里没写 import 时用它的 exports 推断
 
-模板的说明和关键词是手写的，在 `packages/cli/src/generate/template-meta.ts`，属于源数据，不是生成物。
+模板的说明和关键词是手写的，在 `packages/cli/src/generate/template-meta/`，每类模板一个文件，由 `template-meta.ts` 合并，属于源数据，不是生成物。
 
 示例的标题和说明按语言各存一份，但示例代码两种语言只存一份：两个页面指向的是同一个 `.vue` 文件。以后要是一个页面改了代码、另一个没改，生成时直接报错并指出是哪个组件的第几个示例，不会让一种语言悄悄用上另一种的代码。取回某种语言的示例只走 `packages/cli/src/catalog.ts` 里的 `examplesFor()`。
 
@@ -174,9 +215,11 @@ CLI 不另存一份组件文档。`packages/cli/scripts/generate-catalog.mjs`
 pnpm --filter @astryx-vue/cli generate
 ```
 
-`pnpm check` 会跑 `generate:check`。它会在这几种情况下失败：`catalog.json` 过期、某个 PascalCase 的 `@astryx-vue/core` 导出没有任何组件文档引用、或者某个演练场页面在 `template-meta.ts` 里没有元数据。`./icons`、`./locale`、CSS 和包根不算组件导出。
+`pnpm check` 会跑 `generate:check`。它会在这几种情况下失败：`catalog.json` 过期、某个包里有 PascalCase 导出没有任何组件文档引用、或者某个演练场页面在 `template-meta.ts` 里没有元数据。`./icons`、`./locale`、CSS 和包根不算组件导出。
+
+`catalog.packages` 列出 catalog 覆盖的每个包（`core`、`themes`、`richtext`、`charts`、`lab`），带目录、「是否只发 canary」的标记，以及 `published`。`private` 的包 `published` 是 false：npm 上没有它的版本，所以任何输出都不会给它写安装命令。组件的 `package` 取「有它这个子路径导出的包」，没有就取「`src/` 里有它这个目录的包」。
 
-主题、升级、doctor、swizzle 和 MCP 命令不在这个包里。
+`swizzle`、`discover`、`gap-report`、`integration`、`blog` 不在这个包里，也没有 MCP 服务。`theme`、`upgrade`、`doctor` 只输出指引和报告，都不改项目文件。
 
 ## 相关包
 

package/dist/index.d.ts

@@ -10,17 +10,6 @@ export declare function applyManagedBlock(existing: string | null, inner: string
   action: BlockAction;
 };
 //#endregion
-//#region src/cli.d.ts
-interface CliIO {
-  cwd?: string;
-}
-interface CliResult {
-  exitCode: number;
-  stdout: string;
-  stderr: string;
-}
-export declare function runCli(argv: readonly string[], io?: CliIO): Promise<CliResult>;
-//#endregion
 //#region src/error.d.ts
 interface Suggestion {
   name: string;
@@ -56,6 +45,19 @@ export declare function isError(value: unknown): value is ErrorEnvelope;
 export declare function parseResponse(raw: string): AnyEnvelope;
 export declare function assertResponse<TType extends string>(raw: unknown, type: TType): SuccessEnvelope<TType>;
 //#endregion
+//#region src/cli/context.d.ts
+interface CliIO {
+  cwd?: string;
+}
+interface CliResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+//#endregion
+//#region src/cli.d.ts
+export declare function runCli(argv: readonly string[], io?: CliIO): Promise<CliResult>;
+//#endregion
 //#region src/spec.d.ts
 export declare const API_VERSION = 1;
 export declare const BINARY = "astryx-vue";