@teamix-evo/skills 0.12.1 → 0.13.0

package/src/teamix-evo-manage/update-token-rename.md

@@ -0,0 +1,126 @@
+# Part A — Token rename adoption
+
+## What is a hint file
+
+When `teamix-evo tokens update` bumps a variant version that ships a `renames` log, or `teamix-evo switch --apply` lands on a new variant whose history contains renames, the CLI writes a single JSON file:
+
+```
+.teamix-evo/
+└── .upgrade-hints/
+    └── tokens-2026-06-12T03-15-00-000Z.json
+```
+
+Schema v1 payload (every field is required except `description` per rename):
+
+```json
+{
+  "schemaVersion": 1,
+  "ts": "2026-06-12T03:15:00.000Z",
+  "package": "tokens",
+  "trigger": "update",
+  "fromVariant": "opentrek",
+  "toVariant": "opentrek",
+  "fromVersion": "0.5.0",
+  "toVersion": "0.6.5",
+  "renames": [
+    {
+      "sinceVersion": "0.6.0",
+      "from": "--color-old",
+      "to": "--color-new"
+    },
+    {
+      "sinceVersion": "0.6.5",
+      "from": "--space-x",
+      "to": "--space-h",
+      "description": "horizontal axis rename"
+    }
+  ]
+}
+```
+
+> `trigger` is `"update"` for version-bump hints and `"switch"` for variant-switch hints. Both consume the same way — only the framing line differs.
+
+## Workflow (5 steps, never skip step 4)
+
+### A1 · Discover
+
+List every hint file under `.teamix-evo/.upgrade-hints/`. Sort newest-first by filename (the `tokens-<fs-ts>.json` ts is filesystem-safe and lexically chronological).
+
+```bash
+ls -1 .teamix-evo/.upgrade-hints/tokens-*.json 2>/dev/null
+```
+
+If the directory is missing or empty, tell the user:
+
+> 当前没有待处理的 token rename hint。这通常意味着最近一次 `tokens update` / `switch` 没有跨过 rename 节点；你可以继续做你原本的事。
+
+### A2 · Aggregate
+
+Read each hint and aggregate the `renames` arrays into a single `from → to` map. When two hints rename the same token (rare — usually means a token was renamed twice across versions), the **newest hint wins** and the older mapping is discarded (treat the chain as resolved).
+
+Surface a one-line summary per hint to the user:
+
+> `tokens-…06-12T03-15-00-000Z.json` · update · opentrek 0.5.0 → 0.6.5 · 2 renames
+
+### A3 · Scan
+
+For each `from` token, run a project-wide search across the consumer-owned surface (never read `node_modules/` or `dist/`). The exact glob set depends on which token shape the rename targets:
+
+| `from` shape                                  | Where to search                                                            | Tooling          |
+| --------------------------------------------- | -------------------------------------------------------------------------- | ---------------- |
+| CSS variable (`--color-old`)                  | `src/**/*.{ts,tsx,js,jsx,css,scss,md,mdx}` + `tokens/tokens.overrides.css` | grep / Grep tool |
+| Tailwind class fragment (e.g. `bg-color-old`) | `src/**/*.{ts,tsx,jsx}` + `index.html`                                     | grep             |
+| Token JSON path (`color.old`)                 | `tokens/**/*.json` if any                                                  | grep             |
+
+Explicitly exclude:
+
+- `node_modules/**`、`dist/**`、`build/**`、`.next/**`
+- Anything under `.teamix-evo/snapshots/**` (those are restore points, not live code)
+- The hint file itself
+
+For each occurrence collect: file path, 1-based line number, the matched line.
+
+### A4 · Propose & ask (HARD GATE)
+
+For every `from → to` rename, show a diff hunk and **ask the user per file** before touching it. Use this template:
+
+```
+─── tokens/tokens.overrides.css (1 occurrence) ───
+- 12 |   color: var(--color-old);
++ 12 |   color: var(--color-new);
+
+─── src/components/Banner.tsx (3 occurrences) ───
+- 18 |   className="text-[var(--color-old)]"
++ 18 |   className="text-[var(--color-new)]"
+…
+
+应用这些修改？(y / n / per-file)
+```
+
+`per-file` lets the user pick file-by-file. Default to **no** if the user is silent. **Never auto-apply.** This is the entire reason the rename pipeline exists — frozen boundary (用户源码由用户确认后才改).
+
+If the user declines a particular file, record it in your reply (`保留：src/legacy/old-page.tsx — 用户选择不替换`) so they can come back to it later.
+
+### A5 · Archive processed hints
+
+After (and only after) the user has either accepted or explicitly skipped every rename in a hint file, **move the hint into the archive subdirectory** so subsequent runs don't re-prompt:
+
+```bash
+mkdir -p .teamix-evo/.upgrade-hints/.processed
+mv .teamix-evo/.upgrade-hints/tokens-<ts>.json .teamix-evo/.upgrade-hints/.processed/
+```
+
+Tell the user the file moved and that they can `git diff` to review the rewrites + the hint move in one shot.
+
+> If the user wants to **defer** an entire hint (not just per-file skip), leave it in place and tell them they can re-run this flow later.
+
+## Edge cases (token rename)
+
+| Situation                                                       | Response                                                                                                                  |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Hint file fails JSON parse / wrong schemaVersion                | Print the file path + the parse error; **do not** delete it. Suggest the user inspect or run `teamix-evo restore --list`. |
+| `from` token literally not found in `src/**`                    | Tell the user the rename is "已经无影响" and ask whether to archive the hint anyway.                                      |
+| Multiple hint files pending                                     | Process newest-first one hint at a time — never batch across hints (keeps the diff small and the user in control).        |
+| User says "全部接受" / "apply all"                              | Still show every diff before applying. Bulk-confirm is fine, **silent apply is not**.                                     |
+| Project has no `src/` (library / monorepo root)                 | Ask the user which directory to scan; default to `packages/*/src` if a `pnpm-workspace.yaml` is present.                  |
+| User asks to handle an old hint that's already in `.processed/` | Read it from `.processed/`, re-run scan, and let the user decide whether to apply again or remove it permanently.         |

