@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/docs/refactoring/smell-refactoring-matrix.md

@@ -0,0 +1,41 @@
+# 24 种代码坏味道与重构手法速查矩阵
+
+本矩阵基于已归一化的第 3 章坏味道关系。候选手法不是机械映射；实际选择还必须检查成因、前置条件、风险、行为契约和差异预算。
+
+| 坏味道 | 主要/辅助候选 | 选择提示 |
+| --- | --- | --- |
+| `SMELL-MYSTERIOUS-NAME`<br>神秘命名（Mysterious Name） | `RF-CHANGE-FUNCTION-DECLARATION`<br>`RF-RENAME-VARIABLE`<br>`RF-RENAME-FIELD` | 先确认“神秘命名”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-DUPLICATED-CODE`<br>重复代码（Duplicated Code） | `RF-EXTRACT-FUNCTION`<br>`RF-SLIDE-STATEMENTS`<br>`RF-PULL-UP-METHOD` | 先确认“重复代码”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-LONG-FUNCTION`<br>过长函数（Long Function） | `RF-EXTRACT-FUNCTION`<br>`RF-REPLACE-TEMP-WITH-QUERY`<br>`RF-INTRODUCE-PARAMETER-OBJECT`<br>`RF-PRESERVE-WHOLE-OBJECT`<br>`RF-REPLACE-FUNCTION-WITH-COMMAND`<br>`RF-DECOMPOSE-CONDITIONAL`<br>`RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`<br>`RF-SPLIT-LOOP` | 先确认“过长函数”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-LONG-PARAMETER-LIST`<br>过长参数列表（Long Parameter List） | `RF-REPLACE-PARAMETER-WITH-QUERY`<br>`RF-PRESERVE-WHOLE-OBJECT`<br>`RF-INTRODUCE-PARAMETER-OBJECT`<br>`RF-REMOVE-FLAG-ARGUMENT`<br>`RF-COMBINE-FUNCTIONS-INTO-CLASS` | 先确认“过长参数列表”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-GLOBAL-DATA`<br>全局数据（Global Data） | `RF-ENCAPSULATE-VARIABLE` | 先确认“全局数据”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-MUTABLE-DATA`<br>可变数据（Mutable Data） | `RF-ENCAPSULATE-VARIABLE`<br>`RF-SPLIT-VARIABLE`<br>`RF-SLIDE-STATEMENTS`<br>`RF-EXTRACT-FUNCTION`<br>`RF-SEPARATE-QUERY-FROM-MODIFIER`<br>`RF-REMOVE-SETTING-METHOD`<br>`RF-REPLACE-DERIVED-VARIABLE-WITH-QUERY`<br>`RF-COMBINE-FUNCTIONS-INTO-CLASS`<br>`RF-COMBINE-FUNCTIONS-INTO-TRANSFORM`<br>`RF-CHANGE-REFERENCE-TO-VALUE` | 先确认“可变数据”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-DIVERGENT-CHANGE`<br>发散式变化（Divergent Change） | `RF-SPLIT-PHASE`<br>`RF-MOVE-FUNCTION`<br>`RF-EXTRACT-FUNCTION`<br>`RF-EXTRACT-CLASS` | 先确认“发散式变化”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-SHOTGUN-SURGERY`<br>霰弹式修改（Shotgun Surgery） | `RF-MOVE-FUNCTION`<br>`RF-MOVE-FIELD`<br>`RF-COMBINE-FUNCTIONS-INTO-CLASS`<br>`RF-COMBINE-FUNCTIONS-INTO-TRANSFORM`<br>`RF-SPLIT-PHASE`<br>`RF-INLINE-FUNCTION`<br>`RF-INLINE-CLASS` | 先确认“霰弹式修改”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-FEATURE-ENVY`<br>依恋情结（Feature Envy） | `RF-MOVE-FUNCTION`<br>`RF-EXTRACT-FUNCTION` | 先确认“依恋情结”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-DATA-CLUMPS`<br>数据泥团（Data Clumps） | `RF-EXTRACT-CLASS`<br>`RF-INTRODUCE-PARAMETER-OBJECT`<br>`RF-PRESERVE-WHOLE-OBJECT` | 先确认“数据泥团”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-PRIMITIVE-OBSESSION`<br>基本类型偏执（Primitive Obsession） | `RF-REPLACE-PRIMITIVE-WITH-OBJECT`<br>`RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES`<br>`RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`<br>`RF-EXTRACT-CLASS`<br>`RF-INTRODUCE-PARAMETER-OBJECT` | 先确认“基本类型偏执”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-REPEATED-SWITCHES`<br>重复的 switch（Repeated Switches） | `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM` | 先确认“重复的 switch”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-LOOPS`<br>循环语句（Loops） | `RF-REPLACE-LOOP-WITH-PIPELINE` | 先确认“循环语句”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-LAZY-ELEMENT`<br>冗赘的元素（Lazy Element） | `RF-INLINE-FUNCTION`<br>`RF-INLINE-CLASS`<br>`RF-COLLAPSE-HIERARCHY` | 先确认“冗赘的元素”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-SPECULATIVE-GENERALITY`<br>夸夸其谈通用性（Speculative Generality） | `RF-COLLAPSE-HIERARCHY`<br>`RF-INLINE-FUNCTION`<br>`RF-INLINE-CLASS`<br>`RF-CHANGE-FUNCTION-DECLARATION`<br>`RF-REMOVE-DEAD-CODE` | 先确认“夸夸其谈通用性”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-TEMPORARY-FIELD`<br>临时字段（Temporary Field） | `RF-EXTRACT-CLASS`<br>`RF-MOVE-FUNCTION`<br>`RF-INTRODUCE-SPECIAL-CASE` | 先确认“临时字段”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-MESSAGE-CHAINS`<br>过长的消息链（Message Chains） | `RF-HIDE-DELEGATE`<br>`RF-EXTRACT-FUNCTION`<br>`RF-MOVE-FUNCTION` | 先确认“过长的消息链”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-MIDDLE-MAN`<br>中间人（Middle Man） | `RF-REMOVE-MIDDLE-MAN`<br>`RF-INLINE-FUNCTION`<br>`RF-REPLACE-SUPERCLASS-WITH-DELEGATE`<br>`RF-REPLACE-SUBCLASS-WITH-DELEGATE` | 先确认“中间人”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-INSIDER-TRADING`<br>内幕交易（Insider Trading） | `RF-MOVE-FUNCTION`<br>`RF-MOVE-FIELD`<br>`RF-HIDE-DELEGATE`<br>`RF-REPLACE-SUBCLASS-WITH-DELEGATE`<br>`RF-REPLACE-SUPERCLASS-WITH-DELEGATE` | 先确认“内幕交易”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-LARGE-CLASS`<br>过大的类（Large Class） | `RF-EXTRACT-CLASS`<br>`RF-EXTRACT-SUPERCLASS`<br>`RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES` | 先确认“过大的类”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-ALTERNATIVE-CLASSES-DIFFERENT-INTERFACES`<br>异曲同工的类（Alternative Classes with Different Interfaces） | `RF-CHANGE-FUNCTION-DECLARATION`<br>`RF-MOVE-FUNCTION`<br>`RF-EXTRACT-SUPERCLASS` | 先确认“异曲同工的类”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-DATA-CLASS`<br>纯数据类（Data Class） | `RF-ENCAPSULATE-RECORD`<br>`RF-REMOVE-SETTING-METHOD`<br>`RF-MOVE-FUNCTION`<br>`RF-EXTRACT-FUNCTION`<br>`RF-SPLIT-PHASE` | 先确认“纯数据类”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-REFUSED-BEQUEST`<br>被拒绝的遗赠（Refused Bequest） | `RF-PUSH-DOWN-METHOD`<br>`RF-PUSH-DOWN-FIELD`<br>`RF-REPLACE-SUBCLASS-WITH-DELEGATE`<br>`RF-REPLACE-SUPERCLASS-WITH-DELEGATE` | 先确认“被拒绝的遗赠”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+| `SMELL-COMMENTS`<br>注释（Comments） | `RF-EXTRACT-FUNCTION`<br>`RF-CHANGE-FUNCTION-DECLARATION`<br>`RF-INTRODUCE-ASSERTION` | 先确认“注释”的真实成因，再从符合当前数据所有权、行为契约和前置条件的手法中选择最小安全变化。 |
+
+## 误判保护
+
+- 行数本身不能证明“过长函数”或“过大的类”；
+- 单个 `switch` 不能证明“重复的 switch”；
+- `filter().map().reduce()` 之类数据管道不自动等同于“过长的消息链”；
+- 注释本身不是缺陷，不能仅因 `Comments` 是坏味道类别就删除注释；
+- 不可变 DTO/中转数据可以合理保持为数据型结构；
+- React/Vue 声明式组合不自动等同于“中间人”或“过长的消息链”。
+
+详细诊断规则见 [`fec-code-smells`](../../localized/zh-CN/skills/fec-code-smells/references/detection-guide.md)。

