@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/CONTRIBUTING.zh-CN.md

@@ -8,17 +8,23 @@
 
 - Node.js >= 22，用于通用安装器与 OpenClaw 包构建。
 - Git。
-- 本地开发前运行 `npm install`。
+- pnpm 12.4.1（在 package.json 中固定）；通过 npm 安装 pnpm 需要 Node.js >=22.13。已发布的插件仍支持 Node.js >=22.0.0。
+- pnpm-lock.yaml 是唯一的依赖锁文件。pnpm-workspace.yaml 允许 esbuild 构建脚本，并显式跳过本项目未使用的可选 SDK/原生依赖安装。
+- Windows 上请通过 Corepack（`corepack enable pnpm`）或 npm 安装 pnpm，不要使用 standalone 安装器；standalone 的 pnpm 10+ 会屏蔽安装固定版本原生二进制的 lifecycle 脚本，留下 Windows 无法执行的 shim。
+- 本地开发前运行 `pnpm install --frozen-lockfile`。
 
 仅修改文档时，重点阅读语言与文档策略以及 Pull Request 自检。修改 skill 或 OpenClaw 时，请在提交 PR 前参考下方对应章节。
 
 快速自检（最小推荐）：
 
 ```bash
-npm test                         # 通用校验
-npm run pack:skills              # Skill 变更
-npm run check:skills-publish     # Skill 变更
-npm run typecheck:openclaw       # OpenClaw 变更
+pnpm lint                         # ESLint + 内容一致性
+pnpm typecheck                    # TypeScript + Skill 脚本类型检查
+pnpm run check:common             # 公共快照只读校验
+pnpm test                         # 构建 + 全部测试
+pnpm run pack:skills              # Skill 变更
+pnpm run check:skills-publish     # Skill 变更
+pnpm run typecheck:openclaw       # OpenClaw 变更
 ```
 
 完整的场景化命令请见后文 npm scripts 与 Pull Request 自检。
@@ -48,23 +54,25 @@ npm run typecheck:openclaw       # OpenClaw 变更
 
 ```bash
 # 1. 安装依赖
-npm install
+pnpm install
 
 # 2. 构建 dist/bin 与 dist/hooks
-npm run build
+pnpm run build
 
 # 3. 本地安装到指定 runtime（如 claude）
-node dist/bin/frontend-craft.js install claude --local --dry-run  # 先 dry-run 预览
-node dist/bin/frontend-craft.js install claude --local            # 实际安装
+node dist/bin/frontend-craft.js runtime install claude --local --dry-run  # 先 dry-run 预览
+node dist/bin/frontend-craft.js runtime install claude --local            # 实际安装
 
 # 4. 安装到所有 runtime
-node dist/bin/frontend-craft.js install --all --dry-run
+node dist/bin/frontend-craft.js runtime install --all --dry-run
 
 # 5. 列出所有支持的 runtime
 node dist/bin/frontend-craft.js list
 ```
 
-`npm run build` 会依次运行 `clean`、`typecheck` 和 `scripts/build-dist.ts`。本地使用 `dist/bin/frontend-craft.js` 或打包后的 hook 脚本前，请先运行它。
+`pnpm run build` 会依次运行 `clean`、`typecheck` 和 `scripts/build-dist.ts`。本地使用 `dist/bin/frontend-craft.js` 或打包后的 hook 脚本前，请先运行它。
+
+源码检出不支持 CLI 自身管理。使用 `node dist/bin/frontend-craft.js runtime update --dry-run` 预览包内资源更新；顶层 update/uninstall 应通过隔离的 npm/pnpm 全局安装、假包管理器及临时 HOME 验证。顶层 `--dry-run` 必须保持只读。3.0 命令迁移见 README 迁移表。
 
 ## 测试指南
 
@@ -72,7 +80,7 @@ node dist/bin/frontend-craft.js list
 
 ```bash
 # 运行所有测试
-npm test
+pnpm test
 
 # 运行单个测试文件
 node --import tsx --test tests/install/cli.test.ts
@@ -93,17 +101,17 @@ node --import tsx --test tests/install/all-runtimes-dry.test.ts
 FRONTEND_CRAFT_FORCE_INTERACTIVE=1 node --import tsx --test tests/install/cli.test.ts
 ```
 
-`npm test` 会先运行 `npm run build`，再通过 `tsx` 执行 `tests/` 下精选的 converter 与 installer 测试。
+`pnpm test` 会先运行 `pnpm run build`，再递归发现 `tests/**/*.test.ts`，通过 Node.js `node:test` 串行执行全部测试。已有构建时可使用 `pnpm run test:only`。
 
 ## OpenClaw 构建流程
 
 OpenClaw runtime 有独立的构建管线：
 
 ```bash
-npm run build:openclaw          # 使用 esbuild 将 TypeScript 打包到 dist/openclaw/
-npm run typecheck:openclaw      # TypeScript 类型检查
-npm run check:openclaw-dist     # 验证 dist 完整性
-npm run pack:openclaw           # 完整构建 + 验证 + 打包
+pnpm run build:openclaw          # 使用 esbuild 将 TypeScript 打包到 dist/openclaw/
+pnpm run typecheck:openclaw      # TypeScript 类型检查
+pnpm run check:openclaw-dist     # 验证 dist 完整性
+pnpm run pack:openclaw           # 完整构建 + 验证 + 打包
 ```
 
 源码路径：`src/openclaw/`（TypeScript）→ `dist/openclaw/index.js`（打包后的 ESM）。
@@ -114,12 +122,12 @@ TypeScript 配置：`tsconfig.openclaw.json`。
 Skill 的权威源文件位于 `skills/<skill-id>/`。不要手动修改 `skill-packages/` 下的生成产物。
 
 ```bash
-npm run pack:skills            # 为每个 skill 生成独立发布包
-npm run check:skills-publish   # 校验包元数据、索引和引用文件
-npm run pack:all               # 构建 + 测试 + OpenClaw 包 + 独立 skill 包
+pnpm run pack:skills            # 为每个 skill 生成独立发布包
+pnpm run check:skills-publish   # 校验包元数据、索引和引用文件
+pnpm run pack:all               # 构建 + 测试 + OpenClaw 包 + 独立 skill 包
 ```
 
