@teamix-evo/skills 0.2.0 → 0.4.0

package/src/teamix-evo-manage/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: teamix-evo-manage
+description: |
+  Single entry point for the teamix-evo lifecycle: scaffold a new project, install the AI coding system into an existing repo, run / update / inspect / remove any teamix-evo package, and drive the placeholder→real UI migration loop after `npm create teamix-evo`.
+  TRIGGER when: (CLI) user runs or asks about `teamix-evo tokens ...` / `teamix-evo skills ...` / `teamix-evo ui ...` / `teamix-evo biz-ui ...` / `teamix-evo templates ...` / `teamix-evo logs ...`, or `npm create teamix-evo` / `pnpm create teamix-evo`; (模糊初始化) "初始化一个项目"、"初始化一个工程"、"初始化一个 teamix-evo 工程"、"初始化一个 Teamix Evo 项目"、"create a teamix-evo project"、"set up teamix-evo from scratch"、"new teamix-evo app"; (具名变体初始化) "初始化一个 opentrek 工程 / op 工程 / OpenTrek 项目 / 探索者项目"、"初始化一个云管 / 云管控制台 / 云管项目 / uni-manager 工程 / 云管工程"、"new opentrek/uni-manager project"; (AI coding 接入) "给现有仓库装 teamix-evo"、"现有项目装一下 skills + ui"、"接入 AI coding 体系"、"装 teamix-evo 进这个项目"、"add teamix-evo to existing repo"、"install AI coding system"、"接入 opentrek 研发体系"、"接入 op 研发体系"、"接入 OpenTrek 研发体系"、"接入 opentrek 研发系统"、"接入 op 研发系统"、"接入云管研发体系"、"接入云管研发系统"、"接入 uni-manager 研发体系"、"接入 uni-manager 研发系统"、"接入统一管理研发体系"; (更新检测) "升级 teamix-evo"、"看看哪些要升级"、"update teamix-evo"、"check what needs updating"、"refresh installed teamix-evo packages"; (卸载 / 清单) "卸载 teamix-evo"、"看看装了哪些 teamix-evo 资源"、"remove the design system"、"list installed"; (placeholder→real 升级) "升级 UI"、"接入真组件"、"替换 placeholder"、"upgrade UI"、"replace placeholders"、"swap in real components"、"make the UI real", or user opens / edits `src/components/_placeholder/**`, project contains `.teamix-evo/create/pending-ui.json`, literal `@teamix-evo:placeholder` tag in code; (状态文件) user touches `.teamix-evo/config.json`、`.teamix-evo/manifest.json`、`.teamix-evo/create/pending-ui.json`.
+  SKIP: any content task — generating components, pages, services, or reviewing screens; changes to `src/` files outside the migration loop, design tokens, or business logic. Those go to teamix-evo-code-opentrek or teamix-evo-design-opentrek. SKIP if the user is mid-flow inside an already-initialized project asking to "新增页面 / 加按钮 / 调接口" — that's coding work, not lifecycle. SKIP pure styling / token tweaks — those go to ESLint + `tokens.overrides.css`.
+  Coordinates with: teamix-evo-design-opentrek (visual side after a screen is generated)、teamix-evo-code-opentrek (file placement / reuse rules) — manage is the entry point and precedes content skills, never co-triggers.
+---
+
+# teamix-evo-manage
+
+Single entry skill for the **teamix-evo** toolkit lifecycle. Covers six scenarios:
+
+1. Fuzzy init → ask user to pick a tokens variant.
+2. Named-variant init → infer variant from business name, run scaffold directly.
+3. AI coding install on existing repo (no scaffold step).
+4. Update detection — only refresh what's already installed.
+5. Uninstall.
+6. Placeholder → real UI migration loop (post-`npm create teamix-evo`).
+
+<!-- teamix-evo:managed:start id="core" -->
+
+## 决策树(动手前必看)
+
+```text
+用户的指令命中本 skill
+  ├── 目录里有 `.teamix-evo/`?
+  │     是 ──▶ 4 (更新) / 5 (卸载) / 6 (placeholder→real,见 `pending-ui.json`)
+  │     否 ──▶ 继续
+  ├── 用户说出业务名 / variant?
+  │     是 ──▶ 2 (具名变体初始化) — 用「业务名→variant 映射表」推断
+  │     否 ──▶ 继续
+  ├── 目录是空的(或只有 .git / README.md)?
+  │     是 ──▶ 1 (模糊初始化) — 询问 variant 后转 2
+  │     否 ──▶ 3 (AI coding 接入) — 跳过 scaffold,只跑 tokens/skills/ui init
+```
+
+## 业务名 → variant 映射
+
+> 用户表述业务时,按下表锁定 variant,**不再询问**。表外的关键词必须询问。
+
+| 用户原话(中/英)                                                               | variant       |
+| ----------------------------------------------------------------------------- | ------------- |
+| 云管 / 云管控制台 / 云管项目 / 云管工程 / uni-manager / unimanager / 统一管理 | `uni-manager` |
+| op / opentrek / OpenTrek / 探索者                                             | `opentrek`    |
+| _未提及业务,只说"做一个工程"_                                                 | **询问**      |
+
+校验:`npx teamix-evo tokens list-variants` 列出当前 `@teamix-evo/tokens` 包内所有变体;若上表中的关键词指向尚未发布的变体,先告知用户该 variant 还未上线。
+
+## CLI 命令面(完整)
+
+CLI 二进制名 `teamix-evo`,所有命令都从这里发起。命令名以 `tokens`、`skills`、`ui`、`biz-ui`、`templates`、`logs` 六个 group 组织。
+
+### Tokens(`@teamix-evo/tokens`)
+
+| 目标         | 命令                                                                |
+| ------------ | ------------------------------------------------------------------- |
+| 初始化       | `npx teamix-evo tokens init <variant>`(`<variant>` 必填,无默认)     |
+| 列出可选变体 | `npx teamix-evo tokens list-variants`                               |
+| 列出已装资源 | `npx teamix-evo tokens list`                                        |
+| 升级         | `npx teamix-evo tokens update`(stub — 见 [ADR 0019](docs/adr/0019)) |
+| 卸载         | `npx teamix-evo tokens uninstall [-y] [--keep-files]`               |
+
+- **`<variant>` 必填**。`tokens init` 之前必须先确定 variant(决策树或业务名映射)。
+- `tokens update` 当前是 stub;权宜方案:删除 `.teamix-evo/tokens-lock.json` 与根 `tokens/`,重跑 `tokens init <variant>`。
+- 资源分类(frozen / regenerable / managed)详见 [ADR 0003](docs/adr/0003-update-strategy-tri-state.md):`tokens.overrides.css` 是 `frozen`,用户改写永不被覆盖;`tokens.theme.css` / `tokens/base.tokens.json` 是 `regenerable`,每次 `update` 完整重写。ADR 0020 之后,`tokens init` 不再向工程根落 `AGENTS.md` / `DESIGN.md` 等 `managed` 文件 —— 设计纲领由 `teamix-evo-design-<variant>` skill 自包含。
+
+### Skills(`@teamix-evo/skills`)
+
+| 目标     | 命令                                     |
+| -------- | ---------------------------------------- |
+| 全量装   | `npx teamix-evo skills add`              |
+| 增量装   | `npx teamix-evo skills add <name...>`    |
+| 列出全部 | `npx teamix-evo skills list`(alias `ls`) |
+| 列出已装 | `npx teamix-evo skills list --installed` |
+| 升级     | `npx teamix-evo skills update`           |
+| 卸载     | `npx teamix-evo skills uninstall [-y]`   |
+| 漂移检测 | `npx teamix-evo skills doctor`           |
+| 重新镜像 | `npx teamix-evo skills sync [name...]`   |
+
+`skills add` 模式:
+
+- **Bulk**(无位置参数):装 manifest 中所有 skill;已装的项目返回 `already-added`。
+- **Incremental**(指定 id):只装列出的 skill;已装的跳过(用 `update` 刷新)。
+
+首次交互式(无既有配置且无 flag 时):
+
+1. 多选 IDE:**Qoder** / **Claude Code**(默认两者,至少一个)。等价 `--ide qoder,claude`。
+2. Scope:**project**(默认,`.qoder/.claude` 在 cwd)/ **global**(`~/.qoder/~/.claude`)。等价 `--scope project|global`。
+
+源镜像模型([ADR 0013](docs/adr/0013)):规范副本在 `.teamix-evo/skills/`,IDE 镜像在 `.qoder/skills/` 与 `.claude/skills/`。`doctor` 检测漂移,`sync` 重镜像(不升版本)。
+
+### UI 组件(`@teamix-evo/ui`)
+
+| 目标       | 命令                                   |
+| ---------- | -------------------------------------- |
+| 初始化     | `npx teamix-evo ui init [-y]`          |
+| 增加 entry | `npx teamix-evo ui add <id...>`        |
+| 列出 entry | `npx teamix-evo ui list [--installed]` |
+
+- `ui init` 写 `.teamix-evo/config.json` 的 `packages.ui`(aliases / iconLibrary / tsx / rsc)。可交互元素的 `cursor: pointer` 由组件源码内显式声明,不再有全局 `preferences.css` —— 见 [ADR 0023](docs/adr/0023-cursor-pointer-explicit-in-component-source.md)
+- `ui add` 自动解析 `registryDependencies`,组件源码写入 `src/components/ui/<id>.tsx`(frozen),并报告还需 `pnpm add` 的 npm 包。
+- 没有 `ui upgrade` 子命令 — placeholder→real 迁移由本 skill 的「场景 6」直接驱动,内部调 `ui add`。
+
+### 业务组件(`@teamix-evo/biz-ui`)
+
+| 目标       | 命令                                                 |
+| ---------- | ---------------------------------------------------- |
+| 列出变体   | `npx teamix-evo biz-ui list-variants`                |
+| 增加 entry | `npx teamix-evo biz-ui add <id...> --variant <name>` |
+
+- `--variant <name>` 必填(没有 auto-detect)。
+- [ADR 0014](docs/adr/0014-ui-biz-ui-templates-tier.md):`tokens` / `biz-ui` / `templates` 共享 variant 名空间,与 `tokens init` 选定的 variant 一致。
+
+### 页面模板(`@teamix-evo/templates`)
+
+> ⚠️ **AI 默认不主动调用本 group**(见 [ADR 0031](docs/adr/0031-skill-templates-decoupling.md))。页面骨架由 `teamix-evo-design-<variant>` skill 的 `patterns/*.md` 驱动 ui + biz-ui 拼装;仅在用户**显式**说"用 templates 包装 frozen 骨架"时,才跳转本 group 命令。
+
+| 目标       | 命令                                                    |
+| ---------- | ------------------------------------------------------- |
+| 列出变体   | `npx teamix-evo templates list-variants`                |
+| 增加 entry | `npx teamix-evo templates add <id...> --variant <name>` |
+
+同 `biz-ui` 的变体规则。模板源码写入 `src/templates/<id>.tsx`(frozen)。
+
+### 日志(`@teamix-evo/logs`)
+
+| 目标       | 命令                                |
+| ---------- | ----------------------------------- |
+| 分析调用链 | `npx teamix-evo logs analyze [...]` |
+
+- 读 vibe-logger 输出 `.log/ai/**/*.jsonl`,做 AI 调用链可视化。诊断 `runTokensInit` / `runUiAdd` 等编排流程时用。
+
+## 场景 1 · 模糊初始化
+
+**触发**:用户说"初始化一个项目 / 工程",未指明 variant。
+
+**步骤**:
+
+1. 确认目录(默认 `./<project-name>`,可由用户改)。
+2. 列出 variants(`tokens list-variants` 的输出),让用户选(`AskUserQuestion`):
+   - OpenTrek(opentrek):AI 副驾驶 / 通用中后台
+   - Uni-Manager(uni-manager):云资源管理(大屏 / 拓扑 / 7 类 AI 场景)
+3. 转场景 2,带上选定 variant 直跑。
+
+## 场景 2 · 具名变体初始化(空目录 → 完整工程)
+
+**触发**:用户在「业务名 → variant 映射」中能锁定 variant,或场景 1 询问后得到答复。
+
+**唯一命令**:
+
+```bash
+npm create teamix-evo@latest <dir> --variant <name>
+# 或 pnpm create teamix-evo <dir> --variant <name>
+```
+
+`create-teamix-evo` 的 `console` preset(默认且当前唯一)会自动一站式落地:
+
+| 阶段 | 产物                                                                                     |
+| ---- | ---------------------------------------------------------------------------------------- |
+| 1    | Vite + React + TS scaffold(`src/`、`vite.config.ts` 等)                                  |
+| 2    | `tokens init <variant>` → 根 `tokens/` 目录(`tokens.theme.css` / `tokens.overrides.css`) |
+| 3    | `skills add` → `.qoder/skills/` + `.claude/skills/`(出厂 3 skill)                        |
+| 4    | `ui init` → `.teamix-evo/config.json`                                                    |
+| 5    | `ui add button` → 真组件源码;Card / Input / Form / Table 以 `_placeholder/` 占位         |
+| 6    | `.teamix-evo/create/pending-ui.json` → 4 个 placeholder 待迁移                           |
+
+**完成后告知用户**:
+
+```bash
+cd <dir>
+pnpm dev          # 立刻可跑
+pnpm typecheck    # 验证零类型错误
+```
+
+并提示:「placeholder 占位组件想换真组件?对我说"升级 UI"/"替换 placeholder",我会进入场景 6 逐个迁移。」
+
+## 场景 3 · AI coding 接入(现有仓库)
+
+**触发**:用户已有 React/TS/Vite 仓库(已 `npm install` / 有 `package.json`),只想装 AI coding 体系。
+
+**关键判断**:
+
+- 跳过 scaffold(用户已有 `package.json`、`vite.config.ts`、`src/`)。
+- `npm create teamix-evo` 会拒绝非空目录(除非 `--force` 且不含 `.teamix-evo/`),所以这里改用单包 CLI。
+
+**步骤**:
+
+```bash
+# 1. 确定 variant(若用户未说,按映射表 / 询问)
+npx teamix-evo tokens list-variants
+npx teamix-evo tokens init <variant>          # 装 tokens(写 tokens/ 与 .teamix-evo/tokens-lock.json)
+
+# 2. 装 skills(同源 Qoder + Claude)
+npx teamix-evo skills add                     # 默认两个 IDE 镜像,project scope
+
+# 3. 装 ui 配置
+npx teamix-evo ui init -y
+npx teamix-evo ui add button                  # 可选:先装一个真组件验证
+```
+
+**结束时告诉用户**:
+
+- 已装的 skill 列表(从 `skills list --installed`)、tokens variant、ui aliases。
+- 接下来怎么用:写新页面就触发 `teamix-evo-design-opentrek` / `teamix-evo-code-opentrek`。
+
+## 场景 4 · 更新检测
+
+**触发**:用户说"升级 / 看看哪些要升级 / update teamix-evo"。
+
+**步骤**:
+
+1. 读 `.teamix-evo/config.json` 的 `packages` 字段,看哪些已装(tokens / skills / ui / biz-ui / templates)。
+2. 对每个已装包,跑对应 `list --installed`(若有该子命令)与上游 manifest 比对版本。
+3. 仅对**已装**的包做 update:
+   - `npx teamix-evo tokens update`(stub — 仍提示用户清 + 重装)
+   - `npx teamix-evo skills update`
+   - 没有 `ui update`(组件升级走场景 6 的语义合并 + AI 协作)
+4. 检测 `.teamix-evo/create/pending-ui.json` 是否存在;存在则提示「还有 placeholder 未迁移,要现在进入场景 6 吗?」
+
+**不要**给未安装的包做 install — 那是场景 2/3 的事。
+
+## 场景 5 · 卸载
+
+**触发**:用户说"卸载 teamix-evo / remove the design system"。
+
+| 范围                                          | 命令                                                  |
+| --------------------------------------------- | ----------------------------------------------------- |
+| Tokens                                        | `npx teamix-evo tokens uninstall [-y] [--keep-files]` |
+| Skills                                        | `npx teamix-evo skills uninstall [-y]`                |
+| (UI 不提供卸载,组件源码用户拥有 → 用户手动删) |                                                       |
+
+`tokens uninstall` 默认保留 `managed` 文件以保护用户编辑;`--keep-files` 完全保留物理文件,只清 manifest。
+
+## 场景 6 · placeholder → real UI 升级循环
+
+**触发**:`pending-ui.json` 存在 / 用户说"升级 UI / 替换 placeholder / upgrade UI / replace placeholders" / 用户编辑 `src/components/_placeholder/**` / grep `@teamix-evo:placeholder` 命中。
+
+**5 步循环**(对 `pendingComponents` 每个条目重复):
+
+1. **读** `.teamix-evo/create/pending-ui.json` 拿 `pendingComponents` 列表(每条含 `id` 如 `card` / `input` / `form` / `table` 与当前 placeholder 路径)。
+2. **装真组件**:`npx teamix-evo ui add <id>` → `src/components/ui/<id>.tsx`。**[ADR 0006](docs/adr/0006-ui-upgrade-no-baseline.md)**:无 baseline diff,真组件直接覆盖。
+3. **迁移引用点**:把 `@/components/_placeholder/<Name>` 替换为 `@/components/ui/<id>`。**真组件的 prop API 可能与 placeholder 不同**(prop 名 / 必填项 / slot 形态),逐个 call site 改对。**不要**靠 `as any` 压住类型错误 — prop 差异是有意的。
+4. **删 placeholder 文件** — 全部 import 迁完后删源文件;再 grep 一次旧路径,确认零命中。
+5. **更新** `pending-ui.json`:移除已迁移的条目;`pendingComponents` 空了就删整文件。
+
+循环完后:再 grep `@teamix-evo:placeholder` 字面 tag,任何残留都是漏网的占位,要再迁移或删除。
+
+**告警**:
+
+- placeholder 顶部的 `@teamix-evo:placeholder` 是字面 canary,不能留进生产代码。
+- Form / Table / DataTable 真组件可能需要 Provider(`FormProvider`、`useReactTable` 等)— 在消费侧补 wiring,**不要**把 wiring 包回 `_placeholder/`。
+- 每迁完一个组件,跑一次 `pnpm typecheck`,有错先修干净再迁下一个。
+
+## 配置文件(信息性)
+
+| 路径                                 | 所有者     | 说明                                    |
+| ------------------------------------ | ---------- | --------------------------------------- |
+| `.teamix-evo/config.json`            | CLI        | 已装包清单、版本、IDE / scope           |
+| `.teamix-evo/manifest.json`          | CLI        | 已装资源 ledger;diff / uninstall 的依据 |
+| `.teamix-evo/create/pending-ui.json` | create CLI | 场景 6 的迁移清单;迁完即删              |
+| `tokens/tokens.overrides.css`        | 用户       | 业务自定义 token 覆盖(`frozen`)         |
+
+**不要**手编 `config.json` / `manifest.json`,用对应 CLI 子命令。
+
+## 常见错误与恢复路径(P8 — failures must be observable)
+
+| 症状                                               | 原因                                        | 恢复路径                                                   |
+| -------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------- |
+| `Unknown tokens variant "..."`                     | 拼写错误或上游未发布该 variant              | `npx teamix-evo tokens list-variants` 列出当前可用         |
+| `Target directory already contains a .teamix-evo/` | 误用 `npm create teamix-evo` 进已装目录     | 改走场景 4(更新)或场景 3(增量装)                           |
+| `UI not initialized`(跑 `ui add` 时)               | 未先跑 `ui init`                            | `npx teamix-evo ui init -y` 然后再 `ui add`                |
+| Vite/Tailwind 跑起来没样式                         | `src/index.css` 缺少 tokens / Tailwind 导入 | 检查 `src/index.css` 的 `@import` 顺序                     |
+| `pending-ui.json` 已删但仍有 `_placeholder/` 文件  | 场景 6 中漏迁某个 import                    | grep `@teamix-evo:placeholder` 与 `_placeholder/` 双管验证 |
+| Skills 在 IDE 不触发                               | `.qoder/skills/` 或 `.claude/skills/` 漂移  | `npx teamix-evo skills doctor` 然后 `skills sync`          |
+
+<!-- teamix-evo:managed:end id="core" -->
+
+## Notes for the user
+
+> 这部分内容由你自由编辑。CLI 升级时只会替换 `id="core"` 区段,不会动这里的笔记。