package/docs/review-and-diagram-workflows.md

@@ -0,0 +1,39 @@
+# Review scope and technical diagram delivery
+
+These conventions apply to the installed capabilities across runtimes. Use natural-language requests; review modes are not installer CLI flags.
+
+## Review scope
+
+`fec-code-reviewer`, `fec-typescript-reviewer`, `fec-security-reviewer`, `fec-code-review`, `fec-security-review`, and `/fec-review` follow the same scope rules:
+
+| Request | Scope | Report conclusion |
+| --- | --- | --- |
+| No scope, including bare `/fec-review` | Entire project, even when Git changes exist | Risk assessment |
+| A file or directory | All existing code in that scope, including unchanged code | Scope risk assessment |
+| Explicit recent changes, PR, or commit | Requested diff and necessary context | Merge recommendation |
+
+Full and targeted reviews do not require a Git diff. An explicit incremental review with no changes reports that fact without expanding its scope. Reviewers keep their frontend, TypeScript, or security specialty; this does not certify a backend security audit.
+
+For project reviews, inventory owned frontend code, related tests, configuration, and dependency declarations, then review modules in batches. Exclude dependencies, generated files, build outputs, caches, and third-party code by default. Reports record mode, target scope, reviewed scope, exclusions, uncovered modules, and validation results. Mark incomplete reviews as partial and merge findings with the same root cause. Reading callers or running static checks does not count as manually reviewing those files. Report only unless fixes are explicitly requested.
+
+Examples: “Review the project”; “Review all code in `src/features/`”; “Review `src/components/Button.tsx`”; “Review only the recent changes.” Automatic review after edits must explicitly pass the current change scope.
+
+## Technical diagrams
+
+Use `cc-technical-diagrams` for sequence diagrams and workflows with local Mermaid where available; use `cc-drawio-studio` for editable architecture diagrams. Use the JSON/HTML renderer when these tools are unavailable. Keep technical relationships and labels in editable source rather than relying on raster image generation for exact structure.
+
+The Mermaid adapter uses an installed CLI only; it does not download packages. PNG export requires a local Chromium browser, with `FEC_BROWSER_PATH` available for an explicit executable. Missing tools must be reported rather than claimed as successful exports.
+
+For the JSON/HTML route, render the source, export PNG with a browser-measured manifest at the same scale, run QA, and inspect the final image:
+
+```bash
+node skills/cc-technical-diagrams/scripts/tech-diagram-render.mjs --input skills/cc-technical-diagrams/assets/quality-examples/workflow.json --type workflow --output workflow.html --manifest workflow.layout.json
+node skills/cc-technical-diagrams/scripts/export-diagram.mjs --input workflow.html --format png --output workflow.png --theme light --scale 2 --manifest workflow.layout.json --output-manifest workflow.actual.json
+node skills/cc-technical-diagrams/scripts/png-qa.mjs --png workflow.png --manifest workflow.actual.json --format json
+```
+
+Preserve complete Unicode labels, explicit geometry, edge direction, sequence order, and self calls. Keep exported SVG styles self-contained. Geometry QA and browser measurement support visual inspection; neither proves semantic correctness nor completes a human visual review. Missing measurements or partial coverage must be disclosed. Repair the editable source for at most two automatic rounds, then report unresolved defects.
+
+Deliver editable source, the requested export, and QA/coverage results. See [reproducible examples](../skills/cc-technical-diagrams/assets/quality-examples/README.md), [diagram workflows](../skills/cc-technical-diagrams/references/diagram-workflows.md), and [PNG QA](../skills/cc-technical-diagrams/references/png-qa-autofix.md).
+
+[简体中文](zh-CN/review-and-diagram-workflows.md)