-`npm run pack:skills` 会生成 `skill-packages/<skill-id>/`，其中包含 `SKILL.md`、该 skill 实际引用的 `references/` 文件、`metadata.json`、`package.json`、`README.md` 和 `LICENSE`。同时会生成 `skill-packages/index.json`，供平台索引或发布自动化使用。
+`pnpm run pack:skills` 会生成 `skill-packages/<skill-id>/`，其中包含 `SKILL.md`、实际引用的 `references/` 及运行所需的 scripts、assets、data、styles 等资源、`metadata.json`、`package.json`、`README.md` 和 `LICENSE`。同时会生成 `skill-packages/index.json`，供平台索引或发布自动化使用。
 
 修改 skill 时，请保持这些源文件一致：
 
@@ -128,34 +136,41 @@ npm run pack:all               # 构建 + 测试 + OpenClaw 包 + 独立 skill
 - `skills/eval_queries.json` — 用于路由质量检查的正向/负向触发样例。
 - 当公开 skill 列表或用户可见行为变化时，同步 `README.md` 和各语言 README 摘要。
 
-## npm scripts
+## 开发 scripts
+
+包管理器固定为 pnpm 12.4.1，唯一依赖锁文件为 pnpm-lock.yaml。通过 npm 安装 pnpm 需要 Node.js >=22.13；发布插件的运行要求仍为 Node.js >=22.0.0。使用 `pnpm install --frozen-lockfile` 安装依赖。pnpm-workspace.yaml 仅允许 esbuild 构建脚本，其余当前未使用的 SDK/原生初始化显式跳过。
+
+`pnpm lint` 检查代码和中英文内容声明；`pnpm format:check` 只检查变更的源码与配置，不修改文件。`pnpm test` 自动发现 tests 下的所有 *.test.ts，无需手动维护清单。
 
 请把 `package.json` scripts 作为公开的开发入口。
 
 | Script                         | 用途                                                                       |
 | ------------------------------ | -------------------------------------------------------------------------- |
-| `npm run clean`                | 删除 `dist/`。                                                             |
-| `npm run typecheck`            | 运行主项目 TypeScript 检查，并检查 skill 辅助脚本。                        |
-| `npm run build`                | 运行 `clean`、`typecheck`，并通过 `scripts/build-dist.ts` 打包 CLI/hooks。 |
-| `npm test`                     | 先构建，再通过 `tsx` 运行精选的 `node:test` 测试集。                       |
-| `npm run build:openclaw`       | 构建主项目，然后打包 OpenClaw runtime 输出。                               |
-| `npm run audit:skills`         | 构建后输出 skill 说明长度与描述重叠度信号。                                |
-| `npm run typecheck:openclaw`   | 使用 `tsconfig.openclaw.json` 检查 OpenClaw 类型。                         |
-| `npm run check:openclaw-dist`  | 校验生成的 OpenClaw dist 输出。                                            |
-| `npm run pack:openclaw`        | 构建、校验并打包 OpenClaw 插件。                                           |
-| `npm run pack:skills`          | 先构建，再在 `skill-packages/` 下生成独立 skill 包。                       |
-| `npm run check:skills-publish` | 先构建，再校验独立 skill 包元数据与复制文件。                              |
-| `npm run pack:all`             | 构建、运行测试、打包 OpenClaw、打包 skills，并校验 skill 产物。             |
-| `npm run sync:version`         | 同步发布清单中的 package 版本元数据。                                      |
-| `npm run version`              | 运行 `sync:version`，并为 npm version 工作流暂存版本清单。                 |
-| `npm run prepack`              | 在 `npm pack` 前构建。                                                     |
-| `npm run prepublishOnly`       | 在 npm publish 前同步版本并运行测试。                                      |
+| `pnpm run lint` | 检查代码和中英文内容声明。 |
+| `pnpm run format:check` | 检查变更源码的格式。 |
+| `pnpm run check:content` | 校验 YAML、名称、引用及本地化结构。 |
+| `pnpm run clean`                | 删除 `dist/`。                                                             |
+| `pnpm run typecheck`            | 运行主项目 TypeScript 检查，并检查 skill 辅助脚本。                        |
+| `pnpm run build`                | 运行 `clean`、`typecheck`，并通过 `scripts/build-dist.ts` 打包 CLI/hooks。 |
+| `pnpm test`                     | 先构建，再递归发现并执行全部 `node:test` 测试。                       |
+| `pnpm run build:openclaw`       | 构建主项目，然后打包 OpenClaw runtime 输出。                               |
+| `pnpm run audit:skills`         | 构建后输出 skill 说明长度与描述重叠度信号。                                |
+| `pnpm run typecheck:openclaw`   | 使用 `tsconfig.openclaw.json` 检查 OpenClaw 类型。                         |
+| `pnpm run check:openclaw-dist`  | 校验生成的 OpenClaw dist 输出。                                            |
+| `pnpm run pack:openclaw`        | 构建、校验并打包 OpenClaw 插件。                                           |
+| `pnpm run pack:skills`          | 先构建，再在 `skill-packages/` 下生成独立 skill 包。                       |
+| `pnpm run check:skills-publish` | 先构建，再校验独立 skill 包元数据与复制文件。                              |
+| `pnpm run pack:all`             | 构建、运行测试、打包 OpenClaw、打包 skills，并校验 skill 产物。             |
+| `pnpm run sync:version`         | 同步发布清单中的 package 版本元数据。                                      |
+| `pnpm run version`              | 运行 `sync:version` 同步版本元数据，不自动暂存文件。                       |
+| `pnpm run prepack`              | 在 `npm pack` 前构建。                                                     |
+| `pnpm run prepublishOnly`       | 在 npm publish 前同步版本并运行测试。                                      |
 
 常见变更类型建议：
 
