@bovinphang/frontend-craft 2.5.0 → 2.7.0

package/.claude-plugin/marketplace.json

@@ -12,9 +12,13 @@
     "plugins": [
         {
             "name": "frontend-craft",
-            "source": "./",
-            "description": "Enterprise frontend team Claude Code plugin — 13 agents, 40 skills, 8 commands, shared rule templates, and production-ready hooks for code review, TypeScript review, type-safety modeling, state management, Tailwind design systems, responsive layout, dependency upgrades, security review, testing strategy, E2E, component testing, route protection, API integration, interaction motion, performance optimization, scaffolding, design-to-code (Figma/Sketch/MasterGo/Pixso/墨刀/摹客), UI design and polish, Vite standards, legacy-to-modern migration, React/Vue/Next.js/Nuxt/monorepo standards, PWA, Web Workers, Canvas/Three.js, SVG animation, CI/CD, architecture planning, and UI debugging with multi-design-tool MCP integration. All reports auto-saved as Markdown files to reports/ directory.",
-            "version": "2.5.0",
+            "source": {
+                "source": "npm",
+                "package": "@bovinphang/frontend-craft",
+                "version": "2.7.0"
+            },
+            "description": "Enterprise frontend team Claude Code plugin — 13 agents, 45 skills, 8 commands, shared rule templates, and production-ready hooks for code review, TypeScript review, type-safety modeling, state management, Tailwind design systems, responsive layout, dependency upgrades, security review, testing strategy, E2E, component testing, route protection, API integration, backend requirements handoff, interaction motion, performance optimization, scaffolding, design-to-code (Figma/Sketch/MasterGo/Pixso/墨刀/摹客), UI design and polish, image generation, editable draw.io drawio studio, web video presentations, Vite standards, legacy-to-modern migration, React/Vue/Next.js/Nuxt/monorepo standards, PWA, Web Workers, Canvas/Three.js, SVG animation, CI/CD, architecture planning, project absorption, and UI debugging with multi-design-tool MCP integration. All reports auto-saved as Markdown files to reports/ directory.",
+            "version": "2.7.0",
             "author": {
                 "name": "Bovin Phang",
                 "email": "pengbaowen@msn.com"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "frontend-craft",
-    "version": "2.5.0",
+    "version": "2.7.0",
     "description": "Shared Claude Code plugin for frontend teams, including frontend skills, subagents, hooks, and MCP integration for Figma/Sketch/MasterGo/Pixso/墨刀/摹客. All reports auto-saved as Markdown files.",
     "author": {
         "name": "Bovin Phang",

package/CHANGELOG.md

@@ -9,6 +9,82 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Project-facing release notes are maintained in English from 2.0.0 onward. Historical entries may preserve their original language.
 
+## [2.7.0] - 2026-06-10
+
+### Added
+
+- **`fec-drawio-studio` skill:** editable draw.io / diagrams.net workflow for technical diagrams, including official shape lookup, brand symbols, Graphviz auto-layout, code structure maps (TS / JS / Go / Python / Rust), validation, export fallback, and an `XML / Mermaid / CSV` URL handoff (`diagram-url --create`) with self-hosted `baseUrl`, lightbox, dark and Windows `.url` shortcut support.
+- **`fec-image-generation` skill:** diagrams, charts, posters, UI mockups, infographics, and image-edit workflows, plus `scripts/png-qa.mjs` for PNG visual QA with bounded self-repair (registered in `typecheck:skill-scripts`).
+- **`fec-backend-requirements-handoff` skill:** frontend-to-backend handoff for UI data needs, user actions, states, permissions, business rules, uncertainties, and backend discussion points — without dictating implementation.
+- **`fec-web-video-presentation` skill:** recordable 16:9 step-driven web presentations from articles, scripts, lessons, and demos, with compact references, starter theme data, and a cross-platform Vite/React scaffold helper.
+- **Modular reference docs:** split several monolithic reference files into focused modules — `fec-e2e-testing` (e2e-ci-reporting / e2e-special-scenarios / e2e-visual-regression), `fec-legacy-to-modern-migration` (migration-execution-checklist / migration-strategy-and-mapping), `fec-performance-optimization` (framework-performance-patterns), `fec-react-project-standard` (react-project-structure / react-runtime-patterns / react-quality-patterns / react-performance-patterns), and `fec-vue3-project-standard` (vue3-project-structure / vue3-composables-routing / vue3-state-api-quality / vue3-performance-patterns). Each `SKILL.md` now points at the new focused references.
+- **Install coverage for the new skills:** `tests/install/image-generation-skill.test.ts`, `tests/install/drawio-studio-skill.test.ts`, expanded `tests/install/ui-design-intelligence.test.ts` (designRead, designDials, page-intent dial behavior) and `tests/install/end-to-end.test.ts` (new skill ids, taxonomy, relations).
+
+### Changed
+
+- **BREAKING — `fec-typescript-type-safety` renamed to `fec-typescript-project-standard`:** the skill directory, id, and metadata entry are renamed; type-safety content is preserved as `references/type-safety.md` inside the new skill, and a top-level `SKILL.md` covers TypeScript project standards (config, public API types, declarations, DTOs, generics). `agents/fec-typescript-reviewer.md` and all `skills/metadata.json` / `skills/relations.json` references were updated. **Migration:** replace every `fec-typescript-type-safety` reference (in agent / skill frontmatter, `relations.json`, eval queries, custom docs) with `fec-typescript-project-standard`.
+- **Skill taxonomy — new `project-standard` category:** the `project-standard` taxonomy was already declared in 2.6.0 metadata; this release populates it with the renamed TypeScript skill and aligns README skill tables across all 5 locales. `fec-monorepo-project-standard` remains in `project-evolution`/standard mix; the existing 7 categories are unchanged.
+- **Skill count:** 41 → 45 across README locales (en / zh-CN / zh-TW / ja-JP / ko-KR), `skills/metadata.json`, `.claude-plugin/marketplace.json` description, and `skills/eval_queries.json` trigger queries. README wording, project-structure docs, and example-prompts tables were re-tagged to label every capability entry by type (skill / agent / cmd).
+- **`fec-ui-design` enhancements:** added product-context reading, design dials (`visualTension`, `motionIntensity`, `informationDensity`, `mediaAuthenticity`, `contentPersuasion`), anti-generic UI guidance, and a visual-references strategy. `design-system.mjs` script, `style-archetypes.json`, `ux-quality-rules.json`, `design-intelligence.md`, and `pre-delivery-checklist.md` data were extended; multi-locale READMEs and project-structure docs were updated.
+- **`fec-motion-interaction` enhancements:** added context-aware motion-intensity guidance, aligning with `fec-ui-design` design dials.
+- **`fec-implement-from-design` enhancements:** added screenshot / section-level visual references alongside the existing Figma / Sketch / MasterGo / Pixso / 墨刀 / 摹客 sources.
+- **`fec-drawio-studio` lint hardening:** `diagram-lint` now forbids XML comments, unescaped ampersands and angle brackets, self-closing edge cells, missing root / layer cells, and warns when vertex labels contain HTML without the `html=1` style. New install tests cover `diagram-url` and `diagram-lint`.
+- **`fec-legacy-to-modern-migration`, `fec-tailwind-design-system`, `fec-responsive-layout`:** added Playwright-equivalent validation guidance so migration and visual-sensitive tasks build a before/after behavior checklist and pick the validation layer (Playwright / visual diff / typecheck / unit) matched to the change risk.
+- **Shared rules slim-down:** `templates/shared/rules/fec-*.md` were condensed to standing project-resident hard constraints. Productized guidance for UI design, Tailwind design systems, responsive layout, TypeScript modeling, error-handling framework internals, and rendering patterns now lives in their dedicated skills instead of being inlined into rules; `fec-i18n.md`, `fec-responsive-design.md`, `fec-typescript.md`, `fec-state-management.md`, `fec-design-system.md`, `fec-rendering-patterns.md`, `fec-error-handling.md`, `fec-ci-cd.md`, and `fec-refactoring.md` were all trimmed.
+- **Multilingual README sync:** the new "XML/Mermaid/CSV URL handoff" description for `fec-drawio-studio` and the new design-dial framing for `fec-ui-design` are reflected in all 5 locales. Old references to the removed `/fec-build-fix` slash command and `fec-build-fixer` agent were replaced with the real `/fec-debug` command and `fec-debugger` agent. `docs/example-prompts.md` (and its zh-CN mirror) now covers all 45 skills.
+- **Marketplace metadata:** `marketplace.json` description and `package.json` keywords updated to reflect the 45-skill surface; re-indented to the repository's prettier configuration.
+- **`fec-doc-sync` scope:** the doc-sync workflow continues to cover env notes, scripts, API / route notes, and deploy facts in addition to user-facing docs; example prompts, the `/fec-doc-sync` command doc, and `skills/metadata.json` align.
+
+### Removed
+
+- **`fec-typescript-type-safety` skill directory:** the legacy directory was removed; its content lives in `fec-typescript-project-standard` (`references/type-safety.md`). Update any custom rules, agents, or skills that referenced the old id.
+
+### Chore
+
+- **JSON metadata reformat:** `marketplace.json` and `skills/metadata.json` indentation / trailing-newline conventions normalized.
+- **Project-structure docs:** `docs/project-structure.md` and its `zh-CN` mirror updated to enumerate the new skills and reorganized reference modules.
+- **Install test coverage:** added `tests/install/image-generation-skill.test.ts` and `tests/install/drawio-studio-skill.test.ts`; existing end-to-end and metadata-consistency tests updated to assert the new skill ids, taxonomy, and relations.
+- **Skill-script typecheck:** `typecheck:skill-scripts` now also covers `skills/fec-image-generation/scripts/png-qa.mjs`.
+
+
+## [2.6.0] - 2026-06-07
+
+### Added
+
+- **`fec-alchemy` skill:** new project absorption workflow that extracts useful ideas from reference systems and redesigns them into original, project-native improvements; ships with `SKILL.md`, intake / absorption-plan templates, and reference docs covering methodology, originality, and licensing.
+- **`fec setup all` subcommand:** installs frontend-craft for every supported runtime in one shot, defaulting to the current project unless `--global` is passed; help text now distinguishes the terminal `fec setup` command from the in-assistant `/fec-init` slash command.
+- **`fec-debug-framework` in README skill tables:** the skill was already shipped in `skills/` but is now surfaced in every README locale and marketplace metadata.
+- **`scripts/sync-version.ts`:** propagates `package.json` version to `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (including the npm source pin), `openclaw.plugin.json`, and per-skill entries in `skills/metadata.json`. Run via `npm run sync:version`; wired into the `version` lifecycle script.
+- **Skill-pack script minification:** `pack-skills.ts` and `skill-packaging.ts` are now minified with esbuild during build, producing smaller standalone skill packages in `skill-packages/`.
+- **Reference docs for key skills:** added dedicated reference documents for `fec-debug-framework`, `fec-performance-optimization`, `fec-refactor-clean`, and `fec-validation-fix`, linked from the localized "详细参考" section of each `SKILL.md`.
+
+### Changed
+
+- **`fec-doc-sync` scope expansion:** the doc-sync workflow and skill descriptions now cover env notes, scripts, API/route notes, and deploy facts in addition to user-facing docs; example prompts, the `/fec-doc-sync` command doc, and `skills/metadata.json` were updated to match.
+- **Skill taxonomy — new `project-evolution` category:** added to the taxonomy allowlist (in addition to the existing `implementation-capability`, `testing`, `review-quality`, `design-ui`, `legacy-migration`, `maintenance-docs`); `fec-alchemy` lives here, and the README skill tables, marketplace keywords, and `tests/install/metadata-consistency.test.ts` allowlist were updated across all 5 locales.
+- **Skill count:** 40 → 41 across all README locales and `skills/metadata.json`.
+- **README install sections restructured:** the en / zh-CN / zh-TW / ja-JP / ko-KR READMEs were reorganized into 3 install options (down from 4), with numbered steps (1–6), `install --all` examples for both `--local` and `--global`, and a final "Preview / query" step that surfaces `dry-run` and `fec list`. Option 1 is now explicitly "Install the fec CLI globally" so the `npm install -g` step is unambiguous; `Claude Code Marketplace` moved to Option 3 to reflect its position among the paths.
+- **CLI setup help text:** clarified that `npm install -g` only installs the `fec` terminal command and that `--global` is required to write to the AI tool's global config; scripted all-runtime installs must use `install --all`, not `install all`.
+- **`SKILL.md` References localization:** the "References" section header is now rendered as `详细参考` (Detailed References) in every `SKILL.md` to match the existing Chinese-first documentation convention.
+- **`pnpm-lock.yaml`:** now tracked in version control — pnpm is the canonical package manager for the repo.
+- **Marketplace plugin source pin:** `marketplace.json` source entry now follows `package.json` version consistently via `sync-version.ts` instead of being edited by hand.
+- **CLI project setup command:** renamed the terminal project initialization shortcut from `fec init` / `frontend-craft init` to `fec setup` / `frontend-craft setup`; the in-assistant `/fec-init` slash command is unchanged. `src/install/cli.ts` help text, command dispatcher, and default install location updated; `tests/install/cli.test.ts` asserts the new `setup` command and that legacy `init` is rejected.
+
+### Fixed
+
+- **Plugin install command scope:** README, runtime docs, and marketplace descriptions now reference the `@bovinphang/frontend-craft` npm scope consistently; the previous `@frontend-craft` references (no scope) were misleading.
+
+### Removed
+
+- **CLI `init` command:** `init` is no longer accepted as a terminal CLI command and exits with "Unknown command: init"; use `setup` for local project setup.
+
+### Chore
+
+- **`SKILL.md` BOM cleanup:** removed the UTF-8 byte order mark (BOM, U+FEFF) from the first line of 23 `SKILL.md` files; the BOM was rendering as an unknown glyph in some editors and tooling.
+- **JSON metadata formatting:** normalized indentation and trailing-newline conventions in `marketplace.json` and `skills/metadata.json` after the `sync-version.ts` migration.
+- **`CONTRIBUTING` guide:** added scenario-specific check instructions (skill authoring, installer changes, runtime template changes, OpenClaw packaging) so contributors know which commands to run before opening a PR.
+- **Runtime docs:** added build and Marketplace troubleshooting notes to per-runtime install docs under `docs/runtimes/`.
+- **npm package scope migration:** published package is now `@bovinphang/frontend-craft`; install commands, `pack:skills` output paths, README badges, and OpenClaw staging paths were updated in lockstep.
 
 
 ## [2.5.0] - 2026-06-01
@@ -39,7 +115,7 @@ Project-facing release notes are maintained in English from 2.0.0 onward. Histor
 ### Added
 
 - **Debug workflow:** added `fec-debug` slash command with type-based routing, `fec-debugger` agent for complex diagnostic scenarios, and `fec-debug-framework` skill with a 5-step diagnostic methodology.
-- **6 new skills:** `fec-performance-optimization` (Core Web Vitals, memory leaks, performance budgets), `fec-source-driven-development` (evidence-based decisions with official-docs verification), `fec-state-management` (state architecture patterns), `fec-typescript-type-safety` (type safety enforcement), `fec-dependency-upgrade` (upgrade planning), `fec-responsive-layout` (responsive layout strategy), and `fec-tailwind-design-system` (Tailwind-based design system implementation).
+- **6 new skills:** `fec-performance-optimization` (Core Web Vitals, memory leaks, performance budgets), `fec-source-driven-development` (evidence-based decisions with official-docs verification), `fec-state-management` (state architecture patterns), `fec-typescript-project-standard` (TypeScript project standards and type safety), `fec-dependency-upgrade` (upgrade planning), `fec-responsive-layout` (responsive layout strategy), and `fec-tailwind-design-system` (Tailwind-based design system implementation).
 - **2 new integration skills:** `fec-api-integration` and `fec-motion-interaction`.
 - **Example prompts library:** added `docs/example-prompts.md` and `docs/zh-CN/example-prompts.md` with scenario-based prompt catalogs covering skills, agents, commands, design workflows, testing, maintenance, and runtime setup; linked from all README variants.
 - **UI design system generator:** added `design-system.mjs` generator with product rules, style archetypes, UX quality and Stack UI rules data packages; supports `--persist` and `--page` flags to write `MASTER.md` and page overrides.

package/CHANGELOG.zh-CN.md

@@ -8,6 +8,82 @@
 
 自 **2.0.0** 起，面向发布的说明以英文 `CHANGELOG.md` 为权威来源；历史条目可能保留最初撰写语言。
 
+## [2.7.0] - 2026-06-10
+
+### 新增
+
+- **`fec-drawio-studio` 技能**：可编辑 draw.io / diagrams.net 技术图工作流，涵盖官方 shape 查询、品牌符号、Graphviz 自动布局、多语言代码结构映射（TS / JS / Go / Python / Rust）、校验、导出兜底，并支持 `XML / Mermaid / CSV` URL 交付（`diagram-url --create`），可使用自托管 `baseUrl`、lightbox、暗色主题与 Windows `.url` 快捷方式。
+- **`fec-image-generation` 技能**：覆盖示意图、图表、海报、UI mockup、信息图与图像编辑流程，并提供 `scripts/png-qa.mjs` 进行有界自修复的 PNG 视觉 QA（已纳入 `typecheck:skill-scripts` 校验范围）。
+- **`fec-backend-requirements-handoff` 技能**：前端→后端需求交接，描述 UI 数据需求、用户操作、状态、权限、业务规则、不确定点和需要后端澄清的问题，不规定实现方式。
+- **`fec-web-video-presentation` 技能**：将文章、口播稿、课程和 demo 转为可录屏的 16:9 步进式网页演示，包含精简参考文档、starter theme 数据和跨平台 Vite/React 脚手架 helper。
+- **参考文档模块化拆分**：将多个技能的单体参考文档拆分为聚焦模块——`fec-e2e-testing`（e2e-ci-reporting / e2e-special-scenarios / e2e-visual-regression）、`fec-legacy-to-modern-migration`（migration-execution-checklist / migration-strategy-and-mapping）、`fec-performance-optimization`（framework-performance-patterns）、`fec-react-project-standard`（react-project-structure / react-runtime-patterns / react-quality-patterns / react-performance-patterns）、`fec-vue3-project-standard`（vue3-project-structure / vue3-composables-routing / vue3-state-api-quality / vue3-performance-patterns）；各 `SKILL.md` 同步指向新的聚焦参考。
+- **新技能的安装覆盖**：新增 `tests/install/image-generation-skill.test.ts`、`tests/install/drawio-studio-skill.test.ts`，并扩展 `tests/install/ui-design-intelligence.test.ts`（designRead、designDials、按页面意图拨盘行为）和 `tests/install/end-to-end.test.ts`（新技能 id、taxonomy、relations）。
+
+### 变更
+
+- **BREAKING — `fec-typescript-type-safety` 重命名为 `fec-typescript-project-standard`**：技能目录、id 与 metadata 条目已统一重命名；原 type-safety 内容作为 `references/type-safety.md` 收纳到新技能下，并新增顶层 `SKILL.md` 覆盖 TypeScript 项目规范（配置、对外 API 类型、声明文件、DTO、泛型）。`agents/fec-typescript-reviewer.md`、`skills/metadata.json`、`skills/relations.json` 中的引用已同步更新。**迁移指引**：将所有 `fec-typescript-type-safety` 引用（agent / skill frontmatter、`relations.json`、评测样例、自定义文档）替换为 `fec-typescript-project-standard`。
+- **Skill 分类 — `project-standard` 类别落地**：2.6.0 已在 metadata 中声明 `project-standard` 分类，本版本正式将重命名后的 TypeScript 技能归入该类，并同步各语言 README 技能表。原有 7 个分类保持不变。
+- **技能数量**：41 → 45，已同步到各语言 README（en / zh-CN / zh-TW / ja-JP / ko-KR）、`skills/metadata.json`、`.claude-plugin/marketplace.json` 描述与 `skills/eval_queries.json` 触发评测样例。README 文案、项目结构文档、示例提示表对每个能力条目按类型（skill / agent / cmd）重新打标。
+- **`fec-ui-design` 增强**：新增产品语境读取、设计拨盘（`visualTension`、`motionIntensity`、`informationDensity`、`mediaAuthenticity`、`contentPersuasion`）、反通用化 UI 引导与视觉参考策略；扩展 `design-system.mjs` 脚本、`style-archetypes.json`、`ux-quality-rules.json`、`design-intelligence.md` 与 `pre-delivery-checklist.md` 数据；同步更新多语言 README 与项目结构文档。
+- **`fec-motion-interaction` 增强**：新增 context-aware motion intensity 引导，与 `fec-ui-design` 设计拨盘对齐。
+- **`fec-implement-from-design` 增强**：在原有 Figma / Sketch / MasterGo / Pixso / 墨刀 / 摹客 基础上，新增 screenshot / section-level 视觉参考输入。
+- **`fec-drawio-studio` lint 强化**：`diagram-lint` 禁止 XML 注释、未转义 `&` 与尖括号、自闭合边单元格、缺失根 / 图层单元格，并对顶点标签内未带 `html=1` 样式的 HTML 内容发出警告。安装测试覆盖 `diagram-url` 与 `diagram-lint`。
+- **`fec-legacy-to-modern-migration`、`fec-tailwind-design-system`、`fec-responsive-layout`**：补充 Playwright 等效的验证指引，要求迁移与视觉敏感类任务构建前后行为清单并按风险选择合适的验证层（Playwright / 视觉 diff / typecheck / 单测）。
+- **Shared rules 精简**：`templates/shared/rules/fec-*.md` 收敛为项目常驻的硬约束；UI 设计、Tailwind 设计系统、响应式布局、TypeScript 建模、错误处理框架内部细节、渲染模式等产品化内容转由对应技能承载；`fec-i18n.md`、`fec-responsive-design.md`、`fec-typescript.md`、`fec-state-management.md`、`fec-design-system.md`、`fec-rendering-patterns.md`、`fec-error-handling.md`、`fec-ci-cd.md`、`fec-refactoring.md` 同步精简。
+- **多语言 README 同步**：在 5 个语言版本中补齐 `fec-drawio-studio` 的「XML/Mermaid/CSV URL 交付」描述与 `fec-ui-design` 的设计拨盘表述；将已移除的 `/fec-build-fix` 斜杠命令与 `fec-build-fixer` agent 引用替换为 `/fec-debug` 与 `fec-debugger`；`docs/example-prompts.md` 及其 zh-CN 镜像已覆盖全部 45 个技能。
+- **Marketplace 元数据**：`marketplace.json` 描述与 `package.json` keywords 同步反映 45 个技能面，并按仓库 prettier 配置重新缩进。
+- **`fec-doc-sync` 范围**：继续保持对 env 说明、脚本、API / 路由说明与部署事实的覆盖；示例提示、`/fec-doc-sync` 命令文档与 `skills/metadata.json` 已对齐。
+
+### 移除
+
+- **`fec-typescript-type-safety` 技能目录**：原目录已移除；其内容迁移至 `fec-typescript-project-standard` 的 `references/type-safety.md`。如自定义规则、agent、skill 引用了旧 id，请同步更新。
+
+### Chore
+
+- **JSON 元数据重排**：`marketplace.json` 与 `skills/metadata.json` 缩进与末尾换行风格统一。
+- **项目结构文档**：`docs/project-structure.md` 及其 `zh-CN` 镜像同步列举新技能与重组后的参考模块。
+- **安装测试覆盖**：新增 `tests/install/image-generation-skill.test.ts`、`tests/install/drawio-studio-skill.test.ts`；现有 end-to-end 与 metadata-consistency 测试同步更新以断言新技能 id、taxonomy 与 relations。
+- **技能脚本类型检查**：`typecheck:skill-scripts` 同时覆盖 `skills/fec-image-generation/scripts/png-qa.mjs`。
+
+
+## [2.6.0] - 2026-06-07
+
+### 新增
+
+- **`fec-alchemy` 技能**：新增「项目吸收与原创化融合」工作流，从参考系统提取可借鉴的设计并以项目原生方式重构为原创能力；随附 `SKILL.md`、intake / absorption-plan 模板，以及涵盖方法论、原创性、许可证的参考文档。
+- **`fec setup all` 子命令**：一键为所有受支持的 runtime 安装 frontend-craft，默认安装到当前项目，除非显式传入 `--global`；帮助文本现在区分终端 `fec setup` 命令与 AI 助手内的 `/fec-init` 斜杠命令。
+- **README 技能表补全 `fec-debug-framework`**：该技能此前已在 `skills/` 中提供，现统一收录到各语言 README 技能表与 marketplace 元数据中。
+- **`scripts/sync-version.ts`**：将 `package.json` 的版本号同步到 `.claude-plugin/plugin.json`、`.claude-plugin/marketplace.json`（包含 npm source 钉版）、`openclaw.plugin.json`，以及 `skills/metadata.json` 的每条技能记录。可通过 `npm run sync:version` 执行；已接入 `version` 生命周期脚本。
+- **技能打包脚本压缩**：`pack-skills.ts` 与 `skill-packaging.ts` 在构建期通过 esbuild 压缩，输出到 `skill-packages/` 的独立技能包体积更小。
+- **关键技能参考文档**：为 `fec-debug-framework`、`fec-performance-optimization`、`fec-refactor-clean`、`fec-validation-fix` 新增独立参考文档，从各 `SKILL.md` 本地化后的「详细参考」一节链接。
+
+### 变更
+
+- **`fec-doc-sync` 同步范围扩展**：文档同步工作流与技能描述现在覆盖环境变量说明、脚本、接口/路由说明与部署文档，不再局限于面向用户的文档；示例提示词、`/fec-doc-sync` 命令文档以及 `skills/metadata.json` 同步更新。
+- **技能分类新增 `project-evolution`**：在原 `implementation-capability` / `testing` / `review-quality` / `design-ui` / `legacy-migration` / `maintenance-docs` 之外新增 `project-evolution`，`fec-alchemy` 归入此类；各语言 README 技能表、marketplace 关键词以及 `tests/install/metadata-consistency.test.ts` 白名单同步更新。
+- **技能数量**：40 → 41，已同步到各语言 README 与 `skills/metadata.json`。
+- **README 安装章节重构**：en / zh-CN / zh-TW / ja-JP / ko-KR 五种语言的 README 重新组织为 3 个安装选项（从 4 个收敛），步骤编号 1–6，并补充 `--local` / `--global` 两种场景下的 `install --all` 示例，新增「Preview / query」步骤展示 `dry-run` 与 `fec list`。「选项 1」改为「全局安装 fec CLI」，使 `npm install -g` 步骤不再有歧义；Claude Code Marketplace 下移至「选项 3」。
+- **CLI setup 帮助文本**：明确说明 `npm install -g` 仅安装终端 `fec` 命令，若要写入 AI 工具的全局配置需额外传 `--global`；脚本化的全 runtime 安装必须使用 `install --all`，不能使用 `install all`。
+- **`SKILL.md` References 本地化**：每份 `SKILL.md` 的「References」章节标题统一为「详细参考」，与既有中文优先的文档约定一致。
+- **`pnpm-lock.yaml` 纳入版本控制**：pnpm 已成为仓库规范化的包管理器。
+- **Marketplace 插件 source 钉版**：`marketplace.json` 的 source 字段现由 `sync-version.ts` 与 `package.json` 保持一致，无需手工修改。
+- **CLI 项目 setup 命令重命名**：终端里的项目初始化快捷命令从 `fec init` / `frontend-craft init` 重命名为 `fec setup` / `frontend-craft setup`；AI 助手内的 `/fec-init` 斜杠命令保持不变。`src/install/cli.ts` 的帮助文本、命令分发与默认安装位置同步更新；`tests/install/cli.test.ts` 已断言新 `setup` 命令并校验旧 `init` 会被拒绝。
+
+### 修复
+
+- **插件安装命令作用域**：README、runtime 文档与 marketplace 描述现在统一引用 `@bovinphang/frontend-craft` npm 作用域；先前未带作用域的 `@frontend-craft` 引用已修正。
+
+### 移除
+
+- **CLI `init` 命令**：终端 CLI 不再接受 `init`，遇到时直接退出并提示「Unknown command: init」；本地项目 setup 请改用 `setup`。
+
+### 工程
+
+- **`SKILL.md` BOM 清理**：从 23 份 `SKILL.md` 的首行移除 UTF-8 字节顺序标记（BOM, U+FEFF），避免部分编辑器与工具把首字符渲染为不可识别字形。
+- **JSON 元数据格式统一**：`sync-version.ts` 迁移后，统一 `marketplace.json` 与 `skills/metadata.json` 的缩进与末尾换行规范。
+- **`CONTRIBUTING` 贡献指南**：补充分场景的检查指引（技能编写、安装器变更、runtime 模板变更、OpenClaw 打包），让贡献者在提 PR 前明确应执行哪些命令。
+- **Runtime 文档**：在 `docs/runtimes/` 的各 runtime 安装文档中补充构建与 Marketplace 排错说明。
+- **npm 包作用域迁移**：发布包更名为 `@bovinphang/frontend-craft`；安装命令、`pack:skills` 输出路径、README 徽标与 OpenClaw staging 路径同步刷新。
 
 
 ## [2.5.0] - 2026-06-01
@@ -38,7 +114,7 @@
 ### 新增
 
 - **调试工作流**：新增 `/fec-debug` 斜杠命令（按类型自动路由）、`fec-debugger` agent（复杂诊断场景）和 `fec-debug-framework` skill（5 步诊断方法论）。
-- **6 个新技能**：`fec-performance-optimization`（Core Web Vitals、内存泄漏、性能预算）、`fec-source-driven-development`（基于官方文档验证的证据驱动决策）、`fec-state-management`（状态架构模式）、`fec-typescript-type-safety`（类型安全强化）、`fec-dependency-upgrade`（依赖升级规划）、`fec-responsive-layout`（响应式布局策略）和 `fec-tailwind-design-system`（基于 Tailwind 的设计系统实现）。
+- **6 个新技能**：`fec-performance-optimization`（Core Web Vitals、内存泄漏、性能预算）、`fec-source-driven-development`（基于官方文档验证的证据驱动决策）、`fec-state-management`（状态架构模式）、`fec-typescript-project-standard`（TypeScript 项目规范与类型安全）、`fec-dependency-upgrade`（依赖升级规划）、`fec-responsive-layout`（响应式布局策略）和 `fec-tailwind-design-system`（基于 Tailwind 的设计系统实现）。
 - **2 个新集成技能**：`fec-api-integration` 和 `fec-motion-interaction`。
 - **示例提示库**：新增 `docs/example-prompts.md` 和 `docs/zh-CN/example-prompts.md`，涵盖技能、Agent、命令、设计工作流、测试、维护和运行时配置等场景化提示目录；已在所有 README 变体中添加链接。
 - **UI 设计系统生成器**：新增 `design-system.mjs` 生成器，包含产品规则、风格原型、UX 质量和 Stack UI 规则数据包；支持 `--persist` 和 `--page` 标志生成 `MASTER.md` 和页面覆盖。

package/CONTRIBUTING.md

@@ -10,15 +10,19 @@ Thanks for your interest in `frontend-craft`. Issues, pull requests, documentati
 - Git.
 - Run `npm install` before local development.
 
-Useful checks:
+For documentation-only changes, focus on the language and documentation policy plus the pull request checklist. For skill or OpenClaw changes, use the focused sections below before opening a pull request.
+
+Quick checks (minimum recommended):
 
 ```bash
-npm test
-npm run pack:skills
-npm run check:skills-publish
-npm run typecheck:openclaw
+npm test                         # General validation
+npm run pack:skills              # Skill changes
+npm run check:skills-publish     # Skill changes
+npm run typecheck:openclaw       # OpenClaw changes
 ```
 
+See the NPM Scripts section and Pull Request Checklist for complete scenario-specific checks.
+
 ## Project Structure
 
 ```
@@ -112,7 +116,7 @@ The canonical skill sources live under `skills/<skill-id>/`. Do not edit generat
 ```bash
 npm run pack:skills            # Build one standalone package per skill
 npm run check:skills-publish   # Verify package metadata, index, and copied references
-npm run pack:all               # Full test + OpenClaw package + standalone skill packages
+npm run pack:all               # Build + test + OpenClaw package + standalone skill packages
 ```
 
 `npm run pack:skills` writes `skill-packages/<skill-id>/` with `SKILL.md`, only the referenced `references/` files, `metadata.json`, `package.json`, `README.md`, and `LICENSE`. It also writes `skill-packages/index.json` for platform crawlers and release automation.
@@ -131,7 +135,7 @@ Use `package.json` scripts as the public development entrypoints.
 | Script                         | Purpose                                                                          |
 | ------------------------------ | -------------------------------------------------------------------------------- |
 | `npm run clean`                | Remove `dist/`.                                                                  |
-| `npm run typecheck`            | Run TypeScript checking for the main project with `tsconfig.json`.               |
+| `npm run typecheck`            | Run main TypeScript checks plus checked skill support scripts.                   |
 | `npm run build`                | Run `clean`, `typecheck`, and bundle CLI/hooks via `scripts/build-dist.ts`.      |
 | `npm test`                     | Build, then run the curated `node:test` suite with `tsx`.                        |
 | `npm run build:openclaw`       | Build the main project, then bundle OpenClaw runtime output.                     |
@@ -139,9 +143,9 @@ Use `package.json` scripts as the public development entrypoints.
 | `npm run typecheck:openclaw`   | Run TypeScript checking for OpenClaw with `tsconfig.openclaw.json`.              |
 | `npm run check:openclaw-dist`  | Verify the generated OpenClaw dist output.                                       |
 | `npm run pack:openclaw`        | Build, verify, and package the OpenClaw plugin.                                  |
-| `npm run pack:skills`          | Build standalone packages under `skill-packages/`.                               |
-| `npm run check:skills-publish` | Build, then verify standalone skill package metadata and copied files.           |
-| `npm run pack:all`             | Run tests, package OpenClaw, package skills, and verify skill publishing output. |
+| `npm run pack:skills`          | Build first, then create standalone packages under `skill-packages/`.            |
+| `npm run check:skills-publish` | Build first, then verify standalone skill package metadata and copied files.     |
+| `npm run pack:all`             | Build, run tests, package OpenClaw, package skills, and verify skill output.     |
 | `npm run sync:version`         | Sync package version metadata across release manifests.                          |
 | `npm run version`              | Run `sync:version`, then stage versioned manifests for npm version workflows.    |
 | `npm run prepack`              | Build before `npm pack`.                                                         |
@@ -161,6 +165,7 @@ Maintenance scripts live under `scripts/` and run from source with `tsx`; they a
 | ------------------------------------------ | ------------------------------------ |
 | `scripts/audit-skills.ts`                  | Skill size and trigger-overlap audit |
 | `scripts/build-dist.ts`                    | CLI and runtime hook bundler         |
+| `scripts/clean-dist.mjs`                   | Remove generated `dist/` output      |
 | `scripts/sync-codex-agents-toml.ts`        | Sync Codex agents configuration      |
 | `scripts/sync-version.ts`                  | Sync release version metadata        |
 | `scripts/pack-skills.ts`                   | Standalone skill package builder     |

package/CONTRIBUTING.zh-CN.md

@@ -10,15 +10,19 @@
 - Git。
 - 本地开发前运行 `npm install`。
 
-常用校验：
+仅修改文档时，重点阅读语言与文档策略以及 Pull Request 自检。修改 skill 或 OpenClaw 时，请在提交 PR 前参考下方对应章节。
+
+快速自检（最小推荐）：
 
 ```bash
-npm test
-npm run pack:skills
-npm run check:skills-publish
-npm run typecheck:openclaw
+npm test                         # 通用校验
+npm run pack:skills              # Skill 变更
+npm run check:skills-publish     # Skill 变更
+npm run typecheck:openclaw       # OpenClaw 变更
 ```
 
+完整的场景化命令请见后文 npm scripts 与 Pull Request 自检。
+
 ## 项目结构
 
 ```
@@ -112,7 +116,7 @@ Skill 的权威源文件位于 `skills/<skill-id>/`。不要手动修改 `skill-
 ```bash
 npm run pack:skills            # 为每个 skill 生成独立发布包
 npm run check:skills-publish   # 校验包元数据、索引和引用文件
-npm run pack:all               # 完整测试 + OpenClaw 包 + 独立 skill 包
+npm 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`，供平台索引或发布自动化使用。
@@ -131,7 +135,7 @@ npm run pack:all               # 完整测试 + OpenClaw 包 + 独立 skill 包
 | Script                         | 用途                                                                       |
 | ------------------------------ | -------------------------------------------------------------------------- |
 | `npm run clean`                | 删除 `dist/`。                                                             |
-| `npm run typecheck`            | 使用 `tsconfig.json` 对主项目做 TypeScript 类型检查。                      |
+| `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 输出。                               |
@@ -139,9 +143,9 @@ npm run pack:all               # 完整测试 + OpenClaw 包 + 独立 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 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` 前构建。                                                     |
@@ -161,6 +165,7 @@ npm run pack:all               # 完整测试 + OpenClaw 包 + 独立 skill 包
 | ------------------------------------------ | ------------------------------ |
 | `scripts/audit-skills.ts`                  | Skill 大小与触发描述重叠度审计 |
 | `scripts/build-dist.ts`                    | CLI 与 runtime hook 打包       |
+| `scripts/clean-dist.mjs`                   | 删除生成的 `dist/` 输出        |
 | `scripts/sync-codex-agents-toml.ts`        | 同步 Codex agents 配置         |
 | `scripts/sync-version.ts`                  | 同步发布版本元数据             |
 | `scripts/pack-skills.ts`                   | 独立 skill 包构建              |