package/docs/runtimes/antigravity.md

@@ -1,10 +1,18 @@
-# frontend-craft: antigravity
-
-See root README **Universal Install** and run:
+# frontend-craft: Antigravity
 
 ```bash
-npx @bovinphang/frontend-craft install antigravity
+fec setup antigravity
+fec setup antigravity --global
+fec doctor antigravity --local
+fec doctor antigravity --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install antigravity --local` or `--global`.
+
+Project skills retain backward-compatible `.agent/skills`; the current IDE/2.0 user base is `~/.gemini/config`, so skills go in `~/.gemini/config/skills`. For Antigravity CLI set `ANTIGRAVITY_CONFIG_DIR` to `~/.gemini/antigravity-cli` before global installation. The override selects one product scope; this adapter does not install plugins or hooks. After upgrading an old default global install, run `fec setup antigravity --global`; the old `~/.gemini/antigravity` files are preserved.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://antigravity.google/docs/skills) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/augment.md

@@ -1,10 +1,18 @@
-# frontend-craft: augment
-
-See root README **Universal Install** and run:
+# frontend-craft: Augment
 
 ```bash
-npx @bovinphang/frontend-craft install augment
+fec setup augment
+fec setup augment --global
+fec doctor augment --local
+fec doctor augment --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install augment --local` or `--global`.
+
+Skills use `.augment/skills` or `~/.augment/skills` (`AUGMENT_CONFIG_DIR` override). The adapter currently installs skills only. Native agents, rules, hooks and MCP support in Augment do not imply that this adapter installs those capabilities.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://docs.augmentcode.com/cli/skills) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/claude.md

