@teamix-evo/skills 0.4.0 → 0.5.0

package/src/teamix-evo-design-uni-manager/patterns/form-page.md

@@ -1,6 +1,8 @@
 # Form Page — 表单页模式（uni-manager）
 
-> **触发**：用户描述含"新建/创建/编辑/修改/复制/填写"。
+> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **FormPage**，并由 Step 3 引导到这里。
+
+> **触发**：用户描述含“新建/创建/编辑/修改/复制/填写”。
 > **核心特征**：用户输入数据 + 字段校验 + 提交。
 > **页面级别**：L2（面包屑模式 PageHeader，自动继承 um-topbar + Sidebar）。弹窗表单 = L0。
 
@@ -27,7 +29,42 @@
 
 ---
 
-## 2. 布局模式（三选一）
+## 2. Template 组件拼装
+
+> 源自 `packages/create/variants/uni-manager/src/templates/form-page.tsx`
+
+```tsx
+<PageShell header={<UmTopbar />} sidebar={<Sidebar />}>
+  <UmPageContainer header={<PageHeader breadcrumb={...} title="新建 XX" />}>
+    <div className="flex-1 min-h-0 overflow-auto">
+      {children}        {/* FieldGroup 们 / 分区 Card */}
+    </div>
+    {submitBar && (
+      <div className="sticky bottom-0 border-t bg-background">
+        {submitBar}     {/* [取消] [提交] */}
+      </div>
+    )}
+  </UmPageContainer>
+</PageShell>
+```
+
+| Slot         | 注入内容                                  | 说明       |
+| ------------ | ----------------------------------------- | ---------- |
+| `topbar`     | UmTopbar                                  | 框架级吃顶 |
+| `sidebar`    | Sidebar + 业务菜单                        | 左导       |
+| `pageHeader` | PageHeader（面包屑模式 — L2 页面）        | 含返回路径 |
+| `children`   | FieldGroup 们（可用分区 Card 切若干小节） | 滚动区     |
+| `submitBar`  | 取消 + 提交按钮（`justify-end`）          | 粘底悬浮   |
+
+**壳层特征**：
+
+- 表单主区 `flex-1 overflow-auto` — 内容超出视口时内滚
+- SubmitBar 从滚动区移出，`sticky bottom-0` 粘底悬浮
+- SubmitBar 上方 `border-t` 分割线 + `bg-background` 防透
+
+---
+
+## 3. 布局模式（三选一）
 
 ### 2.1 SINGLE_COL（默认）
 
@@ -96,7 +133,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 3. 必需组件
+## 4. 必需组件
 
 | 组件                  | 位置   | 说明                                  |
 | --------------------- | ------ | ------------------------------------- |
@@ -108,7 +145,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 4. SubmitBar / Footer 规则
+## 5. SubmitBar / Footer 规则
 
 ### 4.1 智能定位
 