-- Skill 变更：运行 `npm test`、`npm run audit:skills`、`npm run pack:skills` 和 `npm run check:skills-publish`。
-- OpenClaw 变更：运行 `npm run typecheck:openclaw` 和 `npm run pack:openclaw`。
-- 发布打包：运行 `npm run pack:all`；`prepublishOnly` 也会在发布前执行版本同步和测试。
+- Skill 变更：运行 `pnpm test`、`pnpm run audit:skills`、`pnpm run pack:skills` 和 `pnpm run check:skills-publish`。
+- OpenClaw 变更：运行 `pnpm run typecheck:openclaw` 和 `pnpm run pack:openclaw`。
+- 发布打包：运行 `pnpm run pack:all`；`prepublishOnly` 也会在发布前执行版本同步和测试。
 
 ## 源码维护脚本
 
@@ -181,11 +196,12 @@ Hook 脚本位于 `src/hooks/`，发布时会打包到 `dist/hooks/` 供 runtime
 
 | 源文件                             | 打包输出                            | 用途           |
 | ---------------------------------- | ----------------------------------- | -------------- |
-| `src/hooks/run-tests.ts`           | `dist/hooks/run-tests.js`           | 测试运行辅助   |
-| `src/hooks/format-changed-file.ts` | `dist/hooks/format-changed-file.js` | 格式化变更文件 |
-| `src/hooks/security-check.ts`      | `dist/hooks/security-check.js`      | 安全检查       |
-| `src/hooks/notify.ts`              | `dist/hooks/notify.js`              | 通知脚本       |
-| `src/hooks/session-start.ts`       | `dist/hooks/session-start.js`       | 会话初始化     |
+| `src/hooks/cleanup-claude-cache.ts` | `dist/hooks/fec-cleanup-claude-cache.js` | 缓存清理 |
+| `src/hooks/run-tests.ts`           | `dist/hooks/fec-run-tests.js`           | 测试运行辅助   |
+| `src/hooks/format-changed-file.ts` | `dist/hooks/fec-format-changed-file.js` | 格式化变更文件 |
+| `src/hooks/security-check.ts`      | `dist/hooks/fec-security-check.js`      | 安全检查       |
+| `src/hooks/notify.ts`              | `dist/hooks/fec-notify.js`              | 通知脚本       |
+| `src/hooks/session-start.ts`       | `dist/hooks/fec-session-start.js`       | 会话初始化     |
 
 ## 架构概览
 
@@ -281,7 +297,7 @@ description: Use when the user needs ...
 4. 在 `skills/eval_queries.json` 中补充正向和负向触发样例。
 5. 在 `README.md` 的 Skills 表格中新增一行。
 6. 若可见目录结构变化，同步 `README.md` 与各语言 README 的目录树。
-7. 运行 `npm test`、`npm run pack:skills` 和 `npm run check:skills-publish`。
+7. 运行 `pnpm test`、`pnpm run pack:skills` 和 `pnpm run check:skills-publish`。
 
 ## 如何添加 Agent
 
@@ -328,8 +344,8 @@ skills:
 
 1. 更新 `hooks/hooks.json`。
 2. 如需 runtime hook 脚本，放在 `src/hooks/` 下，并优先使用跨平台 Node.js。