@@ -5,16 +5,18 @@ Recommended path for most Claude Code users: install through **Claude Code Marke
 Use the CLI only when you need cross-runtime installation, offline/scripted file copies, or a non-Marketplace environment:
 
 ```bash
-npx @bovinphang/frontend-craft@latest install --local claude
+npx @bovinphang/frontend-craft@latest runtime install --local claude
 # or
-npx @bovinphang/frontend-craft@latest install --global claude
+npx @bovinphang/frontend-craft@latest runtime install --global claude
 ```
 
 > **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
 
 Choose one active source of truth for the same Claude scope: Marketplace/native plugin, CLI install, or `--plugin-dir`. They can technically coexist, but running multiple complete copies in the same Claude session can duplicate commands, skills, agents, and hooks.
 
-The CLI enforces this for Marketplace installs: if Claude Code Marketplace already manages `frontend-craft`, `frontend-craft install/update claude` stops and tells you to update through Marketplace instead. `--force` does not override a Marketplace install.
+In CLI 3.0, top-level `fec update` upgrades a supported npm/pnpm global CLI and then refreshes its managed resources. Use the `runtime` group below for resource-only operations; `runtime update` uses the running package contents without fetching a newer package. Top-level `fec uninstall` removes the CLI itself; `fec runtime uninstall claude --local` (or `--global`) removes the managed Claude resources. See the [3.0 migration table](../../README.md#update-and-remove).
+
+The CLI enforces this for Marketplace installs: if Claude Code Marketplace already manages `frontend-craft`, `frontend-craft runtime install/update claude` stops and tells you to update through Marketplace instead. `--force` does not override a Marketplace install.
 
 ---
 
@@ -63,9 +65,17 @@ After initialization, customize for your project:
 ### Step 3: Start using
 
 ```bash
-# Code review (outputs to reports/code-review-*.md)
+# Full project review by default (outputs to reports/code-review-*.md)
 /fec-review
 
+# Explicit change review
+/fec-review review recent changes
+
+# Specify a file, directory or entire project (natural language, not CLI flags)
+/fec-review review src/components/Button.tsx
+/fec-review review src/features/
+/fec-review review the entire project
+
 # Create page/feature/component by convention
 /fec-scaffold page UserDetail
 /fec-scaffold component DataTable
@@ -110,13 +120,13 @@ Clone the repo and load via `--plugin-dir` (no install, suitable for development
 ```bash
 git clone https://github.com/bovinphang/frontend-craft.git
 cd frontend-craft
-npm install
-npm run build
+pnpm install --frozen-lockfile
+pnpm run build
 cd ..
 claude --plugin-dir ./frontend-craft
 ```
 
-When using `--plugin-dir` for development, run `npm run build` after changing hook or CLI sources because Claude executes the compiled files under `dist/`. Disable or avoid a Marketplace install of the same plugin in that session so you know which copy is running.
+When using `--plugin-dir` for development, run `pnpm run build` after changing hook or CLI sources because Claude executes the compiled files under `dist/`. Disable or avoid a Marketplace install of the same plugin in that session so you know which copy is running.
 
 ### Option 4: Git Submodule (project-level sharing)
 
@@ -165,13 +175,19 @@ For Git submodule installs:
 git submodule update --remote .claude/plugins/frontend-craft
 ```
 
-**CLI installs:** re-run `npx @bovinphang/frontend-craft@latest update claude --local` or `... --global` for the same scope, and read [CHANGELOG.md](../../CHANGELOG.md) for release notes. If Claude Code Marketplace is already installed, the CLI refuses Claude install/update and prints the Marketplace update path. If the opposite CLI scope is already installed, interactive terminals ask whether to keep that source updated or uninstall it before switching; non-interactive terminals print the exact commands to run.
+**CLI installs:** re-run `npx @bovinphang/frontend-craft@latest runtime update claude --local` or `... --global` for the same scope, and read [CHANGELOG.md](../../CHANGELOG.md) for release notes. If Claude Code Marketplace is already installed, the CLI refuses Claude install/update and prints the Marketplace update path. If the opposite CLI scope is already installed, interactive terminals ask whether to keep that source updated or uninstall it before switching; non-interactive terminals print the exact commands to run.
 
 ```bash
-npx @bovinphang/frontend-craft@latest update claude --global
-npx @bovinphang/frontend-craft@latest update claude --local
+npx @bovinphang/frontend-craft@latest runtime update claude --global
+npx @bovinphang/frontend-craft@latest runtime update claude --local
 ```
 
 ---
 
 **Other languages:** [简体中文](claude.zh-CN.md)
+
+## CLI compatibility update
+
+CLI hooks are merged into `settings.json`, preserving unrelated settings. Malformed JSON stops installation. Native Marketplace plugins continue to use `hooks/hooks.json`. See [compatibility and upgrade notes](compatibility.md).
+
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/claude.zh-CN.md

@@ -5,16 +5,18 @@
 仅当你需要跨运行时安装、离线/脚本化复制文件，或处在非 Marketplace 环境时，再使用 CLI：
 
 ```bash
-npx @bovinphang/frontend-craft@latest install --local claude
+npx @bovinphang/frontend-craft@latest runtime install --local claude
 # 或
-npx @bovinphang/frontend-craft@latest install --global claude
+npx @bovinphang/frontend-craft@latest runtime install --global claude
 ```
 
 > **非交互场景：** 请加上 `--local` 或 `--global`，避免询问安装位置。交互与脚本行为说明见根目录 README **通用安装**。
 
 同一个 Claude 作用域请只选择一个激活来源：Marketplace/原生插件、CLI 安装或 `--plugin-dir`。它们技术上可以共存，但不推荐在同一个 Claude 会话里同时启用多份完整插件，否则 commands、skills、agents 与 hooks 可能重复。
 
-CLI 会对 Marketplace 安装执行单一来源保护：如果已经由 Claude Code Marketplace 管理 `frontend-craft`，`frontend-craft install/update claude` 会停止，并提示改用 Marketplace 更新。`--force` 不会覆盖 Marketplace 安装。
+CLI 3.0 的顶层 `fec update` 会升级受支持的 npm/pnpm 全局 CLI，再刷新其托管资源。仅操作资源请使用下述 `runtime` 分组；`runtime update` 只使用当前包内容，不获取新版包。顶层 `fec uninstall` 卸载 CLI 本体；`fec runtime uninstall claude --local`（或 `--global`）移除托管的 Claude 资源。迁移表见 [README](../../README.zh-CN.md)。
+
+CLI 会对 Marketplace 安装执行单一来源保护：如果已经由 Claude Code Marketplace 管理 `frontend-craft`，`frontend-craft runtime install/update claude` 会停止，并提示改用 Marketplace 更新。`--force` 不会覆盖 Marketplace 安装。
 
 ---
 
@@ -61,9 +63,17 @@ Marketplace 条目会从已发布的 npm 包解析插件；npm 包中包含 Clau
 ### 第三步：开始使用
 
 ```bash
-# 代码评审（输出到 reports/code-review-*.md）
+# 默认全项目审核（输出到 reports/code-review-*.md）
 /fec-review
 
+# 明确增量审核
+/fec-review 审核最近改动
+
+# 指定文件、目录或全项目（自然语言范围，不是 CLI 参数）
+/fec-review 审核 src/components/Button.tsx
+/fec-review 审核 src/features/
+/fec-review 审核整个项目
+
 # 按规范创建页面/功能/组件
 /fec-scaffold page UserDetail
 /fec-scaffold component DataTable
@@ -108,13 +118,13 @@ Marketplace 条目会从已发布的 npm 包解析插件；npm 包中包含 Clau
 ```bash
 git clone https://github.com/bovinphang/frontend-craft.git
 cd frontend-craft
-npm install
-npm run build
+pnpm install --frozen-lockfile
+pnpm run build
 cd ..
 claude --plugin-dir ./frontend-craft
 ```
 
-使用 `--plugin-dir` 做开发调试时，修改 hooks 或 CLI 源码后需要重新执行 `npm run build`，因为 Claude 会运行 `dist/` 下的已编译文件。请避免在同一会话里同时启用 Marketplace 版本，这样才能确定当前运行的是哪一份代码。
+使用 `--plugin-dir` 做开发调试时，修改 hooks 或 CLI 源码后需要重新执行 `pnpm run build`，因为 Claude 会运行 `dist/` 下的已编译文件。请避免在同一会话里同时启用 Marketplace 版本，这样才能确定当前运行的是哪一份代码。
 
 ### 选项 4：Git Submodule（项目内共享）
 
@@ -163,13 +173,19 @@ claude --plugin-dir .claude/plugins/frontend-craft
 git submodule update --remote .claude/plugins/frontend-craft
 ```
 
-**CLI 安装：** 对同一作用域执行 `npx @bovinphang/frontend-craft@latest update claude --local` 或 `... --global`，版本说明见 [CHANGELOG.zh-CN.md](../../CHANGELOG.zh-CN.md) 或 [CHANGELOG.md](../../CHANGELOG.md)。如果已经检测到 Claude Code Marketplace 安装，CLI 会拒绝 Claude install/update，并提示通过 Marketplace 更新。如果另一个 CLI 作用域已安装，交互式终端会询问是保持该来源并更新，还是卸载后切换；非交互终端会打印可执行命令。
+**CLI 安装：** 对同一作用域执行 `npx @bovinphang/frontend-craft@latest runtime update claude --local` 或 `... --global`，版本说明见 [CHANGELOG.zh-CN.md](../../CHANGELOG.zh-CN.md) 或 [CHANGELOG.md](../../CHANGELOG.md)。如果已经检测到 Claude Code Marketplace 安装，CLI 会拒绝 Claude install/update，并提示通过 Marketplace 更新。如果另一个 CLI 作用域已安装，交互式终端会询问是保持该来源并更新，还是卸载后切换；非交互终端会打印可执行命令。
 
 ```bash
-npx @bovinphang/frontend-craft@latest update claude --global
-npx @bovinphang/frontend-craft@latest update claude --local
+npx @bovinphang/frontend-craft@latest runtime update claude --global
+npx @bovinphang/frontend-craft@latest runtime update claude --local
 ```
 
 ---
 
 **English:** [claude.md](claude.md)
+
+## CLI 兼容性更新
+
+CLI 安装会将 hooks 合并到 `settings.json`，保留其他用户配置；无效 JSON 会阻止安装。原生 Marketplace 插件继续使用 `hooks/hooks.json`。参见[兼容性与升级说明](compatibility.md)。
+
+审核默认覆盖全项目；指定文件或目录时审核全部现有代码，仅明确要求改动 / PR / 提交时增量审核。技术图使用结构化源文件，PNG 导出需本地浏览器并报告 QA 覆盖情况。详见[审核范围与技术图交付](../zh-CN/review-and-diagram-workflows.md)。

package/docs/runtimes/cline.md

@@ -1,10 +1,18 @@
-# frontend-craft: cline
-
-See root README **Universal Install** and run:
+# frontend-craft: Cline
 
 ```bash
-npx @bovinphang/frontend-craft install cline
+fec setup cline
+fec setup cline --global
+fec doctor cline --local
+fec doctor cline --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install cline --local` or `--global`.
+
+Project rules: `.clinerules/frontend-craft.md`, preserving other files in the directory. An existing legacy `.clinerules` file is backed up as `.clinerules.frontend-craft-backup` and copied into `.clinerules/legacy.md` before installing the new bundle. An existing backup stops migration to avoid overwriting it. Global rules: `~/Documents/Cline/Rules/frontend-craft.md`. Set `CLINE_CONFIG_DIR` to the parent of your actual `Rules` directory when Documents is redirected or Cline uses a different location. Manifest-tracked old default `~/.cline` installs are copied to the new location on install/update; originals and user edits are preserved.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://docs.cline.bot/customization/cline-rules) 路 [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/codebuddy.md

@@ -1,10 +1,18 @@
-# frontend-craft: codebuddy
-
-See root README **Universal Install** and run:
+# frontend-craft: CodeBuddy
 
 ```bash
-npx @bovinphang/frontend-craft install codebuddy
+fec setup codebuddy
+fec setup codebuddy --global
+fec doctor codebuddy --local
+fec doctor codebuddy --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install codebuddy --local` or `--global`.
+
+Skills use `.codebuddy/skills` or `~/.codebuddy/skills` (`CODEBUDDY_CONFIG_DIR` override). This adapter installs skills only; commands, agents, hooks and MCP supported by the product are separate integration opportunities.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://www.codebuddy.ai/docs/cli/skills) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/codex.md

@@ -1,10 +1,18 @@
-# frontend-craft: codex
-
-See root README **Universal Install** and run:
+# frontend-craft: Codex
 
 ```bash
-npx @bovinphang/frontend-craft install codex
+fec setup codex
+fec setup codex --global
+fec doctor codex --local
+fec doctor codex --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install codex --local` or `--global`.
+
+Project skills: `.agents/skills`; user skills: `~/.agents/skills`. Agents: `.codex/agents/*.toml` or `$CODEX_HOME/agents`. Existing `config.toml` is preserved. New agents inherit the session model and reasoning effort; edited agent files are preserved by `fec runtime update`. Hooks and active MCP configuration are not installed by this adapter.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://learn.chatgpt.com/docs/agent-configuration/subagents) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/compatibility.md

@@ -0,0 +1,42 @@
+# Runtime compatibility and upgrades
+
+The adapters install different capability subsets. Run `fec matrix` for the project-level inventory and read the runtime-specific page for global differences. A successful install or doctor result proves the expected artifacts exist, not that every host feature is integrated or a particular release was tested interactively.
+
+## CLI 3.0 command migration
+
+Use `fec runtime install/update/uninstall [runtime]` for managed resources, including npx examples (`npx @bovinphang/frontend-craft@latest runtime update`). Resource flags and the `runtime upgrade/remove` aliases remain available; `setup` remains supported and top-level `install` is deprecated.
+
+Top-level `fec update/upgrade` now upgrades a verified npm/pnpm global CLI to registry `latest`, then refreshes resources in the current project and user-global scope with the new version. Top-level `fec uninstall/remove` removes only the CLI; `--purge` first cleans managed resources while preserving user edits. It requires terminal confirmation or non-interactive `--yes`. `--dry-run` is read-only. Old runtime arguments and resource flags on these top-level commands are rejected before changes.
+
+`runtime update` uses the running CLI package without fetching a new one. Temporary npx runs never create a global install and cannot self-uninstall; use the latest-package runtime command when an npx update reports a version mismatch. CLI upgrade failure stops refresh; partial resource failure is reported without CLI rollback. Other projects and Marketplace installs are not scanned or managed. Source links, project dependencies, unknown sources and pnpm groups shared with other packages are refused for automatic self-management.
+
+## Updating existing installations
+
+Use `fec runtime update <runtime> --local` or `--global` with the new CLI. Updates preserve manifest-tracked files changed by the user. Fresh installs retain existing Codex configuration and context files. Merge any missing rule imports into existing Gemini context files manually.
+
+Unchanged manifest-owned legacy command paths are retired when replacements are installed for OpenCode, Kilo, Copilot, Gemini, OpenClaw and global Windsurf. Unknown or edited old files are preserved. Files that remain in old directories stay tracked for a later uninstall. Claude CLI hooks now live in settings.json; the original native Marketplace packaging stays unchanged.
+
+Antigravity and Cline global defaults changed. Run `fec setup antigravity --global` / `fec setup cline --global` to copy manifest-tracked files to the current destination before updating; user edits and old originals are preserved. `fec runtime update --global` also discovers these legacy installations. For product-specific or redirected directories, use the documented runtime configuration-directory environment variable. It is an installer override; configure the host consistently too.
+
+Shared Claude/Qoder settings are never owned as a whole file. The manifest records installed hook entries, so uninstall removes only exact matching entries and preserves other settings. A user-modified hook entry is preserved; remove it manually if it still refers to a script you uninstall. Malformed settings stop the operation rather than being replaced. Keep the install manifest for safe updates and uninstall.
+
+## Scope differences
+
+- Copilot project installs provide IDE prompt files and path-specific instructions. Global installs provide CLI user instructions, not IDE global prompts.
+- Kilo targets the current CLI discovery contract. Antigravity defaults to its IDE/2.0 global directory; its CLI uses a different override.
+- OpenClaw project installs require the agent workspace as the working directory. Native plugin packaging is separate from the universal installer.
+- Cursor, Augment and CodeBuddy keep their existing supported capability subsets. New host features are not automatically installed.
+- Codex agents inherit the selected model and reasoning effort. Older manually edited TOML files remain untouched by update; remove their model overrides yourself if you want inheritance.
+
+## Verification
+
+Regression tests exercise artifact discovery paths, metadata, existing settings, repeated installation and uninstall behavior. `pnpm test` runs the package's build, type checks and test suite. `pnpm run typecheck:openclaw` and `pnpm run pack:openclaw` verify the separate native package. Full host-session tests require the corresponding installed product and account.
+
+Review scope and diagram delivery rules are shared across adapters; installed artifacts do not guarantee that local Mermaid or a Chromium browser is available. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).
+# 3.0 公共能力说明
+
+公共 Skill 使用 `cc-*`，由固定版本的 craft-common 随产品提供。CLI 按实际 Skill 目录记录公共所有权，而不是按配置目录猜测：Codex 使用项目或用户目录下的 `.agents/skills`；OpenClaw 本地使用项目 `skills`；其他支持标准 Skill 的适配器使用其现有 Skill 目标。
+
+同一真实目标的消费者必须使用一致的公共版本、语言与内容摘要。公共账本位于目标父目录的 `craft-manifests/<目标摘要>/`；产品清单保存依赖指针并继续独立管理 `fec-*` 文件。卸载一个产品保留其他消费者引用，最后退出时也只回收未修改的公共文件。`doctor` 的 `common` 行检查公共依赖和资源状态。
+
+Copilot、Trae、Cline 延续现有规则/命令降级，不宣称新增标准 Skill 支持。原生插件渠道本期保证单产品快照完整，双产品原生去重需另外验证。迁移步骤见 [迁移指南](../common-migration.md)。