package/src/teamix-evo-manage/update-token-treatment.md

@@ -0,0 +1,116 @@
+# Part C — Token treatment pipeline
+
+After `teamix-evo init` lands tokens + ESLint rules, the project often has pre-existing token violations (hardcoded colors, raw Tailwind scales, etc.). The CLI provides a **diagnose → treat → reflect → baseline-lock** pipeline to systematically clean them up. This flow guides the user through it.
+
+> **Coordinates with**: [update-token-rename.md](update-token-rename.md) (Part A) handles _rename_ hints from upstream version bumps; Part C handles _project-internal_ violations detected by ESLint rules.
+
+## When to trigger
+
+TRIGGER when: user references "token 治理"、"tokens diagnose"、"tokens treat"、"治理计划"、".treatment-plan.md"、"baseline 锁定"、"token 反哺"、"清理 token 违规"、"token cleanup"、"lint baseline"、"降违规"、"全部治理"; AI sees output of `teamix-evo init` showing token-discipline ESLint warnings and the user wants to follow up; user opens any `.teamix-evo/.treatment-plan.md`.
+
+SKIP: rename hints (Part A), component source upgrades (Part B), design decisions (defer to design skill).
+
+## C1 · Diagnose
+
+Run the diagnosis to understand the current violation landscape:
+
+```bash
+npx teamix-evo@latest tokens diagnose
+```
+
+This produces `.teamix-evo/.treatment-plan.md` — a tiered treatment plan classifying violations into:
+
+| Phase            | Description                                                    | Automation |
+| ---------------- | -------------------------------------------------------------- | ---------- |
+| L1-structure     | Token file structure issues (via `tokens audit`)               | audit      |
+| L2-format        | Color format normalisation (`hsl()` → CSS v4)                  | full-auto  |
+| L3-semantic-auto | Tailwind scale → semantic tokens                               | full-auto  |
+| L3-semantic-semi | Arbitrary values → tokens (AI-guided)                          | semi-auto  |
+| L3-manual        | Requires human judgment (radius, border, dark mode)            | manual     |
+| reflect          | High-frequency color literals → project-level token candidates | analysis   |
+
+Present the plan overview to the user and ask which phases they want to tackle now.
+
+## C2 · Treat (automated codemods)
+
+For full-auto phases (L2 + L3-auto), run the treatment pipeline:
+
+```bash
+# Dry-run first (recommended)
+npx teamix-evo@latest tokens treat
+
+# Apply changes
+npx teamix-evo@latest tokens treat --apply
+
+# Apply + lock baseline
+npx teamix-evo@latest tokens treat --apply --lock-baseline
+```
+
+The pipeline executes 4 codemods in order:
+
+1. `hsl-to-v4` — HSL function → CSS v4 color syntax
+2. `hex-to-token` — hardcoded hex → semantic token reference
+3. `tw-scale-to-semantic` — raw Tailwind color scale → semantic class
+4. `space-to-gap` — space utility → gap utility
+
+After execution, a treatment report is generated at `.teamix-evo/.treatment-reports/<timestamp>.md` showing per-rule before/after deltas.
+
+### Workflow
+
+1. **Always dry-run first** — show the user the match counts and ask for confirmation
+2. Show the delta table from the report
+3. If the user approves, re-run with `--apply`
+4. Ask whether to lock the baseline (`--lock-baseline`)
+
+## C3 · Semi-auto treatment (AI-guided)
+
+For `L3-semantic-semi` violations (`no-arbitrary-tw-value`):
+
+1. Read the treatment plan's L3-semi section for the list of violations
+2. For each violation, read the file context and suggest the closest semantic token
+3. Present a diff hunk per file (same template as [update-token-rename.md](update-token-rename.md) step A4)
+4. **HARD GATE** — never auto-apply; get per-file confirmation
+
+## C4 · Reflect (token 反哺)
+
+After automated treatment, remaining `no-color-literal` violations often reveal project-specific colors not covered by the design system. Suggest the user run reflect analysis:
+
+1. Scan remaining violations and cluster by color value + frequency
+2. Present a table of candidates (color → suggested token name → occurrence count → files)
+3. Colors appearing ≥ 3 times are candidates for project-level tokens
+4. Guide the user to add chosen tokens to `tokens/tokens.overrides.css`
+5. After adding tokens, re-run `tokens treat` to pick up the new mappings
+
+## C5 · Baseline lock
+
+Once the user is satisfied with the treatment level:
+
+```bash
+npx teamix-evo@latest tokens treat --apply --lock-baseline
+```
+
+This writes `.teamix-evo/tokens-baseline.json` — a snapshot of current violation counts. Future `tokens treat` runs will compare against this baseline.
+
+**CI integration**: add to `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "lint:baseline": "teamix-evo tokens treat --lock-baseline && git diff --exit-code .teamix-evo/tokens-baseline.json"
+  }
+}
+```
+
+If violations exceed the locked baseline, CI fails — preventing regression.
+
+## C6 · Edge cases
+
+| Situation                                         | Response                                                                   |
+| ------------------------------------------------- | -------------------------------------------------------------------------- |
+| No ESLint config / teamix-evo rules not installed | Tell the user to run `teamix-evo init` first to set up the lint rules.     |
+| No `src/` directory                               | Ask which directory to scan; default to `packages/*/src` in monorepo.      |
+| Codemod not found                                 | Skip gracefully; the pipeline only runs available codemods.                |
+| User wants to skip a phase                        | Respect the choice; only run requested phases.                             |
+| Baseline already exists                           | Show current vs baseline comparison before re-locking.                     |
+| Treatment report shows 0 delta                    | All violations are either semi-auto or manual; guide user to C3/C4.        |
+| User says "全部治理"                              | Run diagnose → treat --apply → reflect in sequence, but confirm each step. |

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