@@ -132,7 +169,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 5. 字段控件选型
+## 6. 字段控件选型
 
 > **枚举数量阈值规则（≤7 RadioGroup / 8-30 Select / >30 Combobox）见 [components.md §3.5 输入控件](../components.md#35-输入控件--input-vs-select-vs-combobox)**。本节只列表单页专属补充字段。
 
@@ -151,7 +188,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 6. 字段校验规则
+## 7. 字段校验规则
 
 ### 6.1 触发时机
 
@@ -178,7 +215,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 7. 提交交互
+## 8. 提交交互
 
 ### 7.1 操作流
 
@@ -216,7 +253,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 8. shadcn 表单组合契约
+## 9. shadcn 表单组合契约
 
 > 表单**组合层面**的本地约定。视觉/全局规则参见 [boundaries.md FF1-FF4](../boundaries.md#ff1-ff4--表单专属硬约束)（色块、必填、Card 嵌套、错误文案）+ [boundaries.md S2](../boundaries.md#error-s2--不用-space-x---space-y--改用-flex--gap-)（gap 替代 space-y）+ [boundaries.md F8](../boundaries.md#error-f8--禁止在-dialogtitle-中加图标--scope-dialog)（DialogTitle 无图标）+ [boundaries.md F9](../boundaries.md#error-f9--弹窗确定按钮禁止加-disabled-禁用态--scope-dialog)（提交按钮无 disabled）。
 
@@ -230,7 +267,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 9. 嵌套约束
+## 10. 嵌套约束
 
 | 父子关系                                                                                      | 状态                        |
 | --------------------------------------------------------------------------------------------- | --------------------------- |
@@ -248,7 +285,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 10. 禁止项
+## 11. 禁止项
 
 | 禁项                        | 原因                             |
 | --------------------------- | -------------------------------- |
@@ -262,7 +299,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 11. 表单页特有自检
+## 12. 表单页特有自检
 
 - [ ] PageHeader 用面包屑模式（L2 页面）
 - [ ] um-topbar 在框架层就位（UM1）
@@ -280,7 +317,7 @@ SubmitBar  [取消] [创建]
 
 ---
 
-## 12. 《Teamix UI 表单设计规范》对齐 Checklist
+## 13. 《Teamix UI 表单设计规范》对齐 Checklist
 
 > 详细说明见 [`packages/ui/AGENTS.md` 第六节](../../../../ui/AGENTS.md#六表单族硬规则formfieldfilter-barlabelinput)。本节只列 AI 写表单时的 yes/no 自检项。
 

package/src/teamix-evo-design-uni-manager/patterns/list-page.md

@@ -1,6 +1,8 @@
 # List Page — 列表页模式（uni-manager）
 
-> **触发**：用户描述含"列表/表格/查询/检索/卡片管理"。
+> ⚠️ **Prerequisites**: 你必须已在 [generation-flow.md](../generation-flow.md) Step 2 确认页面类型为 **ListPage**，并由 Step 3 引导到这里。
+
+> **触发**：用户描述含“列表/表格/查询/检索/卡片管理”。
 > **核心特征**：多条结构化数据 + 搜索/筛选 + 分页。
 > **页面级别**：L1（标题模式 PageHeader，自动继承 um-topbar + Sidebar）。
 > **uni-manager 增强**：高密度行（36-40px）+ 跨云 CloudBadge 列 + 多租户 / 多区域筛选维度 + 批量操作高频。
@@ -35,7 +37,38 @@
 
 ---
 
-## 2. 标准结构
+## 2. Template 组件拼装
+
+> 源自 `packages/create/variants/uni-manager/src/templates/list-page.tsx`
+
+```tsx
+<PageShell header={<UmTopbar />} sidebar={<Sidebar />}>
+  <UmPageContainer header={<PageHeader title="..." actions={...} />}>
+    {toolbar}       {/* ActionToolbar / SearchCombo / 筛选按钮 */}
+    {children}      {/* DataTable / CardGrid 主内容区 */}
+    {footer}        {/* Pagination / BulkActionBar */}
+  </UmPageContainer>
+</PageShell>
+```
+
+| Slot         | 注入内容                                    | 说明                        |
+| ------------ | ------------------------------------------- | --------------------------- |
+| `topbar`     | UmTopbar                                    | 框架级吃顶（租户/区域切换） |
+| `sidebar`    | Sidebar + 业务菜单                          | 左导                        |
+| `pageHeader` | PageHeader（title + description + actions） | 标题模式 L1                 |
+| `toolbar`    | ActionToolbar / SearchCombo / 筛选行        | PageHeader 下方、主区上方   |
+| `children`   | DataTable / CardGrid                        | 主内容区（撑高）            |
+| `footer`     | Pagination + BulkActionBar                  | 紧贴表格底部                |
+
+**壳层特征**：
+
+- UmPageContainer **无白卡** — 业务组件直接坐在白底主区上
+- 与 OpenTrek 的“内嵌大白卡”对仗：um 主区无额外包裹层
+- footer 紧贴表格底部，页面整体溢出由父级 SidebarInset overflow 接管
+
+---
+
+## 3. 标准结构（设计线框）
 
 ```
 ┌────────────────────────────────────────────┐
@@ -57,7 +90,7 @@
 
 ---
 
-## 3. 必需组件
+## 4. 必需组件
 
 | 组件                          | 位置    | 说明                                                        |
 | ----------------------------- | ------- | ----------------------------------------------------------- |
@@ -70,7 +103,7 @@
 
 ---
 
-## 4. SearchCombo 规范
+## 5. SearchCombo 规范
 
 > ListPage 顶部搜索 + 筛选的标准复合组件。**禁止**用 Input + Select 散件拼装。
 
@@ -131,7 +164,7 @@
 
 ---
 
-## 5. DataTable 规则（核心）
+## 6. DataTable 规则（核心）
 
 ### 5.1 列元规则（每列必备）
 
@@ -205,7 +238,7 @@
 
 ---
 
-## 6. 操作列规范（硬约束）
+## 7. 操作列规范（硬约束）
 
 ### 6.1 结构
 
@@ -237,7 +270,7 @@
 
 ---
 
-## 7. Card 内对齐规则（硬约束）
+## 8. Card 内对齐规则（硬约束）
 
 水平 padding 分层模型：
 
@@ -270,7 +303,7 @@
 
 ---
 
-## 8. 状态-操作模式
+## 9. 状态-操作模式
 
 ### 8.1 元规则
 
@@ -306,7 +339,7 @@
 
 ---
 
-## 9. 嵌套约束
+## 10. 嵌套约束
 
 | 父子关系                                                                                                    | 状态                         |
 | ----------------------------------------------------------------------------------------------------------- | ---------------------------- |
@@ -321,7 +354,7 @@
 
 ---
 
-## 10. 禁止项
+## 11. 禁止项
 
 | 禁项                    | 原因                                |
 | ----------------------- | ----------------------------------- |
@@ -337,7 +370,7 @@
 
 ---
 
-## 11. 列表页特有自检
+## 12. 列表页特有自检
 
 - [ ] PageHeader / ActionToolbar / DataTable / Pagination 嵌套结构正确
 - [ ] um-topbar 在框架层就位（UM1）

package/src/teamix-evo-design-uni-manager/patterns/page-types.md

@@ -1,8 +1,10 @@
 # Page Types — 5 种标准页面类型（uni-manager）
 
+> ⚠️ **Prerequisites**: 你必须由 [generation-flow.md](../generation-flow.md) Step 2 引导到这里。若未完成 Step 1（需求确认），请先返回。
+
 > AI 生成页面前**必须先识别页面类型**，再选择对应模式。本文档是 generation-flow.md Step 2 的核心输入。
 >
-> uni-manager 与 OpenTrek 五型同构，差异在于：**Dashboard 默认承担"Console Home"**、所有 L1/L2 页面**必须挂在 `um-topbar` 之下**。
+> uni-manager 与 OpenTrek 五型同构，差异在于：**Dashboard 默认承担“Console Home”**、所有 L1/L2 页面**必须挂在 `um-topbar` 之下**。
 
 ---
 

package/src/teamix-evo-design-uni-manager/philosophy.md

@@ -1,6 +1,8 @@
 # 设计哲学 · Uni-Manager
 
-> 回答**"为什么这么做"**。具体规则见 [boundaries.md](./boundaries.md) / [foundations.md](./foundations.md)。
+> ⚠️ **何时读本文件**: [generation-flow.md](./generation-flow.md) Step 1 强制要求读取。本文件建立“为什么这么做”的认知基础，是后续所有决策的裁判依据。
+
+> 回答**“为什么这么做”**。具体规则见 [boundaries.md](./boundaries.md) / [foundations.md](./foundations.md)。
 
 ---
 

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

@@ -2,7 +2,7 @@
 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`.
+  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 lint ...` / `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.
 ---
@@ -18,6 +18,34 @@ Single entry skill for the **teamix-evo** toolkit lifecycle. Covers six scenario
 5. Uninstall.
 6. Placeholder → real UI migration loop (post-`npm create teamix-evo`).
 
+## 安装方式
+
+本 skill 是 **entry skill**(lifecycle orchestrator),manifest 里声明 `scope: "global"`。**推荐全局安装一次**:
+
+```bash
+npx teamix-evo skills add teamix-evo-manage --scope global
+```
+
+`skills add`(默认 project scope)与 `npm create teamix-evo` **不会**自动装本 skill —— bulk 模式按 scope 自动跳过(ADR 0033)。如果用户在项目级显式 `skills add teamix-evo-manage --scope project`,CLI 给出"推荐 global"warning 但仍装入(用户自负责),代价是后续 IDE 会同时识别全局与项目两份副本。
+
+## 自助升级
+
+升级到最新版本(任何目录可跑 — 自动找全局 meta root):
+
+```bash
+npx teamix-evo@latest skills update                       # 全部已装
+npx teamix-evo@latest skills update teamix-evo-manage     # 只升 manage 一个
+npx teamix-evo@latest skills update --dry-run             # 预览,不写盘
+```
+
+`@latest` 让 npx 拉最新 CLI + 最新 `@teamix-evo/skills` 包。命令头部会打印 CLI 版本与 skills 包版本,方便排查 npx cache 与包不同步的问题。
+
+升级范围(ADR 0035 双闸):
+
+- 只更新 lock 里**已装**的 skill — 新 skill 用 `skills add <id>` 显式加入,不会被 update 自动装上
+- 只更新 scope 与当前 install scope 一致的 skill — 项目级 update 不会动全局 manage,反之亦然
+- 版本完全一致时短路,不重写源(managed 区域用户改动不被来回备份)
+
 <!-- teamix-evo:managed:start id="core" -->
 
 ## 决策树(动手前必看)
@@ -25,7 +53,7 @@ Single entry skill for the **teamix-evo** toolkit lifecycle. Covers six scenario
 ```text
 用户的指令命中本 skill
   ├── 目录里有 `.teamix-evo/`?
-  │     是 ──▶ 4 (更新) / 5 (卸载) / 6 (placeholder→real,见 `pending-ui.json`)
+  │     是 ──▶ 4 (更新) / 5 (卸载)
   │     否 ──▶ 继续
   ├── 用户说出业务名 / variant?
   │     是 ──▶ 2 (具名变体初始化) — 用「业务名→variant 映射表」推断
@@ -67,21 +95,23 @@ CLI 二进制名 `teamix-evo`,所有命令都从这里发起。命令名以 `tok
 
 ### 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...]`   |
+| 目标     | 命令                                                 |
+| -------- | ---------------------------------------------------- |
+| 自举     | `npx teamix-evo skills init`                         |
+| 增量装   | `npx teamix-evo skills add <name...>`                |
+| 列出全部 | `npx teamix-evo skills list`(alias `ls`)             |
+| 列出已装 | `npx teamix-evo skills list --installed`             |
+| 升级     | `npx teamix-evo skills update [name...] [--dry-run]` |
+| 卸载     | `npx teamix-evo skills uninstall [-y]`               |
+| 漂移检测 | `npx teamix-evo skills doctor`                       |
+| 重新镜像 | `npx teamix-evo skills sync [name...]`               |
+
+> 升级语义见 ADR 0035 双闸:仅升级 lock 已装且 scope 匹配的 skill;version 完全一致时短路;新 skill 用 `skills add <id>` 显式加入。
 
-`skills add` 模式:
+verb 分工(ADR 0034):
 
-- **Bulk**(无位置参数):装 manifest 中所有 skill;已装的项目返回 `already-added`。
-- **Incremental**(指定 id):只装列出的 skill;已装的跳过(用 `update` 刷新)。
+- **`skills init`**(无 ids):自举 — 按当前 tokens variant + install scope 装 manifest 里全部符合条件的 skill。已装的工程再跑会返回 `already-initialized`。
+- **`skills add <name...>`**(必填 ids):增量 — 只装列出的 skill;已装的跳过(用 `update` 刷新)。不传 id 会被 commander 拒绝并输出 help。
 
 首次交互式(无既有配置且无 flag 时):
 
@@ -100,7 +130,7 @@ CLI 二进制名 `teamix-evo`,所有命令都从这里发起。命令名以 `tok
 
 - `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`。
+- 没有 `ui upgrade` 子命令 — 组件升级走 `ui add` 覆盖即可。
 
 ### 业务组件(`@teamix-evo/biz-ui`)
 
@@ -129,7 +159,7 @@ CLI 二进制名 `teamix-evo`,所有命令都从这里发起。命令名以 `tok
 | ---------- | ----------------------------------- |
 | 分析调用链 | `npx teamix-evo logs analyze [...]` |
 
-- 读 vibe-logger 输出 `.log/ai/**/*.jsonl`,做 AI 调用链可视化。诊断 `runTokensInit` / `runUiAdd` 等编排流程时用。
+- 读 vibe-logger 输出 `.teamix-evo/logs/ai/**/*.jsonl`,做 AI 调用链可视化。诊断 `runTokensInit` / `runUiAdd` 等编排流程时用。
 
 ## 场景 1 · 模糊初始化
 
@@ -156,14 +186,16 @@ npm create teamix-evo@latest <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 待迁移                           |
+| 阶段 | 产物                                                                                                       |
+| ---- | ---------------------------------------------------------------------------------------------------------- |
+| 1    | Vite + React + TS scaffold(`src/`、`vite.config.ts` 等)                                                    |
+| 2    | `tokens init <variant>` → 根 `tokens/` 目录(`tokens.theme.css` / `tokens.overrides.css`)                   |
+| 3    | `skills add design-<variant> code-<variant>` → 项目级装 2 个 variant 内容 skill(manage 不在内,见 ADR 0033) |
+| 4    | `ui init` → `.teamix-evo/config.json`                                                                      |
+| 5    | `ui add` → 真组件源码(button / card / input / form / table 等)                                             |
+| 6    | `lint init` → ESLint + Stylelint 配置                                                                      |
+
+> 提示:`teamix-evo-manage` 是 entry skill,推荐**全局**装一次(`npx teamix-evo skills add teamix-evo-manage --scope global`)。create CLI 不会装它到 project,scaffold 完成后的 next-steps 会提示用户。
 
 **完成后告知用户**:
 
@@ -173,8 +205,6 @@ pnpm dev          # 立刻可跑
 pnpm typecheck    # 验证零类型错误
 ```
 
-并提示:「placeholder 占位组件想换真组件?对我说"升级 UI"/"替换 placeholder",我会进入场景 6 逐个迁移。」
-
 ## 场景 3 · AI coding 接入(现有仓库)
 
 **触发**:用户已有 React/TS/Vite 仓库(已 `npm install` / 有 `package.json`),只想装 AI coding 体系。
@@ -191,8 +221,8 @@ pnpm typecheck    # 验证零类型错误
 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
+# 2. 自举 skills(同源 Qoder + Claude;manage 是 global-only,自举自动跳过 — ADR 0033 + 0034)
+npx teamix-evo skills init                    # 项目级装 design-<variant> + code-<variant>,默认两个 IDE 镜像
 
 # 3. 装 ui 配置
 npx teamix-evo ui init -y
@@ -203,6 +233,7 @@ npx teamix-evo ui add button                  # 可选:先装一个真组件验
 
 - 已装的 skill 列表(从 `skills list --installed`)、tokens variant、ui aliases。
 - 接下来怎么用:写新页面就触发 `teamix-evo-design-opentrek` / `teamix-evo-code-opentrek`。
+- 若全局尚未安装 entry skill,补一句:`npx teamix-evo skills add teamix-evo-manage --scope global`(ADR 0033)。
 
 ## 场景 4 · 更新检测
 
@@ -214,9 +245,8 @@ npx teamix-evo ui add button                  # 可选:先装一个真组件验
 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 吗?」
+   - `npx teamix-evo skills update [name...] [--dry-run]` — 双闸 + version 短路 + 可选限定 id(ADR 0035)。先 `--dry-run` 给用户看清单,确认后再无 flag 跑一遍真升级
+   - 没有 `ui update`(组件升级走 `ui add` 覆盖即可)
 
 **不要**给未安装的包做 install — 那是场景 2/3 的事。
 
@@ -232,47 +262,25 @@ npx teamix-evo ui add button                  # 可选:先装一个真组件验
 
 `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`)         |
+| 路径                          | 所有者 | 说明                                    |
+| ----------------------------- | ------ | --------------------------------------- |
+| `.teamix-evo/config.json`     | CLI    | 已装包清单、版本、IDE / scope           |
+| `.teamix-evo/manifest.json`   | CLI    | 已装资源 ledger;diff / uninstall 的依据 |
+| `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`          |
+| 症状                                               | 原因                                        | 恢复路径                                           |
+| -------------------------------------------------- | ------------------------------------------- | -------------------------------------------------- |
+| `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` 顺序             |
+| Skills 在 IDE 不触发                               | `.qoder/skills/` 或 `.claude/skills/` 漂移  | `npx teamix-evo skills doctor` 然后 `skills sync`  |
 
 <!-- teamix-evo:managed:end id="core" -->