package/docs/runtimes/copilot.md

@@ -1,10 +1,18 @@
-# frontend-craft: copilot
-
-See root README **Universal Install** and run:
+# frontend-craft: GitHub Copilot
 
 ```bash
-npx @bovinphang/frontend-craft install copilot
+fec setup copilot
+fec setup copilot --global
+fec doctor copilot --local
+fec doctor copilot --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install copilot --local` or `--global`.
+
+Local installation targets repository customization: `.github/instructions/frontend-craft.instructions.md` with `applyTo: "**"` and `.github/prompts/fec-*.prompt.md`. Prompt files are supported by compatible IDE clients. Global installation targets Copilot CLI user instructions in `~/.copilot/copilot-instructions.md` (`COPILOT_CONFIG_DIR` override), preserving an existing file. Global IDE prompt installation is not provided; use `--local` for prompts.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://docs.github.com/en/copilot/reference/customization-cheat-sheet) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/cursor.md

@@ -1,10 +1,18 @@
-# frontend-craft: cursor
-
-See root README **Universal Install** and run:
+# frontend-craft: Cursor
 
 ```bash
-npx @bovinphang/frontend-craft install cursor
+fec setup cursor
+fec setup cursor --global
+fec doctor cursor --local
+fec doctor cursor --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install cursor --local` or `--global`.
+
+Project skills: `.cursor/skills`; user skills: `~/.cursor/skills` (or `CURSOR_CONFIG_DIR/skills`). Project rules use `.cursor/rules/*.mdc`. This adapter installs skills and project rules; it does not install native agents, hooks, commands or MCP configuration.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://cursor.com/docs/skills) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/gemini.md