-3. 在 `scripts/build-dist.ts` 中新增对应入口，确保 `npm run build` 会将其打包到 `dist/hooks/`。
-4. 在 `hooks/hooks.json` 中，引用内置 hook 入口请使用 **`${CLAUDE_PLUGIN_ROOT}/dist/hooks/<script>.js`**（Claude Code 会在运行时替换根路径；见官方 [Plugins reference](https://code.claude.com/docs/en/plugins-reference)）。本仓库的 Claude 安装器在将 `hooks.json` 写入 `.claude/` 时，也会把 **`${CLAUDE_PLUGIN_ROOT}`** 及旧占位符 **`${FRONTEND_CRAFT_ROOT}`** 展开为绝对路径。
+3. 在 `scripts/build-dist.ts` 中新增对应入口，确保 `pnpm run build` 会将其打包到 `dist/hooks/`。
+4. 在 `hooks/hooks.json` 中，引用内置 hook 入口请使用 **`${CLAUDE_PLUGIN_ROOT}/dist/hooks/<script>.js`**（Claude Code 会在运行时替换根路径；见官方 [Plugins reference](https://code.claude.com/docs/en/plugins-reference)）。本仓库的 Claude 安装器在将 CLI 管理的 hook 条目合并到 `.claude/settings.json` 时，也会把 **`${CLAUDE_PLUGIN_ROOT}`** 及旧占位符 **`${FRONTEND_CRAFT_ROOT}`** 展开为绝对路径。
 5. 仓库维护脚本继续放在 `scripts/`，不要在 runtime hook 配置中直接引用它们。
 6. 更新 `README.md` 的 Hooks 表格。
 
@@ -338,13 +354,13 @@ skills:
 提交 PR 前请确认：
 
 - [ ] 变更范围清晰，描述明确。
-- [ ] `npm test` 通过。
-- [ ] 修改 skill 时，`npm run audit:skills`、`npm run pack:skills` 与 `npm run check:skills-publish` 通过。
-- [ ] 修改 OpenClaw 代码或模板时，`npm run typecheck:openclaw` 与 `npm run pack:openclaw` 通过。
+- [ ] `pnpm test` 通过。
+- [ ] 修改 skill 时，`pnpm run audit:skills`、`pnpm run pack:skills` 与 `pnpm run check:skills-publish` 通过。
+- [ ] 修改 OpenClaw 代码或模板时，`pnpm run typecheck:openclaw` 与 `pnpm run pack:openclaw` 通过。
 - [ ] 用户可见行为变化已更新 `README.md` 与 `CHANGELOG.md`（及 [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md) 如适用）。
 - [ ] 多语言 README 已同步，或已链接后续翻译 Issue。
 - [ ] 新增 runtime、agent、skill、command、hook 或模板时，包含相关测试或 dry-run 覆盖。
-- [ ] 发布打包相关变更已通过 `npm run pack:all`，或已由 `prepublishOnly` 发布门禁覆盖。
+- [ ] 发布打包相关变更已通过 `pnpm run pack:all`，或已由 `prepublishOnly` 发布门禁覆盖。
 - [ ] 涉及安全敏感逻辑时，已按 [SECURITY.zh-CN.md](SECURITY.zh-CN.md) / [SECURITY.md](SECURITY.md) 检查。
 
 ## 代码风格
@@ -359,3 +375,9 @@ skills:
 使用 [GitHub Issues](https://github.com/bovinphang/frontend-craft/issues) 提交 Bug 或功能建议。请尽量包含 runtime、操作系统、Node.js 版本、执行命令、预期行为和实际行为。
 
 **安全敏感漏洞**不要提交公开 Issue，请按 [SECURITY.zh-CN.md](SECURITY.zh-CN.md)（或 [SECURITY.md](SECURITY.md)）处理。
+
+修改审核或图表能力时，同步各语言 README 与运行时指南中的范围默认值、自然语言示例、工具前提、QA 边界和覆盖报告要求。参见 [审核范围与技术图交付](docs/zh-CN/review-and-diagram-workflows.md).
+
+## 公共内容维护
+
+`cc-*` Skill 和内嵌公共方法由精确依赖 `@bovinphang/craft-common@2.0.0` 生成，禁止直接修改分发副本。先在 craft-common 修改并准备对应包，再运行 `pnpm run sync:common`，审阅 `common-content.lock.json` 与中英文快照，最后运行 `pnpm run check:common` 和 `pnpm lint`。前端领域 Skill、元数据及中文镜像仍在本仓库维护。完整目录和维护边界见[项目结构](docs/zh-CN/project-structure.md)与[公共能力迁移](docs/zh-CN/common-migration.md)。

package/README.md

@@ -1,5 +1,8 @@
 <div align="center">
 
+> Release status (2026-11-09): craft-common 2.0.0 is published on npm. Frontend 3.0.0 and backend 1.0.0 remain unreleased; product versions are unchanged. Earlier preparation notes describe the pre-publication state.
+
+
 <img src="assets/brand/frontend-craft.png" alt="frontend-craft logo" width="200" />
 
 # frontend-craft
@@ -22,6 +25,9 @@
 
 </div>
 
+
+[Runtime compatibility and upgrade notes](docs/runtimes/compatibility.md)
+
 ---
 
 `frontend-craft` is a **universal frontend plugin** that brings the same opinionated engineering standards to all **15 AI coding assistants** listed below:
@@ -32,7 +38,7 @@
 
 Per-runtime paths and caveats live in [`docs/runtimes/`](docs/runtimes/).
 
-It bundles **13 specialized agents**, **45 auto-activated skills**, **8 slash commands**, **5 event-driven hooks**, **MCP integrations** for 6 design-tool endpoints, and a complete **rules library** into a single installable package. Run one command, and every AI session on your team writes React, Vue, Next.js, or Nuxt the same way — typed, accessible, secure, and consistent.
+It bundles **14 specialized agents**, **74 auto-activated skills**, **11 slash commands**, **5 event-driven hooks**, **MCP integrations** for 6 design-tool endpoints, and a complete **rules library** into a single installable package. Run one command, and every AI session on your team writes React, Vue, Next.js, or Nuxt the same way — typed, accessible, secure, and consistent.
 
 ---
 
@@ -40,10 +46,10 @@ It bundles **13 specialized agents**, **45 auto-activated skills**, **8 slash co
 
 | Problem                                                              | What frontend-craft does                                                                       |
 | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| AI assistants write inconsistent, untyped, or insecure frontend code | **45 skills** encode team standards — auto-activated when the assistant touches matching files |
+| AI assistants write inconsistent, untyped, or insecure frontend code | **74 skills** encode team standards — auto-activated when the assistant touches matching files |
 | Each AI tool has its own plugin format                               | **One CLI** installs the same rules, agents, and hooks into 15 runtimes                        |
 | Design-to-code handoff is lossy                                      | **MCP integrations** bring in richer context from Figma, Figma Desktop, Sketch, MasterGo, Pixso, and 墨刀 |
-| Reviews are ad-hoc and shallow                                       | **13 agents** produce graded reports: code, security, a11y, performance, TS, UI fidelity       |
+| Reviews are ad-hoc and shallow                                       | **14 agents** produce graded reports: code, security, a11y, performance, TS, UI fidelity       |
 | No one remembers to run lint/tests                                   | **Event-driven hooks** validate on save and session end — automatically                        |
 | New projects start from scratch every time                           | **`/fec-init`** scaffolds CLAUDE.md, rules, and settings in seconds                            |
 
@@ -76,7 +82,7 @@ fec setup claude --global
 fec setup all --global
 
 # 6. Preview / query
-fec install --all --dry-run --global
+fec runtime install --all --dry-run --global
 fec list
 ```
 
@@ -89,17 +95,17 @@ fec list
 npx @bovinphang/frontend-craft@latest
 
 # 2. Connect the current project
-npx @bovinphang/frontend-craft@latest install --local codex
-npx @bovinphang/frontend-craft@latest install --local claude
-npx @bovinphang/frontend-craft@latest install --all --local
+npx @bovinphang/frontend-craft@latest runtime install --local codex
+npx @bovinphang/frontend-craft@latest runtime install --local claude
+npx @bovinphang/frontend-craft@latest runtime install --all --local
 
 # 3. Connect globally, available across all projects
-npx @bovinphang/frontend-craft@latest install --global codex
-npx @bovinphang/frontend-craft@latest install --global claude
-npx @bovinphang/frontend-craft@latest install --all --global
+npx @bovinphang/frontend-craft@latest runtime install --global codex
+npx @bovinphang/frontend-craft@latest runtime install --global claude
+npx @bovinphang/frontend-craft@latest runtime install --all --global
 
 # 4. Preview / query
-npx @bovinphang/frontend-craft@latest install --all --dry-run --global
+npx @bovinphang/frontend-craft@latest runtime install --all --dry-run --global
 npx @bovinphang/frontend-craft@latest list
 ```
 
@@ -109,7 +115,7 @@ Use `npx` when you do not want to install a global `fec` command. Without argume
 
 For Claude Code users, **Claude Code Marketplace** is the preferred single-source install. Use the CLI for Claude only when you need cross-runtime installs, scripted/offline file copies, or non-Marketplace environments.
 
-If Marketplace is already installed, the CLI will not install or update a second Claude copy, even with `--force`; update through Claude Code Marketplace instead. If a CLI-managed Claude install already exists in the other scope, interactive terminals ask whether to keep that source updated or uninstall it before switching. Non-interactive terminals stop and print the exact `update`, `uninstall`, and `install` commands to run.
+If Marketplace is already installed, the CLI will not install or update a second Claude copy, even with `--force`; update through Claude Code Marketplace instead. If a CLI-managed Claude install already exists in the other scope, interactive terminals ask whether to keep that source updated or uninstall it before switching. Non-interactive terminals stop and print the exact `runtime update`, `runtime uninstall`, and `runtime install` commands to run.
 
 Full Claude-specific steps are in [docs/runtimes/claude.md](docs/runtimes/claude.md) · [简体中文](docs/runtimes/claude.zh-CN.md).
 
@@ -134,6 +140,9 @@ You: "/fec-scaffold dashboard feature"
 
 You: "/fec-refactor-clean"
 → Classifies and safely removes dead code, unused exports, styles, and deps
+
+You: "/fec-refactor src/features/compose"
+→ Diagnoses structural smells, builds a small-step plan, refactors one behavior-preserving step at a time, and validates every step
 ```
 
 All slash commands below are shown for **Claude Code**; other runtimes expose the same capabilities through their own command systems (see [`docs/runtimes/`](docs/runtimes/)).
@@ -150,6 +159,9 @@ You: "Before coding, plan the account billing feature: route structure, componen
 You: "Build a multi-step registration form; choose the right form and schema validation approach for this project, with file upload, conditional fields, async validation, and accessible errors."
 You: "Implement the UI from Figma node 123:456. Use existing design tokens and components, match spacing and responsive states, and document assumptions."
 You: "`/fec-refactor-clean` Clean up dead code in this module."
+You: "`/fec-smell` Diagnose structural smells in this module without editing."
+You: "`/fec-refactor-plan` Build a behavior-preserving small-step refactoring plan."
+You: "`/fec-refactor` Refactor this module without changing observable behavior."
 ```
 
 ---
@@ -163,14 +175,31 @@ Slash commands are the primary entry points for structured workflows. Most produ
 | Command               | Purpose                                                                | Report                                           |
 | --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------ |
 | `/fec-init`           | Initialize project templates (CLAUDE.md, rules, settings)              | —                                                |
-| `/fec-review`         | Structured review of specified or recently changed files               | `code-review-*.md`                               |
+| `/fec-review`         | Review the full project by default; explicit file/directory or change scope | `code-review-*.md`                               |
 | `/fec-scaffold`       | Create page / feature / component boilerplate by convention            | —                                                |
 | `/fec-plan`           | Unified planning: implementation architecture or test strategy         | `architecture-proposal-*.md` or `test-plan-*.md` |
 | `/fec-tdd`            | Red → green → refactor loop for frontend TDD                           | —                                                |
 | `/fec-debug`          | Diagnose and fix frontend issues: build, runtime, UI, and API failures | `debug-*.md`                                     |
 | `/fec-refactor-clean` | Classify and safely remove dead code, unused exports, styles, and deps | `refactor-clean-*.md`                            |
+| `/fec-smell`          | Diagnose code smells with evidence; do not edit business code             | `refactoring/smell-*.md`                       |
+| `/fec-refactor-plan`  | Build an ordered behavior-preserving refactoring plan                      | `refactoring/plan-*.md`                        |
+| `/fec-refactor`       | Execute one validated behavior-preserving refactoring step at a time       | `refactoring/refactoring-*.md`                 |
 | `/fec-doc-sync`       | Sync READMEs, docs, env notes, scripts, API/route notes, and deploy docs | —                                                |
 
+### Review scope
+
+`/fec-review`, the code/TypeScript/security review agents, and their review skills use three modes:
+
+- **Change review:** explicitly request recent/current/staged changes, a PR or a commit, or use an established change context. With no changes, report that there is nothing to review; do not automatically review recent commits.
+- **Targeted review:** specify a file or directory to review existing code, including unchanged code, without requiring a Git diff.
+- **Project review (default):** with no scope or change context, or when the entire project is requested, inventory project-owned frontend code, related tests, configuration and dependency declarations, then review by module.
+
+A file/directory request reviews its full contents; add "recent changes" to review only its diff. Bare `/fec-review` reviews the project even when changes exist. State mode and scope before review. Automatic review after edits must pass the current change scope explicitly.
+
+Examples: `/fec-review`,`/fec-review review recent changes`,  `/fec-review review src/components/Button.tsx`, `/fec-review review src/features/`, and `/fec-review review the entire project`. These are natural-language instructions, not CLI flags. Explicit scope takes precedence over the default.
+
+Dependency directories, build outputs, caches, generated files and third-party code are excluded by default. Reports record the mode, target scope, reviewed and unreviewed files/modules, exclusions, completion status and verification results. Limited coverage is marked partial; reading callers or running project-wide lint/typecheck does not establish manual review coverage. Change reviews retain merge recommendations; targeted/project reviews assess risk within reviewed scope. The frontend review does not replace a backend audit, and reviewers do not edit business code unless repairs are requested.
+
 ### Skills (auto-activated)
 
 Skills are workflow definitions that activate automatically based on file patterns, frameworks, or task context. They encode review dimensions, output conventions, and report formats.
@@ -187,7 +216,7 @@ The skills below are grouped by use case so you can quickly find project standar
 | `fec-nuxt-project-standard`     | Nuxt 3 SSR/SSG, composables, data fetching, middleware                |
 | `fec-vite-project-standard`     | Vite config, env safety, HMR, dev proxy, build optimization           |
 | `fec-monorepo-project-standard` | pnpm workspace, Turborepo, Nx structure and task orchestration        |
-| `fec-typescript-project-standard`   | TypeScript config, public API types, declarations, DTOs, generics             |
+| `cc-typescript-project-standard`   | TypeScript config, public API types, declarations, DTOs, generics             |
 
 **Implementation capabilities** — activated when building specific frontend behavior:
 
@@ -218,22 +247,38 @@ The skills below are grouped by use case so you can quickly find project standar
 
 | Skill                          | Scope                                                                         |
 | ------------------------------ | ----------------------------------------------------------------------------- |
-| `fec-code-review`              | Architecture, types, rendering, styles, a11y review                           |
+| `fec-code-review`              | Correctness, maintainability, types, rendering, and verification review        |
 | `fec-debug-framework`          | Systematic diagnostics for build, runtime, UI, and API/data failures          |
-| `fec-security-review`          | XSS, CSRF, sensitive data leakage, input validation                           |
+| `fec-security-review`          | Browser-side XSS, CSRF, token exposure, unsafe DOM, and third-party risks     |
 | `fec-accessibility-check`      | WCAG 2.2, keyboard, focus, touch, and screen-reader behavior                  |
 | `fec-dependency-upgrade`       | Dependency upgrades, lockfile review, CVE remediation, migration verification |
 | `fec-validation-fix`           | Run and repair lint, type-check, test, build in one pass                      |
 | `fec-performance-optimization` | Core Web Vitals, bundle, rendering, memory, network, and budget reviews       |
 | `fec-refactor-clean`           | Safe dead-code, unused export, style, route, dependency cleanup               |
 
+**Refactoring** — activated for evidence-based, behavior-preserving structural improvement:
+
+| Skill | Purpose |
+| --- | --- |
+| `fec-refactoring` | Orchestrate classification, baseline, safety, small-step execution, rollback, and proof |
+| `fec-code-smells` | Diagnose the 24 canonical code smells with evidence and false-positive checks |
+| `fec-refactoring-catalog` | Select and compose techniques from the complete 61-item catalog |
+| `fec-refactoring-functions` | Function decomposition, naming, variable, parameter-object, and phase refactorings |
+| `fec-refactoring-encapsulation` | Record, collection, primitive, class, delegate, and algorithm encapsulation refactorings |
+| `fec-refactoring-move-features` | Move functions/fields/statements, split loops, pipelines, and dead-code routing |
+| `fec-refactoring-data` | Variable/field and reference/value data refactorings |
+| `fec-refactoring-control` | Conditional decomposition, guards, polymorphic dispatch, special cases, assertions |
+| `fec-refactoring-api` | Query/modifier, parameter, flag, factory, command, and API-shape refactorings |
+| `fec-refactoring-inheritance` | Inheritance/delegation refactorings with composition-first frontend adaptations |
+| `fec-refactoring-validation` | Behavior-preservation contracts, coverage levels, verification ladder, proof verdicts |
+
 **Design UI** — activated for design-to-code, design systems, and visual polish:
 
 | Skill                         | Scope                                                                         |
 | ----------------------------- | ----------------------------------------------------------------------------- |
 | `fec-ui-design`               | Product-context UI direction, anti-generic design dials, media strategy, states, visual QA |
-| `fec-image-generation`        | System blueprints, process workflows, interactive live diagrams, HTML/SVG/PNG exports, image generation/editing, visual assets, and PNG QA |
-| `fec-drawio-studio`         | Editable draw.io / diagrams.net technical diagrams, XML/Mermaid/CSV URL handoff, shape lookup, auto-layout, code maps |
+| `fec-image-generation`        | UI, product and brand image generation/editing with shared PNG QA |
+| `cc-drawio-studio`         | Editable draw.io / diagrams.net technical diagrams, XML/Mermaid/CSV URL handoff, shape lookup, auto-layout, code maps |
 | `fec-web-video-presentation` | Recordable 16:9 step-driven web presentations from articles, scripts, lessons, and demos |
 | `fec-tailwind-design-system`  | Tailwind tokens, theme extension, variants, class governance, dark mode       |
 | `fec-responsive-layout`       | Mobile-first layouts, container queries, data-dense responsive UI             |
@@ -241,6 +286,10 @@ The skills below are grouped by use case so you can quickly find project standar
 | `fec-implement-from-design`   | Build UI from design tools, screenshots, or section-level visual references   |
 | `fec-storybook-component-doc` | Storybook component docs, design-system presentation, isolated state previews |
 
+Technical diagram quality: `cc-technical-diagrams` prefers local Mermaid for standard sequence/workflow diagrams and the draw.io workflow for editable architecture, with JSON/HTML fallback when tools are unavailable. Export a browser-measured manifest scaled to the PNG, run QA and inspect the final image. Preserve complete text, explicit layout and relationships; repair the source for at most two automatic rounds and report unresolved issues. Reproducible fixtures are in `skills/cc-technical-diagrams/assets/quality-examples/`.
+
+[Review and technical diagram guide](docs/review-and-diagram-workflows.md).
+
 **Legacy migration** — activated during modernization work:
 
 | Skill                            | Scope                                                      |
@@ -260,7 +309,7 @@ The skills below are grouped by use case so you can quickly find project standar
 | ------------------------------- | -------------------------------------------------------------------------------------- |
 | `fec-backend-requirements-handoff` | Frontend-to-backend handoff for UI data needs, actions, states, rules, and questions |
 | `fec-doc-sync`                  | Keep frontend docs in sync with code, config, scripts, routes, APIs, env, and deploy facts |
-| `fec-source-driven-development` | Verify version-sensitive frontend decisions against project facts and official sources |
+| `cc-source-driven-development` | Verify version-sensitive frontend decisions against project facts and official sources |
 
 ### Agents
 
@@ -276,6 +325,7 @@ Agents are specialized sub-agents dispatched by the main assistant to handle a f
 | `fec-test-planner`          | Risk-to-layer matrix: static, unit, component, E2E, visual, a11y, security | `test-plan-*.md`             |
 | `fec-debugger`              | Complex frontend diagnostics for build, runtime, UI, and API failures      | `debug-*.md`                 |
 | `fec-refactor-cleaner`      | Classify and safely remove unused code, exports, styles, routes, deps      | `refactor-clean-*.md`        |
+| `fec-refactoring-expert`   | Evidence-based behavior-preserving refactoring orchestration              | `refactoring/refactoring-*.md` |
 | `fec-e2e-runner`            | E2E authoring and runs (Playwright/Cypress), flaky quarantine, traces      | `e2e-summary-*.md`           |
 | `fec-doc-updater`           | Sync README, runtime docs, structure, capability tables, metadata          | —                            |
 | `fec-ui-checker`            | Visual issue debugging and design fidelity evaluation                      | `ui-fidelity-review-*.md`    |
@@ -291,9 +341,11 @@ Hooks run automatically on AI assistant events — no invocation needed.
 | `SessionStart`            | Clean Claude cache, then detect project framework and package manager |
 | `PreToolUse(Bash)`        | Block dangerous commands (`rm -rf`, force push, etc.)          |
 | `PostToolUse(Write/Edit)` | Auto-format modified files with Prettier                       |
-| `Stop`                    | Run lint, type-check, test, and build on session end           |
+| `Stop`                    | Run available validation scripts once, report failures, and block only when configured |
 | `Notification`            | Cross-platform desktop notifications (macOS / Linux / Windows) |
 
+Stop validation is advisory by default: failures are reported without blocking the session. Set `FRONTEND_CRAFT_VALIDATION_MODE=blocking` to return a failure status. The hook uses `packageManager` from `package.json` when present, otherwise a single lockfile; conflicting lockfiles default to npm.
+
 ### MCP integration
 
 Plug your AI assistant into design tools for design-to-code workflows with richer design context.
@@ -390,7 +442,7 @@ $env:MODAO_TOKEN = "your-modao-token"
 Every review, analysis, and evaluation writes a timestamped Markdown report to `reports/`. These serve as an audit trail and a handoff artifact for PRs.
 
 <details>
-<summary>Click to see all 16 report types</summary>
+<summary>Click to see all 19 report types</summary>
 
 | Report type            | Filename pattern                             | Produced by                                                         |
 | ---------------------- | -------------------------------------------- | ------------------------------------------------------------------- |
@@ -408,6 +460,9 @@ Every review, analysis, and evaluation writes a timestamped Markdown report to `
 | Test plan              | `test-plan-YYYY-MM-DD-HHmmss.md`             | `/fec-plan`, `fec-testing-strategy`, `fec-test-planner`             |
 | Validation fix         | `validation-fix-YYYY-MM-DD-HHmmss.md`        | `fec-validation-fix`                                                |
 | Refactor clean         | `refactor-clean-YYYY-MM-DD-HHmmss.md`        | `/fec-refactor-clean`, `fec-refactor-clean`, `fec-refactor-cleaner` |
+| Smell diagnosis       | `refactoring/smell-YYYY-MM-DD-HHmmss.md`     | `/fec-smell`, `fec-code-smells`                                  |
+| Refactoring plan      | `refactoring/plan-YYYY-MM-DD-HHmmss.md`      | `/fec-refactor-plan`, `fec-refactoring`                           |
+| Refactoring execution | `refactoring/refactoring-YYYY-MM-DD-HHmmss.md` | `/fec-refactor`, `fec-refactoring`, `fec-refactoring-expert`    |
 | E2E run summary        | `e2e-summary-YYYY-MM-DD-HHmmss.md`           | `fec-e2e-runner` (optional)                                         |
 | Migration plan         | `migration-plan-YYYY-MM-DD-HHmmss.md`        | `fec-legacy-to-modern-migration`                                    |
 
@@ -419,33 +474,55 @@ Every review, analysis, and evaluation writes a timestamped Markdown report to `
 
 ## Update and Remove
 
-`fec` is the short command for `frontend-craft`. If you have not installed the global `fec` command, use the same arguments with `npx @bovinphang/frontend-craft@latest`, for example `npx @bovinphang/frontend-craft@latest update`.
+### CLI lifecycle (3.0)
+
+`fec update` (`upgrade`) upgrades an npm/pnpm global CLI to the original registry's `latest`, then starts the new CLI to refresh managed resources in the current project and user-global scope, even when already latest. Other projects and Marketplace installs are not scanned or managed. CLI upgrade failure stops refresh; independent resource failures are reported by phase without rolling back the CLI. Retry those resources with `fec runtime update`.
+
+`fec uninstall` (`remove`) removes only the global CLI by default. `--purge` first removes discovered managed resources while preserving user modifications; cleanup errors keep the CLI installed. A terminal prompts for confirmation; non-interactive runs require `--yes`. Self-management supports verified npm/pnpm global registry installs only; source links, project dependencies, unknown sources and pnpm groups shared with other packages are refused before changes. Use the original package manager manually for shared groups. `--dry-run` only previews; it never installs, deletes or starts the refresh process.
+
+```bash
+fec update
+fec uninstall --dry-run
+fec uninstall --purge --yes
+```
+
+Temporary npx runs never create a global CLI install and cannot uninstall the CLI. Top-level npx `update` refreshes resources only if its package version equals registry `latest`; otherwise use `npx @bovinphang/frontend-craft@latest runtime update`.
+
+| 2.x resource command | 3.0 replacement |
+| --- | --- |
+| `fec update [runtime] [options]` | `fec runtime update [runtime] [options]` |
+| `fec uninstall [runtime] [options]` | `fec runtime uninstall [runtime] [options]` |
+| `fec install [runtime] [options]` | `fec runtime install [runtime] [options]` |
+
+Top-level update/uninstall reject old runtime arguments and resource options such as `--global` before making changes. `setup` remains available; top-level `install` is a deprecated compatibility alias. `runtime upgrade/remove` alias `runtime update/uninstall`. Resource options remain available. `runtime update` uses only the currently running CLI package, without fetching a new package from the network.
+
+`fec` is the short command for `frontend-craft`. For resource operations without a global CLI, use `npx @bovinphang/frontend-craft@latest runtime update` (or `runtime install/uninstall`).
 
-### Update
+### Resource update
 
 ```bash
-fec update                         # Update all discovered CLI-managed installs
-fec update <runtime> --local        # Update one local CLI-managed install
-fec update <runtime> --global       # Update one global CLI-managed install
-fec upgrade <runtime> --global      # `upgrade` is an alias for `update`
+fec runtime update                              # Update all discovered CLI-managed installs
+fec runtime update <runtime> --local            # Update one local CLI-managed install
+fec runtime update <runtime> --global           # Update one global CLI-managed install
+fec runtime upgrade <runtime> --global          # `upgrade` is an alias for `update`
 ```
 
-### Remove
+### Resource removal
 
 ```bash
-fec uninstall                       # Remove all discovered CLI-managed installs
-fec remove                          # `remove` is an alias for `uninstall`
-fec uninstall <runtime>             # Remove a specific runtime install
-fec remove <runtime>                # Same removal through the alias
-fec uninstall --global              # Remove discovered global installs only
-fec remove --local                  # Remove discovered local installs only
-fec uninstall <runtime> --dry-run   # Preview removals
-fec uninstall <runtime> --force     # Remove modified managed files too
+fec runtime uninstall                           # Remove all discovered CLI-managed installs
+fec runtime remove                              # `remove` is an alias for `uninstall`
+fec runtime uninstall <runtime>                 # Remove a specific runtime install
+fec runtime remove <runtime>                    # Same removal through the alias
+fec runtime uninstall --global                  # Remove discovered global installs only
+fec runtime remove --local                      # Remove discovered local installs only
+fec runtime uninstall <runtime> --dry-run       # Preview removals
+fec runtime uninstall <runtime> --force         # Remove modified managed files too
 ```
 
-The CLI writes `frontend-craft.manifest.json` into the runtime directory. `update` discovers those manifests automatically when no runtime is provided and **skips files you’ve modified locally**, so customizations survive updates.
+The CLI writes `frontend-craft.manifest.json` into the runtime directory. `runtime update` discovers those manifests automatically when no runtime is provided and **skips files you’ve modified locally**, so customizations survive updates.
 
-`uninstall`/`remove` only deletes files recorded in the manifest. It skips modified files by default; add `--force` only when you want to remove modified managed files too. `--force` does not override a Claude Code Marketplace install.
+`runtime uninstall`/`runtime remove` only deletes files recorded in the manifest. It skips modified files by default; add `--force` only when you want to remove modified managed files too. `--force` does not override a Claude Code Marketplace install.
 
 For **Claude Code Marketplace** or **submodule** installs, see [docs/runtimes/claude.md](docs/runtimes/claude.md) · [简体中文](docs/runtimes/claude.zh-CN.md). `/fec-init` only initializes project config; it is not a second plugin install.
 
@@ -491,3 +568,38 @@ To disable telemetry: `DISABLE_TELEMETRY=1`. Details: [skills.sh CLI docs](https
 **If frontend-craft helps your team ship better code, [give it a Star](https://github.com/bovinphang/frontend-craft).**
 
 </div>
+
+## Craft Common in 3.0
+
+Version 3.0 is unreleased. It delivers 53 frontend entries and 21 shared entries (74 skills total) from the pinned craft-common dependency, without a third manual plugin install. Common source is maintained only in craft-common.
+
+- `cc-drawio-studio`
+- `cc-technical-diagrams`
+- `cc-source-driven-development`
+- `cc-doc-sync-core`
+- `cc-debug-methodology`
+- `cc-refactoring-core`
+- `cc-tdd-methodology`
+
+Run `fec runtime check-migration codex --local --json` and read [migration guide](docs/common-migration.md).
+CLI installation manages shared ownership and uninstall references. Native channels guarantee complete single-product payloads; native dual-product deduplication is not promised.
+
+Pinned common source: `@bovinphang/craft-common@2.0.0`. See [project structure and maintenance boundaries](docs/project-structure.md) and [contributor checks](CONTRIBUTING.md).
+
+## Mixed-project inspection
+
+`fec project inspect . --task-path apps/desktop/src-tauri/src/lib.rs --task-kind ipc --json` reads bounded manifest evidence and recommends only delivered capabilities. Roles (UI, desktop core, native library, service, CLI), languages and frameworks are separate dimensions. It never runs build scripts or installs tools. Shared language entries include independent C and C++ standards; Tauri/Electron are common specialties. Next/React/Vue/Nuxt/Vite stay frontend specialties. No task argument means project-level candidates only.
+
+Common uses the final version number 2.0.0 and is prepared for publication; frontend 3.0.0 and backend 1.0.0 remain unreleased. Exit old common consumers with each old product CLI before installing matching product builds. Run `fec runtime check-migration [runtime] --local --json` first. Unknown or edited retired entries block installation. See [migration](docs/common-migration.md).
+
+<!-- engineering-practices-20261108 -->
+
+## Conditional engineering practices
+
+Eight existing frontend entries now connect shared principles to React/Vue lifecycle, API replay safety, query ownership, review evidence, testing, security and dependency compatibility. Read the entry's local engineering reference for conditions and exceptions. Both products still deliver all21 common entries; language capability is independent of UI, desktop, library or service role. Company guidance does not authorize a toolchain migration.
+
+The [React sample](skills/fec-react-project-standard/examples/engineering/README.md) uses real React/Testing Library/JSDOM to verify stale-result rejection and owned cleanup. Its locked dependencies are isolated. Repository maintenance: explicitly run `pnpm run verify:engineering -- --prepare`, then omit --prepare to reuse only matching preparation. This is a source-repository maintenance task, not a new installed CLI command. DOM simulation does not prove browser E2E, remote rollback or desktop GUI.
+
+Payment writes are not retried solely because of429/5xx/network errors: require a server replay contract, same intent/key and bounded budget, otherwise reconcile the uncertain result. Public clean installation still awaits common publication; [upgrade ownership rules](docs/common-migration.md) remain in force.
+
+Common 2.0.0 release preparation: [current unreleased changes](CHANGELOG.md#300---unreleased). Publish and verify common first; this step does not publish frontend 3.0.0.