package/skills/teamix-evo-manage/SKILL.md

@@ -1,138 +0,0 @@
----
-name: teamix-evo-manage
-description: Use this skill when the user asks to install, initialize, update, list, or uninstall the teamix-evo toolkit (design system, skills, or related packages) inside the current project. Triggers include phrases like "init teamix-evo", "set up the design system", "update teamix-evo", "remove teamix-evo", "list installed teamix-evo packages", or any lifecycle question about teamix-evo packages such as @teamix-evo/design and @teamix-evo/skills.
----
-
-# teamix-evo-manage
-
-This skill helps the user manage the **teamix-evo** toolkit lifecycle inside their project.
-
-<!-- teamix-evo:managed:start id="core" -->
-
-## When to use
-
-Activate when the user wants to **install / update / inspect / remove** any
-teamix-evo package — typically the design system (`@teamix-evo/design`) or the
-skills package (`@teamix-evo/skills`). Common signals:
-
-- "帮我初始化 teamix-evo 设计体系" / "set up @teamix-evo/design"
-- "升级 teamix-evo" / "update teamix-evo skills"
-- "卸载 teamix-evo" / "remove the design system"
-- "看看装了哪些 teamix-evo 资源"
-
-## What you can do for the user
-
-The CLI binary is `teamix-evo` (bin name), backed by the npm package also
-called `teamix-evo`. All operations are split into **package families**:
-
-### Design system (`@teamix-evo/design`)
-
-| Goal             | Command                                                    |
-| ---------------- | ---------------------------------------------------------- |
-| Initialize       | `npx teamix-evo design init [variant] [--tailwind v3\|v4]` |
-| Update resources | `npx teamix-evo design update`                             |
-| List installed   | `npx teamix-evo design list`                               |
-| Uninstall        | `npx teamix-evo design uninstall [-y] [--keep-files]`      |
-
-- Default variant: `opentrek`.
-- `--tailwind` controls which token entry is wired in. Default: **v4**.
-- Resources marked `frozen` / `regenerable` are physical files; `managed`
-  files use embedded regions (`<!-- teamix-evo:managed:start id="..." -->`)
-  so the user's custom edits survive updates.
-
-### Skills (`@teamix-evo/skills`)
-
-| Goal           | Command                                   |
-| -------------- | ----------------------------------------- |
-| Add (all)      | `npx teamix-evo skills add`               |
-| Add (one+)     | `npx teamix-evo skills add <name...>`     |
-| List (all)     | `npx teamix-evo skills list` (alias `ls`) |
-| List installed | `npx teamix-evo skills list --installed`  |
-| Update         | `npx teamix-evo skills update`            |
-| Uninstall      | `npx teamix-evo skills uninstall [-y]`    |
-
-`skills add` modes:
-
-- **Bulk** (no positional args): installs every skill declared in the
-  manifest. On a project that already has a skills package installed, returns
-  `already-added`.
-- **Incremental** (one or more skill ids): only installs the listed skills.
-  Skills already present are skipped (use `skills update` to refresh). When the
-  project already has a skills config, `--ide` / `--scope` may be omitted —
-  they default to the previously chosen values.
-
-`skills add` is interactive (only when no prior config and no flags):
-
-1. Multi-select target IDE(s): **Qoder** and/or **Claude Code** (default both,
-   at least one required). Non-interactive equivalent: `--ide qoder,claude`.
-2. Scope: **project** (default; `.qoder/.claude` in cwd) or **global**
-   (`~/.qoder/~/.claude`). Non-interactive: `--scope project|global`.
-
-Skills are installed as `SKILL.md` (Anthropic-compatible frontmatter, also
-recognized by Qoder) under `<base>/skills/<name>/SKILL.md`. Update strategy is
-`managed`, so the user's edits inside SKILL.md outside of the marked regions
-are preserved on `update`.
-
-## Workflow you should follow
-
-1. **Detect intent.** Confirm which package family the user wants to touch
-   (design vs skills vs both).
-2. **Check current state.** Suggest running `npx teamix-evo design list` and
-   `npx teamix-evo skills list` to see what's already installed before
-   changing anything.
-3. **Run the smallest correct command.** Prefer the dedicated lifecycle
-   subcommand. Avoid hand-crafted file edits inside `.qoder/`, `.claude/`, or
-   `.teamix-evo/` — let the CLI write through.
-4. **Report and verify.** After running, summarize what changed (files
-   touched, version, IDE, scope) and re-run `list` if useful.
-
-## Configuration files (informational)
-
-- `<projectRoot>/.teamix-evo/config.json` — declares which packages are
-  installed, their versions, IDE selection and scope.
-- `<projectRoot>/.teamix-evo/manifest.json` — installed-resource ledger;
-  CLI uses it for diffing and uninstalling.
-
-Both are **owned by the CLI**. Don't edit by hand unless the user explicitly
-asks; recommend the CLI subcommand instead.
-
-## Common pitfalls
-
-- The CLI must be run from the project root (where `.teamix-evo/` lives or
-  will be created).
-- For `design uninstall`, `managed` files are kept by default to protect user
-  edits. Use `--keep-files` to keep everything (only updates the ledger).
-- A skill's `description` is the AI trigger contract — keep it specific and
-  scenario-rich when editing.
-
-## Console preset upgrade (placeholder → real UI)
-
-Projects scaffolded by `npm create teamix-evo@latest -- --preset console`
-ship with a set of **placeholder components** under
-`src/components/_placeholder/` (Card / Input / Form / Table). They are marked
-with the literal `@teamix-evo:placeholder` tag at the top of each file and
-are registered in `.teamix-evo/create/pending-ui.json`.
-
-**When the user asks to "upgrade UI", "replace placeholders", "接入真组件"**:
-
-1. Read `.teamix-evo/create/pending-ui.json` to know which component IDs are
-   pending and where the placeholder files live.
-2. For each pending component, run `npx teamix-evo ui add <id>` (e.g.
-   `card`, `input`, `form`, `table`). This writes the real implementation to
-   `src/components/ui/<id>.tsx`.
-3. Update import sites: replace `@/components/_placeholder/<Name>` with
-   `@/components/ui/<id>` and adapt the API surface as needed (the real
-   shadcn-style components may have a different signature).
-4. Delete the placeholder file once all references are migrated.
-5. Remove the corresponding entry from `.teamix-evo/create/pending-ui.json`
-   (or delete the file if `pendingComponents` becomes empty).
-
-Grep for `@teamix-evo:placeholder` to discover any remaining placeholders.
-Never leave placeholders in production builds — they are intentionally
-minimal and unstyled.
-
-<!-- teamix-evo:managed:end id="core" -->
-
-## Notes for the user
-
-> 这部分内容由你自由编辑。CLI 升级时只会替换 `id="core"` 区段，不会动这里的笔记。