@@ -1,10 +1,18 @@
-# frontend-craft: gemini
-
-See root README **Universal Install** and run:
+# frontend-craft: Gemini CLI
 
 ```bash
-npx @bovinphang/frontend-craft install gemini
+fec setup gemini
+fec setup gemini --global
+fec doctor gemini --local
+fec doctor gemini --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install gemini --local` or `--global`.
+
+Skills use `.gemini/skills` or `~/.gemini/skills` (`GEMINI_CONFIG_DIR` override). Rules are copied into `rules/` under that base. If absent, project `GEMINI.md` or user `~/.gemini/GEMINI.md` is created with resolvable rule imports. Existing context files are preserved; add the rule imports manually if you want them in an existing context. This installs native skills, not an incomplete extension.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://geminicli.com/docs/cli/skills/) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/kilo.md

@@ -1,10 +1,18 @@
-# frontend-craft: kilo
-
-See root README **Universal Install** and run:
+# frontend-craft: Kilo CLI
 
 ```bash
-npx @bovinphang/frontend-craft install kilo
+fec setup kilo
+fec setup kilo --global
+fec doctor kilo --local
+fec doctor kilo --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install kilo --local` or `--global`.
+
+This adapter targets the current Kilo CLI: project `.kilo`, user `$XDG_CONFIG_HOME/kilo` or `~/.config/kilo`, with `KILO_CONFIG_DIR` override. Skills use `skills/`, commands use canonical `commands/`. Official CLI source also discovers legacy singular directories and home `.kilo` / `.kilocode` roots. IDE-only installations can have different global discovery behavior; this is not a blanket IDE certification.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://github.com/Kilo-Org/kilocode/blob/main/packages/opencode/src/config/paths.ts) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/openclaw.md