@@ -0,0 +1,213 @@
+# Update (Teamix Evo 套件更新)
+
+> **前置条件**：当前目录已接入 teamix-evo（`.teamix-evo/` 存在）。
+> 非 teamix-evo 工程执行时被 `assertCommandPrecondition` 拒绝。
+
+本文件覆盖 **持续更新**（tokens / skills / ui / biz-ui / blocks 版本追踪 + staging 生成 + apply）。
+
+更新应用的三条独立 workflow 拆分到子文件：
+
+| 子文件                                                         | 覆盖范围                               | 触发关键词                                     |
+| -------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------- |
+| [update-token-rename.md](update-token-rename.md)             | Part A — Token rename adoption         | token 改名 / rename hint / `.upgrade-hints/`   |
+| [update-component-staging.md](update-component-staging.md)   | Part B — Component source staging apply| staging / apply / `.upgrade-staging/`           |
+| [update-token-treatment.md](update-token-treatment.md)       | Part C — Token treatment pipeline      | token 治理 / diagnose / treat / baseline / 反哺|
+
+---
+
+## §0 · 资源升级覆盖总览
+
+| 资源类型 | 升级方式 | 用户操作 |
+| --- | --- | --- |
+| tokens | `tokens update` — 刷新 regenerable，frozen 保留 | CLI 自动 |
+| skills | `skills update` — 版本对比 + 覆写/managed merge | CLI 自动 |
+| ui / biz-ui / blocks | `ui update` / `biz-ui update` / `blocks update` → staging → 逐个 apply | AI 引导逐个确认 |
+| **AGENTS.md** | `skills update` / `switch` 后自动刷新 managed 区段 | CLI 自动（非关键，失败只 warn） |
+| **lint 规则包** | `update` 报告展示当前版本，提示 `pnpm update` 检查更新 | 用户手动 `pnpm update` |
+| **config.json** | CLI 读取时 Zod `.transform()` 自动 v1→v2 迁移，无感 | 无需操作 |
+| **manifest.json** | 当前 v1，无 migration 需求；未来版本同 config.json 模式 | 无需操作 |
+
+## §1 · 顶层更新入口
+
+**触发**：用户表达"更新 / update / 升级套件 / 升级组件 / 看看有什么新版 / 更新 ui"等关键词。
+
+**一行命令**：
+
+```bash
+npx teamix-evo@latest update              # 输出当前安装状态报告
+npx teamix-evo@latest update --json       # JSON 格式（供 AI 消费）
+```
+
+`update` 输出已安装资产清单后，根据用户意图引导调用对应子命令。
+
+## §2 · 单 skill 升级（"升级 manage skill / 升级 design skill"）
+
+**触发**：用户明确指定要升级某个 skill（如"升级 teamix-evo-manage / 更新 design skill / update manage skill"）。
+
+**命令**：
+
+```bash
+npx teamix-evo@latest skills update <skill-id>           # 指定 skill
+npx teamix-evo@latest skills update <skill-id> --dry-run  # 先预览
+```
+
+## §3 · 组件源码升级（`teamix-evo ui update` / `teamix-evo biz-ui update`）
+
+**触发**：用户表达"升级 ui / 升级业务组件 / 升级 button / 看看哪些组件有新版 / update ui / update biz-ui / stage ui update"等关键词。
+
+> 这里是**版本演进**（installed 资源 → 上游新版 → staging → 逐个 apply），是安装完成后跟随上游发布的升级流程。
+
+**一行命令**：
+
+```bash
+npx teamix-evo@latest ui update                  # 全量 staging。仅在 `teamix-evo` / `mixed` lineage 产出
+npx teamix-evo@latest ui update button input     # 只 stage 指定组件
+npx teamix-evo@latest biz-ui update              # 变体感知的 biz-ui staging
+npx teamix-evo@latest blocks update              # blocks staging
+```
+
+> `ui upgrade` / `biz-ui upgrade` / `blocks upgrade` 仍可使用（hidden alias），但推荐使用 `update`。
+
+**lineage 分三档**（CLI 只在前两者上产出 staging）：
+
+| lineage         | CLI 会产出 staging？ | AI 开场白                                                                         |
+| --------------- | -------------------- | --------------------------------------------------------------------------------- |
+| `teamix-evo`    | 是                   | 走 staging → [update-component-staging.md](update-component-staging.md) 流程逐件 review |
+| `mixed`         | 是                   | 升级项优先，末了与用户商量 foreign 组件（未登记）去留                              |
+| `shadcn-native` | 否                   | 告诉用户他是 shadcn 原生，建议先 `teamix-evo migrate` 迁移到 teamix-evo          |
+| `custom-only`   | 否                   | 跳过。告诉用户"现有组件不在 manifest 中，升级只针对 teamix-evo 安装资产"           |
+
+**AI 引导决策树**：
+
+1. **先识别 lineage**：`ui update` 的输出会带 `lineage=...`。根据表选开场白。
+2. **路径 A（`teamix-evo` / `mixed`）**：
+   - CLI 生成 staging 后会输出 `staging at .teamix-evo/.upgrade-staging/<dir>` + risk 汇总。复述给用户。
+   - **应用 staging 走 [update-component-staging.md](update-component-staging.md) 流程** — 逐个展示 diff，按 risk 分批让用户确认后才复制 incoming.tsx 到 src（逐文件 hard gate）。
+   - **不要手工复制！**`incoming.tsx` 已是 alias 重写过的、可直接覆盖。但走 [update-component-staging.md](update-component-staging.md) 流程能带 archive 动作 + risk-aware UX。
+3. **路径 B（`shadcn-native`）**：告知用户 "CLI 不会为 shadcn 原生仓生成 staging"，提示他走 `teamix-evo migrate` 迁移到 teamix-evo 后再升级。
+4. **路径 C（用户误走 `--apply`）**：CLI 会拒绝 + 打印 "请走本 skill 升级流程"。重复该提示，引导走路径 A。
+5. **路径 D（foreign 组件）**：staging 中的 `riskLevel: foreign` 是未登记文件（`mixed` lineage）— 不要表达为"要升级"；作为联动信息告诉用户，让他决定是否 `teamix-evo ui add <id>` 收纳、删掉、或保留。
+
+**身份划分清单**：
+
+- **CLI**：检测 lineage / 生成 staging / 算 risk。**从不写 `src/components/{ui,business}`**。
+- **AI（本 skill）**：识别意图、跳起 CLI 命令、复述结果、在路径 A 上继续 [update-component-staging.md](update-component-staging.md) 流程。
+- **[update-component-staging.md](update-component-staging.md)**：读 staging、逐文件 diff 征同意、apply、archive。
+
+**不要**：
+
+- 不要自己在 SKILL.md hub 里复制 staging 文件到 `src` — 那是 [update-component-staging.md](update-component-staging.md) 的职责。
+- 不要听到"升级 ui"就打 `ui add` — `add` 是装进去，`update` 是已装后追上上游。
+- 不要在 `shadcn-native` lineage 强行跳 staging；CLI 跳过是预期行为。
+
+## §4 · 组件源码 promotion（`teamix-evo ui promote-to-biz` — Init 落地计划 §C.3 / §C.4）
+
+**触发**：用户表达"把 ui 组件融进 biz-ui / 把 button 提级成业务组件 / promote ui to business / 把 staging 里的差异融合到 business 层 / 多模式融合 / wrapper + preset 叠加 / 双轨 coexist / 把上游版和自家版同时保留"等关键词；或在 §3 走完 staging 后用户问"能不能直接生成业务包装组件"。
+
+> 这是 §3 的**下游**：§3 只生成 `.upgrade-staging/`，§4 才把条目按 AI 推荐的 `recommendedModes` 真正落地到 `src/components/business/` 并维护 manifest。**条目的 8 模式判定全部由 staging meta 给出**，本 skill 只做分组、确认、转发命令。
+
+**一行命令**：
+
+```bash
+npx teamix-evo@latest ui promote-to-biz                       # 默认融合最新 ui-* staging 中所有可自动模式条目
+npx teamix-evo@latest ui promote-to-biz button card           # 只融合指定 id
+npx teamix-evo@latest ui promote-to-biz --modes Wrapper,Preset # 强制覆盖 staging 推荐模式
+npx teamix-evo@latest ui promote-to-biz --migrate-imports     # Coexist 模式时连带 src/** 改 import 到 legacy-<id>
+npx teamix-evo@latest ui promote-to-biz --keep-original-names # Coexist 模式 export 不前缀化 Legacy
+npx teamix-evo@latest ui promote-to-biz --dry-run             # 计划态：列模式分组 + 文件变更预览，不写盘
+npx teamix-evo@latest ui promote-to-biz --staging-dir <path>  # 指定 staging 目录（不指定则取最新 ui-* 目录）
+```
+
+**8 模式分组语义**：
+
+| Mode           | 终结？ | 产物                                                                             |
+| -------------- | ------ | -------------------------------------------------------------------------------- |
+| `Coexist`      | 是     | `business/legacy-<id>.tsx`（用户版改名 `Legacy<Foo>`）+ `ui/<id>.tsx` 回填上游版 |
+| `Fork`         | 是     | `business/<id>.tsx`（直接搬用户版，无上游对应）                                  |
+| `TokenOnly`    | 是     | **不创建文件**，引导用户改 `tokens/tokens.overrides.css`                         |
+| `ManualReview` | 是     | **不创建文件**，列入待办交用户决策                                               |
+| `Preset`       | 可叠加 | `business/<id>.tsx` import 上游 + `defaultProps`                                 |
+| `Wrapper`      | 可叠加 | `business/<id>.tsx` 包装上游 + 业务 state/effect                                 |
+| `Variant`      | 可叠加 | `business/<id>.tsx` 扩展上游 cva（上游未 export → 触发 ManualReview）            |
+| `Compose`      | 可叠加 | `business/<id>.tsx` 拼装多个上游原子                                             |
+
+> 叠加规则：`Coexist` / `Fork` / `TokenOnly` / `ManualReview` 互斥（终结）；`Preset + Wrapper + Variant + Compose` 任意组合，叠加顺序内 → 外为 `variant > wrapper > preset`。
+
+**AI 引导决策树（5 步闭环）**：
+
+1. **读 staging meta** —— 让 CLI 帮拿（`teamix-evo ui update` 输出 staging 路径），打开 `.teamix-evo/.upgrade-staging/<latest-ui-*>/meta.json` 阅读所有 entries 的 `id` / `recommendedModes` / `confidence` / `reasons` / `featureVector`。
+2. **按主模式分组展示** —— 取每个 entry 的第一个 mode 作为分组键；列表给用户：
+   - `Coexist (3): button, dialog, dropdown-menu` → 双轨并存，会改 import 路径
+   - `Wrapper+Preset (2): card, badge` → 业务包装 + 默认值
+   - `TokenOnly (4): separator, label, ...` → 只需改 tokens.overrides.css
+   - `ManualReview (1): table` → 置信度 < 0.6，需要用户先看 diff
+3. **每组逐一询问** —— 对每组先展示 `current.tsx` ↔ `incoming.tsx` 关键 diff（用户要看才展），再问"是否按推荐模式 promote？yes/no/调整模式"。
+   - 用户改模式时复述新 mode list，再调 `--modes` 参数。
+   - `Coexist` 分组要明确告诉用户：默认**不**重写既有 `import .../ui/<id>` 引用，加 `--migrate-imports` 才统改为 `legacy-<id>`。
+4. **逐组调 promote-to-biz** —— 每组一次命令调用，传该组所有 id；先 `--dry-run` 看 FileChange 四桶（new/modified/deleted/backed-up），用户 OK 后去 dry-run 真写。
+5. **收尾输出未处理 + import skipped 清单** —— 命令结束后复述：
+   - `manualReview: [...]` 让用户人工抉择（看 diff 或拆 family）
+   - `tokenOnly: [...]` 引导走 `tokens audit`
+   - `importRewrite.skipped: [{file, line, reason}]` 列出动态 import / 别名 export / 模板字符串这些 regex 重写不到的位置，让用户人工处理
+   - `failed: [...]`（如果有）逐条说明失败原因
+
+**身份划分清单**：
+
+- **CLI（`ui promote-to-biz`）**：执行备份、写 `business/`、回填 `ui/`、按 spec 重写 `src/**` 静态 import、改 manifest。
+- **AI（本 skill）**：读 meta、分组、展示 diff、征用户同意、转命令；**不**自己写文件、**不**自己改 import。
+- **[update-component-staging.md](update-component-staging.md)**：管 §3 staging → src 的 1:1 替换；**不**做模式分流，本场景才做。
+
+**不要**：
+
+- 不要绕过 staging 直接调 `promote-to-biz`：CLI 拒收（命令依赖 staging meta）。
+- 不要把 `Coexist` 当 `Replace` 用：默认双轨，旧 import **不**自动迁移，要 `--migrate-imports`。
+- 不要忽略 `importRewrite.skipped`：那批位置 CLI 故意放弃，必须告诉用户人工处理。
+- 不要建议用户手改 `manifest.json`：promoted 登记由 CLI 写，污染了走 `restore`。
+
+## §5 · AGENTS.md 自动刷新
+
+AGENTS.md 中的 managed 区段（`<!-- teamix-evo:managed:start id="teamix-evo-skills" -->`）由 CLI 自动维护，用户无需手动操作。
+
+**自动刷新时机**：
+
+- `skills update` — 更新 skill 后立即用当前 variant + 所有 project-scope skill ids 重生 managed 区段
+- `switch` — 切 variant 后用新 variant + 当前 project-scope skill ids 重生 managed 区段
+
+刷新使用 `mode: 'merge-managed'`，只替换 managed 区段内容，用户在 managed 区段外的自定义笔记不受影响。
+
+**异常处理**：AGENTS.md 刷新是非关键步骤，失败只输出 warn 日志，不影响主流程返回值。
+
+**手动触发**：如果 AGENTS.md 缺失或 managed 区段被意外删除，跑 `teamix-evo init`（幂等，会跳过已完成步骤，只重生缺失部分）。
+
+## §6 · lint 规则包版本检测
+
+`@teamix-evo/eslint-config` 和 `@teamix-evo/stylelint-config` 是 npm devDependencies，由用户的包管理器管理版本。
+
+**升级方式**：
+
+```bash
+pnpm update @teamix-evo/eslint-config @teamix-evo/stylelint-config
+```
+
+**`teamix-evo update` 报告**会展示：
+
+- 当前已安装的 lint 包版本
+- 升级提示命令
+
+**config 文件（`eslint.config.js` / `stylelint.config.cjs`）是用户所有**，CLI 不会在 update 流程中覆盖或修改。如果 lint 包大版本升级导致 config 格式变化，由 AI skill 引导用户手动迁移。
+
+## §7 · config.json / manifest.json schema 迁移
+
+**config.json**（`.teamix-evo/config.json`）已建立 read-time migration 模式：
+
+- `ProjectConfigSchema` 使用 `z.discriminatedUnion('schemaVersion', [V1, V2]).transform()` 实现 v1→v2 自动迁移
+- CLI 每次读取 config 时自动升级，写回时用最新 schema version
+- 用户无感，无需手动操作
+
+**manifest.json**（`.teamix-evo/manifest.json`）当前 v1，暂无 migration 需求。未来版本变更时沿用 config.json 的 Zod discriminatedUnion + transform 模式。
+
+**开发者参考**：新增 schema 版本时：
+
+1. 新建 `ProjectConfigV3Schema`（或 `InstalledManifestV2Schema`）
+2. 在 discriminatedUnion 里加入新版本
+3. transform 里加 v(N-1)→vN 迁移链