@@ -1,10 +1,18 @@
-# frontend-craft: openclaw
-
-See root README **Universal Install** and run:
+# frontend-craft: OpenClaw
 
 ```bash
-npx @bovinphang/frontend-craft install openclaw
+fec setup openclaw
+fec setup openclaw --global
+fec doctor openclaw --local
+fec doctor openclaw --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install openclaw --local` or `--global`.
+
+Universal CLI: run from the agent workspace; project skills go into `<workspace>/skills`, with the install manifest in `.openclaw`. User skills go into `$OPENCLAW_STATE_DIR/skills` or `~/.openclaw/skills`; `OPENCLAW_CONFIG_DIR` remains a fallback alias. Commands are converted to named skill directories with `SKILL.md`. Global setup does not write project context files. The separately packed native plugin includes hook handlers and an optional workspace initialization tool; `pnpm run pack:openclaw` generates its command skills.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://docs.openclaw.ai/skills) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).

package/docs/runtimes/opencode.md

@@ -1,10 +1,18 @@
-# frontend-craft: opencode
-
-See root README **Universal Install** and run:
+# frontend-craft: OpenCode
 
 ```bash
-npx @bovinphang/frontend-craft install opencode
+fec setup opencode
+fec setup opencode --global
+fec doctor opencode --local
+fec doctor opencode --global
 ```
 
-> **Non-interactive:** append `--local` or `--global` to skip install-location prompts. See the repository README **Universal Install** for interactive vs. scripted behavior.
+Without a global CLI installation, use `npx @bovinphang/frontend-craft runtime install opencode --local` or `--global`.
+
+Project base: `.opencode`; user base: `~/.config/opencode` (`XDG_CONFIG_HOME` / `OPENCODE_CONFIG_DIR` supported). Skills use `skills/`; commands use `commands/`. The generated `opencode.jsonc` uses `permission`, not `permissions`. The exact old generated template is repaired; custom JSONC is preserved. Unchanged manifest-owned `command/` files migrate to `commands/`.
+
+The capability matrix describes what frontend-craft installs, not every feature offered by the host. `doctor` checks installation artifacts; it does not launch the host or certify a release version.
+
+[Official reference](https://opencode.ai/docs/config/) · [Compatibility and upgrade notes](compatibility.md)
 
+Review defaults to the full project; a file/directory request includes unchanged code, while incremental review requires an explicit changes/PR/commit request. Technical diagrams use structured sources; PNG export requires a local browser and disclosed QA coverage. See [review scope and technical diagram delivery](../review-and-diagram-workflows.md).