package/src/teamix-evo-design-opentrek/brand.md

@@ -1,154 +0,0 @@
-# Brand — OpenTrek 视觉调性 + 文案语气 + 正反例
-
-> OpenTrek 服务于运维与平台管理场景。本文是品牌定标尺：所有视觉、文案决策不应越过这里定义的边界。
-
----
-
-## 1. 视觉风格五维
-
-| 维度         | 定位     | 具体表现                                                                           | 对立面（禁止）       |
-| ------------ | -------- | ---------------------------------------------------------------------------------- | -------------------- |
-| **色彩情绪** | 沉稳专业 | 品牌主色 `#0055EE` (hsl(218.6 100% 46.7%)) + 高对比信息层级                        | 花哨多彩、渐变堆叠   |
-| **信息密度** | 高效紧凑 | 单屏承载核心操作，减少翻页                                                         | 大面积留白、装饰占位 |
-| **视觉层次** | 克制有序 | 间距、字重、色彩建立 3 级层级                                                      | 多重强调、全部高亮   |
-| **交互反馈** | 即时确定 | 操作后 200ms 内明确反馈                                                            | 模糊状态、静默       |
-| **圆角风格** | 中圆角   | OpenTrek v4.1：`rounded-md` (8px) / `rounded-lg` (12px)；legacy `rounded-sm` (4px) | 全直角、超大圆角     |
-
----
-
-## 2. 情感矩阵
-
-```
-可信赖 ████████████████████ 95%   ← 不可让步
-高效率 ███████████████████░ 90%   ← 不可让步
-专业感 ██████████████████░░ 85%
-现代感 ████████████████░░░░ 75%
-亲和力 ███████████░░░░░░░░░ 55%   ← 次要，不刻意追求
-趣味性 ████░░░░░░░░░░░░░░░░ 20%   ← 极度克制
-```
-
-> "可信赖" 与 "高效率" 是不能让步的两根支柱。"亲和力" 与 "趣味性" 刻意低，避免在严肃场景产生轻浮感。
-
----
-
-## 3. 品牌个性
-
-| 特征     | 描述                           | 设计映射                       |
-| -------- | ------------------------------ | ------------------------------ |
-| **稳定** | 云基础设施核心诉求是"不出问题" | 一致的布局骨架、可预期的交互   |
-| **透明** | 用户需要知道系统正在做什么     | 状态指示器、进度反馈、操作确认 |
-| **掌控** | 管理员需要"全局在握"的感觉     | 数据概览、筛选能力、批量操作   |
-| **专注** | 运维操作容错率低               | 清晰的信息层级、防误操作确认   |
-
-### Moodboard 参考
-
-- 开发者控制台：Vercel、Linear、Datadog、PlanetScale
-- 现代企业 SaaS：Notion Admin、Stripe Dashboard
-- 工程化文档：Tailwind / shadcn / Radix UI Docs
-
----
-
-## 4. 文案语气总体风格
-
-> **精确 > 友好。简短 > 完整。可执行 > 可理解。**
->
-> 不卖萌、不感叹、不"恭喜你"。所有文案以**"是否帮助用户做下一步决策"**为唯一评价标准。
-
-### 4.1 语气矩阵
-
-| 场景        | 语气             | ✅ 正例                            | ❌ 反例                |
-| ----------- | ---------------- | ---------------------------------- | ---------------------- |
-| 标题 / 导航 | 名词、定语短句   | "实例列表" / "安全组规则"          | "你的实例们"           |
-| 引导说明    | 简洁、可执行     | "选择资源后，可执行批量操作"       | "快来选个资源试试吧～" |
-| 主操作按钮  | 动宾结构、≤ 5 字 | "创建实例" / "释放资源"            | "去创建一个新的实例"   |
-| 危险按钮    | 名词 + 动作      | "永久删除" / "立即停机"            | "确认" / "OK"          |
-| 错误提示    | 具体原因 + 建议  | "实例正在运行中，请先停止后再删除" | "操作失败，请重试"     |
-| 成功反馈    | 已完成的事实     | "已释放 3 个实例"                  | "操作成功！🎉"         |
-| 空状态      | 解释 + 入口      | "暂无实例。创建第一个实例以开始"   | "这里空空如也～"       |
-| 加载提示    | 进行时           | "正在加载实例…"                    | "马上就好~"            |
-
-### 4.2 写作规范
-
-1. **动词在前** — 按钮以动词开头：「创建项目」非「项目创建」
-2. **避免歧义** — 「删除」与「释放」严格区分（删除不可恢复 / 释放进入回收站）
-3. **不省略主语** — 错误信息指出"什么"出错：「实例 i-xxx 启动失败」非「启动失败」
-4. **量词精确** — "已删除 3 项" 而非 "已删除几项"
-5. **主动语态** — "系统已保存配置" 而非 "配置已被系统保存"
-
-### 4.3 标点与排版
-
-- 按钮文字 / 表头标签：**不加**句号
-- 描述、提示、说明：**完整句子** + 句号
-- 列表项格式统一（全加句号 或 全不加）
-- 中英文 / 中数字之间加 1 空格：`已选 3 项 / 共 128 项`
-- 数字使用半角；区间用 `~`（中文）/ `–`（英文）
-- 时间格式统一：`2026-05-14 10:23:45`（ISO-like）
-
----
-
-## 5. 危险操作专用文案（硬约束）
-
-破坏性操作（删除、释放、强制重启）必须满足：
-
-| 元素                 | 规则             | 示例                                                                      |
-| -------------------- | ---------------- | ------------------------------------------------------------------------- |
-| **AlertDialog 标题** | 陈述句而非疑问句 | ✅「永久删除实例 i-xxx」 ❌「确定要删除吗？」                             |
-| **正文**             | 列出具体后果     | ✅「该实例的数据盘将被释放且不可恢复。关联的快照（共 2 个）将一并删除。」 |
-| **确认按钮**         | 重复动作动词     | ✅「永久删除」 ❌「确认」                                                 |
-| **取消按钮**         | 用「取消」       | ❌「不」/「再想想」                                                       |
-
----
-
-## 6. AI 场景文案规则
-
-AI 助手在生成回复时遵循：
-
-- **不使用**第一人称「我」（避免拟人化）→ 用「OpenTrek AI」或省略主语
-- 操作建议必须给出**确定性** + **量化影响**：「建议将实例规格升级至 ecs.g7.large（预计成本 +¥120/月）」
-- 不确定时**明确表达**：「此问题可能由 A、B 两个原因引起，建议先排查 A」
-- 拒绝执行不可逆操作时给出明确原因 + 替代路径
-
----
-
-## 7. 视觉正反例对照
-
-### 7.1 布局
-
-| ✅ 正例                                                          | ❌ 反例                                  |
-| ---------------------------------------------------------------- | ---------------------------------------- |
-| ListPage 搜索/筛选固定顶部，表格自适应高度，分页固定底部         | 同一页面同时使用左右两套 Sidebar         |
-| 表单左对齐标签，字段按"必填 → 可选"排序，主操作右下角            | 主操作按钮放在一屏之外（需滚动才能看到） |
-| 详情页 Tab 顺序：基本信息 → 监控 → 配置 → 操作日志（按使用频率） | 表单字段按字母顺序排序（忽略业务优先级） |
-
-### 7.2 色彩
-
-| ✅ 正确                                                              | ❌ 错误                              |
-| -------------------------------------------------------------------- | ------------------------------------ |
-| 主色仅用于主行动点（CTA 按钮、当前选中项、品牌标识）                 | 用主色表示"错误"状态                 |
-| 状态色：`destructive` = 错误/删除；绿/黄按业务语义；图表用 `chart-*` | 把 `destructive` 红色用在 Tab 选中态 |
-| 暗色模式直接切换 CSS 变量，不重写组件                                | 同一页面 4 种以上"重要"按钮颜色      |
-
-### 7.3 动效
-
-| ✅ 正确                                                  | ❌ 错误                                                |
-| -------------------------------------------------------- | ------------------------------------------------------ |
-| Hover 色彩切换 `transition-colors duration-150 ease-out` | 给 width / height / margin 加过渡（性能差 + 布局抖动） |
-| 弹窗入场 `zoom-in-95 + fade-in` 300ms                    | 整页加载用复杂 Loader + 进度条（用 Skeleton 即可）     |
-| Skeleton 占位 → 数据到达后 `fade-in`                     | 微交互动效超过 200ms（hover 不应让用户等待）           |
-
-### 7.4 圆角与阴影对应表
-
-> **完整对应表见 [foundations.md §6.3 圆角 × 阴影对应表](./foundations.md#63-圆角--阴影对应表)** — 圆角与阴影必须同档对应,这是 foundations 层的语义归一规则,brand 层不再重复。
-
----
-
-## 8. 品牌自检
-
-- [ ] 文案动词在前，按钮 ≤ 5 字
-- [ ] 错误提示含主语 + 原因 + 建议
-- [ ] 危险操作 AlertDialog 标题用陈述句、按钮用动作动词
-- [ ] 不出现 emoji 表情、感叹号过多、拟人化主语「我」
-- [ ] 主色仅用于 CTA 与当前选中态，不滥用
-- [ ] 圆角阴影同档对应（rounded-md ↔ shadow-sm ↔ rounded-lg ↔ shadow-md/xl）
-- [ ] 动效仅 transition-colors / opacity / transform，禁 width/height/margin
-- [ ] 中英文之间有空格，时间格式统一 ISO-like